FramePeek

A macOS application for inspecting video and audio files with metadata analysis, bitrate visualization, GOP structure analysis, color analysis, and keyframe detection.

framepeek-demo-2.mp4

Features

Video Analysis

• Comprehensive Metadata: Container format, codec information, resolution, frame rate, pixel aspect ratio, and display aspect ratio
• Color & HDR Information: Color space, chroma subsampling, bit depth, color primaries, transfer functions, and HDR format detection (Dolby Vision, HDR10, HLG, PQ)
• Codec Support: HEVC (H.265), AVC (H.264), AV1, VP9, and more with detailed configuration parsing
• Resolution Categories: Automatic classification (4K UHD, Full HD, etc.)

Audio Analysis

• Multi-Track Support: Detailed information for all audio tracks
• Track Properties: Codec, channel layout, sample rate, bitrate, and language information
• Codec Detection: AAC, AC-3, E-AC-3, MP3, Opus, and more

Bitrate Analysis

• Interactive Charts: Bitrate visualization with Swift Charts
• Flexible Sampling: Automatic, fixed interval, or per-frame sampling modes
• Visualization Modes: Aggregate bitrate by second, frame, or GOP (Group of Pictures)
• Progressive Updates: Real-time bitrate analysis with streaming updates
• Performance Optimized: Efficient frame extraction with configurable accuracy settings and LTTB downsampling
• Timeline Zoom: Interactive timeline for zooming into specific time ranges

GOP Structure Analysis

• Frame-Type Timeline: I/P/B frame visualization with per-GOP details
• GOP Heatmap: Size and structure heatmap with viewport culling for large files
• On-Demand Frame Details: Per-frame size and type extraction with LRU caching

Keyframe Detection

• Thumbnail Strip: Horizontal scrollable strip of keyframe thumbnails for quick navigation
• Sync Sample Detection: Identifies I-frames (intra-coded frames) without decoding
• GOP Interval Display: Shows Group of Pictures intervals for each keyframe

Color & Exposure Analysis

• Scopes: Vectorscope, waveform scope, and RGB histogram
• Color Temperature & Brightness: CCT and brightness charts over time
• HDR Analysis: Dolby Vision configuration details and HDR content classification

Audio Waveforms & A/V Sync

• Per-Track Waveforms: Peak waveform visualization for every audio track
• Sync Analysis: Audio/video timestamp drift detection

Loudness (EBU R128)

• Integrated Loudness: ITU-R BS.1770-4 gated measurement in LUFS with R128 compliance badge
• True Peak: 4x-oversampled inter-sample peak detection in dBTP
• Loudness Range: EBU Tech 3342 LRA plus momentary/short-term maxima
• Short-Term Chart: 3-second loudness over time with the -23 LUFS target line

HLS Ladder Inspection

• Manifest Parsing: RFC 8216 multivariant and media playlists, local folders or remote URLs
• Declared vs Measured: Per-variant peak/average segment bitrate compared against BANDWIDTH and AVERAGE-BANDWIDTH
• QC Findings: Segment duration compliance, cross-variant keyframe alignment, codec verification, ladder shape checks, and DRM detection, grouped by severity

Container Inspector

• Atom/Box Tree: Browse MP4/MOV container structure with size breakdowns

Video Player

• Built-in Player: Play videos with AVPlayer integration
• Statistics Overlay: Real-time display of resolution, frame rate, current time, and bitrate
• Customizable Controls: Toggle controls, auto-play, and mute settings

CLI Tool

• Command-line interface for batch processing and automation
• JSON, text, and CSV output formats
• All analysis capabilities available via CLI

MCP Server

• AI agent integration: framepeek-cli mcp runs a Model Context Protocol server on stdio
• Tools: analyze_media (structured results), media_summary (cheap metadata call), inspect_container (atom tree), inspect_hls_ladder (streaming QC findings)

REST API

• Embedded HTTP server for remote analysis
• Start/stop from the Server tab in the app
• Job queue with progress tracking

System Requirements

• macOS: 15.2 (Sequoia) or later
• Xcode: 16.2 or later (for building from source)

Installation

Download (recommended)

Grab the latest signed .dmg from the Releases page, open it, and drag FramePeek to /Applications. The CLI is published as a separate framepeek-cli-<version>.tar.gz on the same release.

Building from Source

1. Clone the repository:

   git clone https://github.com/oscnord/FramePeek.git
   cd FramePeek

2. Open the project:

   open FramePeek/FramePeek.xcodeproj

3. Build and run:

   • Select your target Mac in Xcode
   • Press Cmd+R to build and run

Usage

Opening Files

1. File Dialog: Click the "Open…" button in the toolbar or press Cmd+O
2. Drag and Drop: Drag a video or audio file onto the main window
3. Supported Formats: MP4, MOV, AVI, MPEG, and other common media formats supported by AVFoundation

CLI Usage

# Basic metadata
framepeek-cli video.mp4 --info --pretty

# All analyses
framepeek-cli video.mp4 --all --pretty

# Bitrate as CSV
framepeek-cli video.mp4 --bitrate --format csv

# EBU R128 loudness
framepeek-cli video.mp4 --loudness --pretty

# Multiple files
framepeek-cli *.mp4 --info --parallel

MCP Server (AI agents)

Two ways to connect:

# stdio: the client spawns the CLI itself
claude mcp add framepeek -- framepeek-cli mcp

# HTTP: connect to the running app (start the server in the Server tab)
claude mcp add --transport http framepeek http://127.0.0.1:8080/mcp

The app is sandboxed, so over HTTP the path-based tools can only read files the app has access to (Downloads, or files previously opened in FramePeek); URL-based tools like inspect_hls_ladder are unrestricted. The stdio CLI transport has no sandbox — prefer it for agents working across arbitrary local paths. The same applies to the REST API's /analyze/path.

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "framepeek": { "command": "framepeek-cli", "args": ["mcp"] }
  }
}

Agents can then call media_summary for a quick look at any local file, analyze_media for full structured results (bitrate, GOP, loudness, …), inspect_container for the MP4/MOV atom tree, and inspect_hls_ladder to QC an HLS ladder by path or URL.

REST API

1. Click "Server" in the sidebar
2. Click "Start Server"
3. Use the API at http://127.0.0.1:8080

See bruno/ folder for a Bruno collection to test the API.

Keyboard Shortcuts

• Cmd+O: Open file dialog
• Cmd+I: Toggle inspector panel
• Cmd+T: New tab
• Cmd+,: Open settings

Architecture

FramePeek follows a clean architecture pattern:

• UI Layer: SwiftUI views with @MainActor ViewModels
• Business Logic: Pure utility functions for parsing and analysis
• Data Layer: AVFoundation and CoreMedia for media access
• Concurrency: Swift Concurrency (async/await) for all async operations

Contributing

Contributions are welcome! Please see instructions.md for detailed information about the codebase structure and contribution guidelines.

License

This project is licensed under the MIT License.