Rendiff Probe

Professional Video Analysis API & CLI - Powered by FFprobe

A production-ready REST API and CLI tool for comprehensive video/audio file analysis, built on top of FFprobe with 19 professional QC categories and 26 content analyzers covering 121 industry-standard parameters.

Acknowledgements

Rendiff Probe uses FFprobe from the FFmpeg project as its core media analysis engine. FFprobe is a powerful multimedia stream analyzer that provides detailed information about media files.

FFprobe is part of the FFmpeg Project
FFprobe is licensed under the LGPL/GPL license
This project wraps FFprobe functionality with enhanced QC analysis, REST API, and CLI interfaces

We are grateful to the FFmpeg community for developing and maintaining such a robust media analysis tool.

Features

Core Capabilities

Comprehensive FFprobe Analysis: Full format, stream, frame, and packet analysis via FFprobe
121 Industry-Standard QC Parameters: Complete broadcast and streaming quality control
26 Parallel Content Analyzers: Real-time analysis using FFmpeg filters (signalstats, idet, astats, etc.)
REST API (rendiff-probe): HTTP interface for video analysis
CLI Tool (rendiffprobe-cli): Command-line tool for local analysis
GraphQL API: Flexible query interface for advanced integrations
URL & HLS Analysis: Direct URL probing and HLS stream analysis
Batch Processing: Process multiple files/URLs in parallel
WebSocket Progress: Real-time progress updates for long operations
LLM-Powered Insights: AI-generated professional analysis reports
Docker Ready: Production-ready containerized deployment
SQLite Embedded: Zero-configuration database
Valkey/Redis Caching: High-performance result caching

Quality Control Analysis

Professional broadcast and streaming QC analysis covering:

Header/Format Analysis: Container validation, codec profiles, resolution, frame rate, bit depth, endianness Video Quality: Baseband analysis (YMIN/YMAX/YAVG), gamut checking, blockiness, blurriness, noise, line errors Video Content: Black frames, freeze frames, letterboxing, color bars, safe areas, field dominance, temporal complexity Audio Analysis: EBU R128 loudness, clipping, silence, phase correlation, channel mapping, frequency analysis Broadcast Compliance: HDR (HDR10/Dolby Vision/HLG), MXF validation, IMF compliance, transport stream analysis, timecode continuity Safety & Accessibility: PSE flash detection, AFD analysis, stream disposition, data integrity

Quick Start

Prerequisites

Docker 24.0+ with Docker Compose (for API)
Go 1.24+ (for CLI)
FFprobe installed (for CLI)
2GB RAM minimum (4GB recommended)

Installation

# Clone the repository
git clone https://github.com/rendiffdev/rendiff-probe.git
cd rendiff-probe

# Quick start API (development mode)
make quick

# Or build CLI for local use
go build -o rendiffprobe-cli ./cmd/rendiffprobe-cli

Using the CLI (`rendiffprobe-cli`)

# Analyze a video file with full QC report
rendiffprobe-cli analyze video.mp4 --format report

# Get JSON output for automation
rendiffprobe-cli analyze video.mp4 --format json --output result.json

# Quick file info
rendiffprobe-cli info video.mp4

# List all QC categories
rendiffprobe-cli categories

Using the API (`rendiff-probe`)

Your API is now running at http://localhost:8080

# Check health
curl http://localhost:8080/health

# Expected response:
{
  "status": "healthy",
  "service": "rendiff-probe",
  "version": "2.0.0",
  "powered_by": "FFprobe (FFmpeg)",
  "features": {
    "file_probe": true,
    "url_probe": true,
    "hls_analysis": true,
    "batch_processing": true,
    "websocket": true,
    "graphql": true,
    "llm_insights": true
  },
  "qc_tools": ["AFD Analysis", "Dead Pixel Detection", ...],
  "ffprobe_validated": true
}

API Reference

Health Check

GET /health

Returns service health status and available QC tools.

Response:

{
  "status": "healthy",
  "service": "rendiff-probe",
  "powered_by": "FFprobe (FFmpeg)",
  "qc_tools": [
    "AFD Analysis",
    "Dead Pixel Detection",
    "PSE Flash Analysis",
    "HDR Analysis",
    "Audio Wrapping Analysis",
    "Endianness Detection",
    "Codec Analysis",
    "Container Validation",
    "Resolution Analysis",
    "Frame Rate Analysis",
    "Bitdepth Analysis",
    "Timecode Analysis",
    "MXF Analysis",
    "IMF Compliance",
    "Transport Stream Analysis",
    "Content Analysis",
    "Enhanced Analysis",
    "Stream Disposition Analysis",
    "Data Integrity Analysis"
  ],
  "ffprobe_validated": true
}

Analyze File

POST /api/v1/probe/file
Content-Type: multipart/form-data

Upload a video/audio file for comprehensive analysis using FFprobe.

Request:

curl -X POST \
  -F "file=@video.mp4" \
  http://localhost:8080/api/v1/probe/file

Response:

{
  "analysis_id": "550e8400-e29b-41d4-a716-446655440000",
  "filename": "video.mp4",
  "size": 1048576,
  "result": {
    "format": {
      "filename": "/tmp/upload_1234567890_video.mp4",
      "nb_streams": 2,
      "format_name": "mov,mp4,m4a,3gp,3g2,mj2",
      "duration": "60.500000",
      "bit_rate": "5000000"
    },
    "streams": [
      {
        "index": 0,
        "codec_type": "video",
        "codec_name": "h264",
        "width": 1920,
        "height": 1080,
        "r_frame_rate": "30/1"
      },
      {
        "index": 1,
        "codec_type": "audio",
        "codec_name": "aac",
        "sample_rate": "48000",
        "channels": 2
      }
    ],
    "enhanced_analysis": {
      "timecode_analysis": {...},
      "hdr_analysis": {...},
      "codec_analysis": {...},
      "data_integrity": {...}
    }
  }
}

Analyze URL

POST /api/v1/probe/url
Content-Type: application/json

Analyze a video file from a URL without uploading.

Request:

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/video.mp4", "include_llm": true}' \
  http://localhost:8080/api/v1/probe/url

HLS Stream Analysis

POST /api/v1/probe/hls
Content-Type: application/json

Analyze HLS streams for quality, compliance, and performance.

Request:

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "manifest_url": "https://example.com/stream.m3u8",
    "analyze_segments": true,
    "analyze_quality": true,
    "validate_compliance": true,
    "max_segments": 10
  }' \
  http://localhost:8080/api/v1/probe/hls

Batch Processing

POST /api/v1/batch/analyze    # Start batch job
GET  /api/v1/batch/status/:id # Get job status

Process multiple files or URLs in parallel.

GraphQL API

POST /api/v1/graphql
GET  /api/v1/graphql  # GraphiQL interface

Query and mutate via GraphQL for flexible data access.

CLI Tool (`rendiffprobe-cli`)

The CLI provides the same powerful analysis capabilities without requiring a running API server.

Commands

Command	Description
`analyze`	Full QC analysis with all 26 content analyzers
`categories`	List available QC analysis categories
`info`	Quick file information (basic metadata)
`version`	Show version information

Output Formats

report: Human-readable comprehensive QC report
json: Machine-readable JSON output
text: Concise text summary

Examples

# Full comprehensive report
rendiffprobe-cli analyze video.mp4 --format report

# JSON for automation/scripting
rendiffprobe-cli analyze video.mp4 --format json

# Save output to file
rendiffprobe-cli analyze video.mp4 --format json --output result.json

# Analyze multiple files
rendiffprobe-cli analyze video1.mp4 video2.mp4 --format text

# Quick metadata check
rendiffprobe-cli info video.mp4

# Set timeout for large files
rendiffprobe-cli analyze large_video.mp4 --timeout 300

Deployment Modes

Minimal (Development/Testing)

make minimal

Core services only: API + Valkey + Ollama
Memory: ~2-3GB
Best for: Development, testing

Quick Start

make quick

Ready in 2 minutes
No authentication required
Best for: Quick testing, demos

Production

make prod

Full monitoring stack
Authentication enabled
Automated backups
Best for: Production deployments

Architecture

View Full Architecture Documentation - Detailed system design, component diagrams, and implementation patterns.

┌──────────────────────────────────────────────────────────────────────────────┐
│                              CLIENT LAYER                                     │
│    ┌─────────────┐     ┌─────────────┐     ┌─────────────┐                   │
│    │  REST API   │     │  GraphQL    │     │   CLI Tool  │                   │
│    └──────┬──────┘     └──────┬──────┘     └──────┬──────┘                   │
└───────────┼────────────────────┼────────────────────┼─────────────────────────┘
            │                    │                    │
┌───────────▼────────────────────▼────────────────────▼─────────────────────────┐
│                           MIDDLEWARE LAYER                                     │
│  [Recovery] → [RequestID] → [Logging] → [RateLimit] → [Auth] → [Validation]  │
└───────────────────────────────────┬───────────────────────────────────────────┘
                                    │
┌───────────────────────────────────▼───────────────────────────────────────────┐
│                            SERVICE LAYER                                       │
│   ┌────────────────┐   ┌────────────────┐   ┌────────────────┐               │
│   │ AnalysisService│   │ ReportService  │   │ SecretRotation │               │
│   └───────┬────────┘   └────────────────┘   └────────────────┘               │
└───────────┼───────────────────────────────────────────────────────────────────┘
            │
┌───────────▼───────────────────────────────────────────────────────────────────┐
│                         ANALYSIS ENGINE                                        │
│  ┌─────────────────────────────────────────────────────────────────────────┐  │
│  │                   Content Analyzer (26 Parallel Goroutines)             │  │
│  │   ┌────────────┬────────────┬────────────┬────────────┬────────────┐   │  │
│  │   │   Video    │   Audio    │   HDR      │  Broadcast │  Integrity │   │  │
│  │   │  Quality   │  Analysis  │  Analysis  │ Compliance │  Analysis  │   │  │
│  │   └─────┬──────┴─────┬──────┴─────┬──────┴─────┬──────┴─────┬──────┘   │  │
│  │         │            │            │            │            │           │  │
│  │   ┌─────▼────────────▼────────────▼────────────▼────────────▼──────┐   │  │
│  │   │              FFmpeg Filters (signalstats, idet, ebur128, etc)  │   │  │
│  │   └────────────────────────────────────────────────────────────────┘   │  │
│  └─────────────────────────────────────────────────────────────────────────┘  │
│                                    │                                           │
│  ┌─────────────────────────────────▼───────────────────────────────────────┐  │
│  │                      FFprobe / FFmpeg Binaries                          │  │
│  └─────────────────────────────────────────────────────────────────────────┘  │
└───────────────────────────────────────────────────────────────────────────────┘
                                    │
┌───────────────────────────────────▼───────────────────────────────────────────┐
│                             DATA LAYER                                         │
│   ┌────────────────┐   ┌────────────────┐   ┌────────────────┐               │
│   │ SQLite (Store) │   │ Valkey (Cache) │   │ File Storage   │               │
│   └────────────────┘   └────────────────┘   └────────────────┘               │
└───────────────────────────────────────────────────────────────────────────────┘

Key Components

Layer	Components	Purpose
Client	REST API, GraphQL, CLI	Multiple interface options
Middleware	Auth, RateLimit, Logging	Request processing pipeline
Service	Analysis, Reports, Secrets	Business logic encapsulation
Analysis Engine	26 concurrent analyzers	FFmpeg-based quality analysis
Data	SQLite, Valkey, FileStore	Persistence and caching

Quality Control Features

26 Content Analyzers (121 Parameters)

Category	Analyzers	FFmpeg Filters	Standards
Video Quality	Baseband, Quality Score, Blockiness, Blurriness, Noise, Line Errors	signalstats, entropy	EBU R103
Video Content	Black Frames, Freeze Frames, Letterbox, Color Bars, Safe Areas, Temporal Complexity, Field Dominance, Differential Frames	blackdetect, freezedetect, cropdetect, idet	ITU-R BT.814
Audio Quality	Loudness (EBU R128), Clipping, Silence, Phase, Channel Mapping, Frequency Analysis	ebur128, astats, volumedetect	EBU R128, ITU-R BS.1770
HDR/Color	HDR10, Dolby Vision, HLG, Color Space, Gamut	signalstats BRNG	Rec.2020, SMPTE ST 2086
Broadcast	Timecode Continuity, MXF Validation, IMF Compliance, Transport Stream	-	SMPTE 12M, ST 377, ST 2067
Safety	PSE Flash Detection, AFD Analysis, Test Tone Detection	-	ITU-R BT.1702, Ofcom
Format	Container, Codec, Resolution, Frame Rate, Bit Depth, Endianness	-	-
Integrity	Data Integrity, Stream Disposition, Dropout Detection	-	CRC32, MD5

19 Top-Level QC Categories

View Complete QC Parameters Reference - Detailed documentation of all 19 categories with 121 parameters

#	Category	Key Parameters	Standards	Use Cases
1	AFD Analysis	AFD codes, aspect ratio validation	ITU-R BT.1868	Broadcast distribution
2	Dead Pixel Detection	Stuck/dead/hot pixels, defect maps	Computer Vision	Camera QC, acquisition
3	PSE Flash Analysis	Flash rate, luminance changes, risk level	ITC/Ofcom, ITU-R BT.1702	Broadcast safety
4	HDR Analysis	MaxCLL, MaxFALL, color gamut	HDR10, Dolby Vision, HLG	Streaming platforms
5	Audio Wrapping	Channel mapping, embedding format	BWF, RF64, AES3	Post-production
6	Endianness Detection	Byte order, platform compatibility	-	Cross-platform workflows
7	Codec Analysis	Profile, level, bitrate efficiency	-	Format validation
8	Container Validation	Structure, metadata, muxing pattern	MP4, MKV, MOV	Workflow compatibility
9	Resolution Analysis	PAR, DAR, display optimization	-	Quality validation
10	Frame Rate Analysis	Temporal accuracy, VFR detection	Broadcast standards	Temporal analysis
11	Bitdepth Analysis	Color precision, dynamic range	8/10/12-bit	HDR compatibility
12	Timecode Analysis	SMPTE TC, drop frame, continuity	SMPTE 12M	Broadcast, post
13	MXF Analysis	OP patterns, essence containers	SMPTE ST 377	Professional broadcast
14	IMF Compliance	CPL, OPL, application profiles	SMPTE ST 2067	Netflix delivery
15	Transport Stream	PID mapping, PSI/SI, continuity	MPEG-TS	IPTV, streaming
16	Content Analysis	26 parallel analyzers (see below)	Multiple	Real-time QC
17	Enhanced Analysis	Quality scoring, risk assessment	-	Advanced metrics
18	Stream Disposition	SDH, audio descriptions, languages	Section 508, WCAG	Accessibility
19	Data Integrity	CRC32, MD5, corruption detection	-	File validation

Configuration

Environment Variables

Variable	Default	Description
`PORT`	`8080`	API port
`LOG_LEVEL`	`info`	Log level (debug, info, warn, error)
`FFPROBE_PATH`	`ffprobe`	Path to FFprobe binary
`DB_PATH`	`./data/rendiff-probe.db`	SQLite database path
`VALKEY_URL`	`valkey:6379`	Valkey/Redis connection

Security Configuration

Variable	Description
`JWT_SECRET`	JWT signing secret (required in production)
`API_KEY`	API key for authentication
`RATE_LIMIT_RPM`	Rate limit per minute

Management Commands

# Service Management
make start      # Start all services
make stop       # Stop all services
make restart    # Restart services
make status     # Show status
make logs       # View logs
make health     # Check health

# Development
make test-unit       # Run unit tests
make test-coverage   # Run tests with coverage
make lint            # Run linter

# Build
go build -o rendiff-probe ./cmd/rendiff-probe
go build -o rendiffprobe-cli ./cmd/rendiffprobe-cli

# Maintenance
make update     # Update services
make backup     # Create backup
make clean      # Clean everything

Testing

# Run all tests
make test-unit

# Run with coverage
make test-coverage

# Run specific package
go test -v ./internal/ffmpeg/...

# Run with race detection
make test-race

Documentation

Core Documentation

Document	Description	Audience
User Manual	Complete guide for using the API and CLI	End Users
Developer Guide	Contributing to and extending the codebase	Developers
Architecture	System design and component diagrams	Architects

Reference Documentation

Document	Description
QC Analysis List	All 19 QC categories with 121 parameters
API Reference	OpenAPI/Swagger documentation
Changelog	Version history and release notes

Quick Links

Contributing

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes
Run tests (make test-unit)
Commit your changes
Push to the branch
Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Third-Party Licenses

FFprobe/FFmpeg: Licensed under LGPL/GPL - see FFmpeg License

Support

Issues: GitHub Issues
Documentation: docs/

Rendiff Probe - Professional Video Analysis, Powered by FFprobe

Built for the video processing community

Name		Name	Last commit message	Last commit date
Latest commit History 38 Commits
.github		.github
cmd		cmd
data		data
docker-image		docker-image
docs		docs
internal		internal
pkg/logger		pkg/logger
scripts		scripts
.env.example		.env.example
.env.production.template		.env.production.template
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
go.mod		go.mod
go.sum		go.sum
railway.env		railway.env
setup.sh		setup.sh

License

rendiffdev/rendiff-probe

Folders and files

Latest commit

History

Repository files navigation

Rendiff Probe

Acknowledgements

Features

Core Capabilities

Quality Control Analysis

Quick Start

Prerequisites

Installation

Using the CLI (rendiffprobe-cli)

Using the API (rendiff-probe)

API Reference

Health Check

Analyze File

Analyze URL

HLS Stream Analysis

Batch Processing

GraphQL API

CLI Tool (rendiffprobe-cli)

Commands

Output Formats

Examples

Deployment Modes

Minimal (Development/Testing)

Quick Start

Production

Architecture

Key Components

Quality Control Features

26 Content Analyzers (121 Parameters)

19 Top-Level QC Categories

Configuration

Environment Variables

Security Configuration

Management Commands

Testing

Documentation

Core Documentation

Reference Documentation

Quick Links

Contributing

License

Third-Party Licenses

Support

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Contributors 3

Uh oh!

Languages

Using the CLI (`rendiffprobe-cli`)

Using the API (`rendiff-probe`)

CLI Tool (`rendiffprobe-cli`)