内容
# FramePeek
[](https://github.com/oscnord/FramePeek/actions/workflows/release.yml)
一款用于检查视频和音频文件的macOS应用程序，提供元数据分析、比特率可视化、GOP结构分析、色彩分析和关键帧检测等功能。
https://github.com/user-attachments/assets/bbd946b5-e3d0-4659-8169-be47a73d1ab8
## 功能特点
### 视频分析
- **全面的元数据**：容器格式、编解码器信息、分辨率、帧率、像素纵横比和显示纵横比
- **色彩和HDR信息**：色彩空间、色度亚采样、比特深度、色彩原色、传输函数和HDR格式检测（Dolby Vision、HDR10、HLG、PQ）
- **编解码器支持**：HEVC（H.265）、AVC（H.264）、AV1、VP9等，支持详细的配置解析
- **分辨率分类**：自动分类（4K UHD、Full HD等）
### 音频分析
- **多音轨支持**：支持所有音轨的详细信息
- **音轨属性**：编解码器、通道布局、采样率、比特率和语言信息
- **编解码器检测**：AAC、AC-3、E-AC-3、MP3、Opus等
### 比特率分析
- **交互式图表**：使用Swift Charts进行比特率可视化
- **灵活的采样**：自动、固定间隔或逐帧采样模式
- **可视化模式**：按秒、帧或GOP（图片组）聚合比特率
- **渐进式更新**：实时比特率分析，支持流式更新
- **性能优化**：高效的帧提取，支持可配置的精度设置和LTTB降采样
- **时间线缩放**：交互式时间线，支持缩放特定时间范围
### GOP结构分析
- **帧类型时间线**：I/P/B帧可视化，支持每GOP的详细信息
- **GOP热图**：大小和结构热图，支持大文件的视口剔除
- **按需帧详细信息**：支持每帧大小和类型提取，带有LRU缓存
### 关键帧检测
- **缩略图条**：水平滚动的关键帧缩略图条，支持快速导航
- **同步样本检测**：无需解码即可识别I帧（帧内编码帧）
- **GOP间隔显示**：显示每个关键帧的GOP间隔
### 色彩和曝光分析
- **范围**：矢量范围、波形范围和RGB直方图
- **色温和亮度**：色彩温度和亮度图表，支持随时间变化的显示
- **HDR分析**：Dolby Vision配置详细信息和HDR内容分类
### 音频波形和音视频同步
- **每音轨波形**：每个音频音轨的峰值波形可视化
- **同步分析**：音频/视频时间戳漂移检测
### 响度（EBU R128）
- **集成响度**：ITU-R BS.1770-4门控测量，单位为LUFS，支持R128合规徽章
- **真实峰值**：4倍过采样帧间峰值检测，单位为dBTP
- **响度范围**：EBU Tech 3342 LRA，支持短时/长期最大值
- **短时图表**：3秒响度随时间变化，支持-23 LUFS目标线
### HLS阶梯检查
- **清单解析**：RFC 8216多变体和媒体播放列表，支持本地文件夹或远程URL
- **声明 vs 测量**：每个变体的峰值/平均分段比特率，与BANDWIDTH和AVERAGE-BANDWIDTH比较
- **质量控制发现**：分段持续时间合规性、跨变体关键帧对齐、编解码器验证、阶梯形状检查和DRM检测，按严重性分组
### 容器检查器
- **原子/盒树**：浏览MP4/MOV容器结构，支持大小明细
### 视频播放器
- **内置播放器**：使用AVPlayer集成播放视频
- **统计信息叠加层**：实时显示分辨率、帧率、当前时间和比特率
- **可自定义控件**：切换控件、自动播放和静音设置
### 命令行工具
- **命令行接口**：用于批处理和自动化
- **JSON、文本和CSV输出格式**：支持多种输出格式
- **所有分析能力均可通过CLI使用**
### MCP服务器
- **AI代理集成**：`framepeek-cli mcp`在标准输入/输出上运行Model Context Protocol服务器
- **工具**：`analyze_media`（结构化结果）、`media_summary`（快速元数据调用）、`inspect_container`（原子树）、`inspect_hls_ladder`（流媒体质量控制发现）
### REST API
- **嵌入式HTTP服务器**：用于远程分析
- **从应用程序的服务器选项卡启动/停止服务器**
- **作业队列，支持进度跟踪**
## 系统要求
- **macOS**：15.2（Sequoia）或更高版本
- **Xcode**：16.2或更高版本（用于从源代码构建）
## 安装
### 下载（推荐）
从[发布页面](https://github.com/oscnord/FramePeek/releases/latest)获取最新的签名`.dmg`文件，打开它并将**FramePeek**拖到`/Applications`文件夹。命令行工具作为单独的`framepeek-cli-<version>.tar.gz`发布在同一版本页面。
### 从源代码构建
1. **克隆仓库**：
```bash
git clone https://github.com/oscnord/FramePeek.git
cd FramePeek
```
2. **打开项目**：
```bash
open FramePeek/FramePeek.xcodeproj
```
3. **构建和运行**：
- 在Xcode中选择目标Mac
- 按`Cmd+R`构建和运行
## 使用
### 打开文件
1. **文件对话框**：点击工具栏中的"打开…"按钮或按`Cmd+O`
2. **拖放**：将视频或音频文件拖放到主窗口
3. **支持的格式**：AVFoundation支持的MP4、MOV、AVI、MPEG等常见媒体格式
### 命令行工具使用
```bash
# 基本元数据
framepeek-cli video.mp4 --info --pretty
# 所有分析
framepeek-cli video.mp4 --all --pretty
# 比特率以CSV格式输出
framepeek-cli video.mp4 --bitrate --format csv
# EBU R128响度
framepeek-cli video.mp4 --loudness --pretty
# 多个文件
framepeek-cli *.mp4 --info --parallel
```
### MCP服务器（AI代理）
连接方式有两种：
```bash
# 标准输入/输出：客户端自行启动CLI
claude mcp add framepeek -- framepeek-cli mcp
# HTTP：连接到正在运行的应用程序（在服务器选项卡中启动服务器）
claude mcp add --transport http framepeek http://127.0.0.1:8080/mcp
```
应用程序被沙盒化，因此通过HTTP，基于路径的工具只能读取应用程序有权访问的文件（下载或之前在FramePeek中打开的文件）；而基于URL的工具（如`inspect_hls_ladder`）则不受限制。标准输入/输出CLI传输方式没有沙盒限制 - 建议用于跨任意本地路径工作的代理。同样适用于REST API的`/analyze/path`。
克劳德桌面版（`claude_desktop_config.json`）：
```json
{
"mcpServers": {
"framepeek": { "command": "framepeek-cli", "args": ["mcp"] }
}
}
```
代理可以调用`media_summary`快速查看任意本地文件、`analyze_media`获取完整结构化结果（比特率、GOP、响度等）、`inspect_container`获取MP4/MOV原子树，以及`inspect_hls_ladder`通过路径或URL检查HLS阶梯。
### REST API
1. 点击侧边栏中的"服务器"
2. 点击"启动服务器"
3. 在`http://127.0.0.1:8080`使用API
参见`bruno/`文件夹中的Bruno集合以测试API。
### 快捷键
- `Cmd+O`：打开文件对话框
- `Cmd+I`：切换检查器面板
- `Cmd+T`：新建标签页
- `Cmd+,`：打开设置
## 架构
FramePeek遵循干净的架构模式：
- **UI层**：SwiftUI视图与`@MainActor`视图模型
- **业务逻辑**：用于解析和分析的纯实用函数
- **数据层**：AVFoundation和CoreMedia用于媒体访问
- **并发**：Swift并发（`async`/`await`）用于所有异步操作
## 贡献
欢迎贡献！请参阅[instructions.md](instructions.md)获取有关代码库结构和贡献指南的详细信息。
## 许可证
该项目在[MIT License](LICENSE)下获得许可。
