FFprobe API

AI-Powered Video Analysis API - Beyond Traditional FFprobe

🧠 The only media analysis API with built-in GenAI intelligence - transforming raw FFprobe data into actionable professional insights, recommendations, and risk assessments.

Why choose FFprobe API over direct FFmpeg/FFprobe?

🎯 GenAI Analysis: AI-powered interpretation of technical data into professional insights
🔍 Intelligent Risk Assessment: AI identifies safety, compliance, and technical risks
📊 Smart Recommendations: GenAI suggests specific FFmpeg commands and workflow improvements
🏆 Professional QC: 19 advanced quality control categories beyond basic FFprobe
💡 Executive Summaries: AI translates technical data for non-technical stakeholders

🧠 Core GenAI Differentiators

FFprobe API: Enhanced Video Analysis

Standard Workflow	FFprobe API Enhancement
Technical data output	🎯 AI-interpreted insights
Analysis workflow	🤖 Automated risk assessment
Raw metrics	💡 Smart optimization suggestions
Technical format	📝 Executive-friendly summaries
Individual file processing	🔄 Workflow integration recommendations

🚀 GenAI-Powered Features

🧠 AI Technical Analysis: LLM interprets FFprobe data into professional assessment
⚠️ Risk Assessment: AI identifies PSE risks, compliance issues, technical problems
🎯 Smart Recommendations: GenAI suggests specific FFmpeg commands for optimization
📊 Quality Insights: AI evaluates suitability for different delivery platforms
🏢 Executive Summaries: Technical findings translated for management/clients
🔍 Issue Detection: AI spots problems human analysts might miss

🛠️ Advanced Technical Features

Advanced Quality Control: 19 professional QC analysis categories including timecode, AFD, MXF validation, dead pixel detection, PSE analysis, data integrity validation, and stream disposition analysis
Latest FFmpeg: Always uses latest stable BtbN builds with all codecs
Professional Reports: Comprehensive technical analysis with quality metrics and compliance validation
Multiple Formats: Supports all video/audio formats that FFmpeg supports
REST & GraphQL API: Complete RESTful and GraphQL interfaces with OpenAPI documentation
Zero Config: Runs out-of-the-box with sensible defaults
Production Ready: Full monitoring, backups, and security features

🚀 Quick Start

Smart Installation with System Requirements Checking

🤖 The setup script automatically validates your system meets the requirements for your chosen deployment mode:

# 🔧 Clone and setup (recommended)
git clone <your-repo-url>
cd ffprobe-api
make quick

# ⚡ Alternative quick modes:
make minimal     # 2GB RAM, 6GB disk - core services only
make dev         # 4GB RAM, 15GB disk - development environment  
make prod        # 8GB RAM, 20GB disk - production with monitoring

# 🎯 Interactive setup with system validation
./setup.sh       # Automatically detects best deployment mode

✨ What the smart installer checks:

📊 RAM: Deployment-specific minimum (2-8GB)
💾 Disk space: Mode-specific requirements (6-20GB)
🖥️ CPU cores: Sufficient processing power (1-4 cores)
🔌 Network ports: Required ports available
🐳 Docker: Installation and container capabilities
🌐 Internet: Connection for downloading images

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

🧠 Test GenAI Analysis (The Core USP)

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

# Traditional analysis (like basic FFprobe)
curl -X POST -F "file=@video.mp4" http://localhost:8080/api/v1/probe/file

# 🎆 GenAI-powered analysis (THE DIFFERENTIATOR)
curl -X POST \
  -F "file=@video.mp4" \
  -F "include_llm=true" \
  http://localhost:8080/api/v1/probe/file

# Get AI insights from the analysis
curl http://localhost:8080/api/v1/analysis/{id} | jq '.llm_report'

💫 What you get with GenAI analysis:

Professional quality assessment in plain English
Specific FFmpeg optimization commands
Risk assessment for PSE/compliance issues
Delivery platform recommendations
Executive summary for stakeholders

📋 System Requirements

Docker 24.0+ with Compose
2GB RAM minimum (4GB recommended)
5GB disk space for models and data
Internet connection for initial setup
No external database required - SQLite embedded by default

🏗️ Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   FFprobe API   │───▶│     SQLite      │    │     Valkey      │
│   (Latest)      │    │ (Embedded DB)   │    │ (Redis-compatible)│
└─────────┬───────┘    └─────────────────┘    └─────────────────┘
          │
          ▼
┌─────────────────┐    ┌─────────────────┐
│     Ollama      │    │   FFmpeg        │
│  (AI Models)    │    │  (BtbN Latest)  │
│                 │    │                 │
│ • Gemma3 270M   │    │ • All Codecs    │
│ • Phi-3 Mini    │    │ • VMAF Support  │
└─────────────────┘    └─────────────────┘

🛠️ Deployment Modes

🐳 NEW: Production-Grade Docker Infrastructure

FFprobe API now includes enterprise-ready Docker infrastructure with comprehensive security, monitoring, and operational capabilities.

🚀 Quick Production Deployment

# Build optimized production image
./docker-image/build-optimized.sh --target production --scan --sbom

# Generate secure secrets
./docker-image/scripts/secrets-manager.sh generate

# Deploy complete production stack
./docker-image/deploy-production.sh \
  --mode compose \
  --environment production \
  --domain api.yourcompany.com \
  --enable-ssl \
  --enable-monitoring \
  --deploy

✨ Production Features:

🛡️ Security-hardened containers with non-root users
📊 Complete monitoring stack (Prometheus, Grafana, Jaeger)
🔒 Automated SSL/TLS with Let's Encrypt
💾 Encrypted backups with retention policies
⚡ Zero-downtime deployments with rolling updates
🔄 Auto-scaling with resource management

📚 Complete Docker Documentation

Traditional Deployment Modes

Minimal Deployment (Testing)

make minimal

Ultra-lightweight: Only 3 core services
Services: API + Valkey + Ollama (SQLite embedded)
Memory: ~2-3GB total
Perfect for: Development, testing, resource-constrained environments

Quick Start (Development)

make quick

Ready in 2 minutes
No authentication
Gemma 3 270M for fast analysis
Perfect for demos and quick testing

Development Environment

make dev

Hot reload and debugging
Database/Valkey admin tools
File browser interface for uploads
Development-focused tooling

Legacy Production

make prod

Basic production setup
Prometheus + Grafana dashboards
Automated backups
Note: Use the new Docker infrastructure for enterprise deployments

🔍 Advanced Quality Control Features

The FFprobe API provides comprehensive professional QC analysis with industry-standard compliance checking.

📋 Complete QC Analysis List - Detailed breakdown of all 19 QC categories

QC Analysis Categories Overview

Core QC Analysis (19 Categories)

AFD Analysis: Active Format Description broadcast signaling compliance
Dead Pixel Detection: Computer vision-based pixel defect analysis
PSE Flash Analysis: Photosensitive epilepsy safety analysis
HDR Analysis: High Dynamic Range content validation
Audio Wrapping Analysis: Professional audio format detection
Endianness Detection: Binary format and platform compatibility
Codec Analysis: Codec validation and profile analysis
Container Validation: Container format compliance checking
Resolution Analysis: Resolution and aspect ratio validation
Frame Rate Analysis: Frame rate accuracy and consistency validation
Bitdepth Analysis: Bit depth validation and HDR compatibility
Timecode Analysis: SMPTE timecode parsing and validation
MXF Analysis: Material Exchange Format compliance
IMF Compliance: Interoperable Master Format validation (Netflix standard)
Transport Stream Analysis: MPEG-TS structure and error detection
Content Analysis: Scene change detection and motion analysis
Enhanced Analysis: Advanced quality metrics and recommendations
Stream Disposition Analysis: Accessibility and stream role validation
Data Integrity Analysis: Error detection and hash-based integrity verification

AI-Enhanced Analysis (Optional)

Risk Assessment: Automated technical, compliance, and safety risk evaluation
Quality Scoring: Overall QC score with critical findings identification
Workflow Integration: Intelligent recommendations for production pipelines
Compliance Insights: Broadcast standards validation (ITU, FCC, EBU, ATSC)

🔒 Security Features

🛡️ Production Security (Docker Infrastructure)

Security-hardened containers with non-root users and read-only filesystems
Comprehensive seccomp profiles limiting system calls
Secrets management with automatic rotation
Network encryption and service isolation
Vulnerability scanning integrated into CI/CD
Compliance-ready (SOC2, PCI-DSS, GDPR)

🔐 Application Security (All Deployments)

API Key Authentication: Secure access control
Rate Limiting: Prevent abuse and DoS attacks
Input Validation: Comprehensive file validation
Secure Defaults: No sensitive data exposure
Container Security: Minimal attack surface
CSRF Protection: Cross-site request forgery prevention
Security Headers: HSTS, CSP, and other security headers

⚡ Optimized Component Architecture

Essential Components (All Deployments)

SQLite: Embedded database (zero configuration)
Valkey 8: High-performance caching (Redis-compatible, open source)
Ollama: Local AI processing (Gemma 3 270M + Phi-3 Mini)
FFprobe API: Core video analysis service

Production Components (Production Only)

Traefik v3: Combined reverse proxy + automatic SSL
Prometheus: Metrics and monitoring
Grafana: Dashboards and visualization
Backup Service: Automated data protection

Development Tools (Development Only)

SQLite Browser: Database administration
Valkey Commander: Cache administration
File Browser: Upload management

Resource Savings: ~300MB RAM, faster startup, fewer containers to manage

📖 API Documentation

Core Endpoints

Health Check

GET /health

🧠 GenAI-Powered Analysis (Core USP)

# THE DIFFERENTIATOR: AI-powered analysis
POST /api/v1/probe/file
Content-Type: application/json

{
  "file_path": "/path/to/video.mp4",
  "include_llm": true,          // 🎆 Enable GenAI analysis
  "content_analysis": true,
  "generate_reports": true,
  "report_formats": ["json", "pdf"]
}

GenAI Response Includes:

{
  "analysis_id": "uuid",
  "llm_report": "🧠 EXECUTIVE SUMMARY: Professional HD content suitable for broadcast. Video shows excellent technical quality with H.264 encoding at 1920x1080. RECOMMENDATIONS: Consider re-encoding to HEVC for 40% smaller files while maintaining quality. RISKS: No safety concerns detected.",
  "llm_enabled": true
}

Traditional Analysis (Like Basic FFprobe)

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

{
  "file_path": "/path/to/video.mp4",
  "content_analysis": true,
  "generate_reports": true,
  "report_formats": ["json", "pdf"]
}

URL Analysis with GenAI

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

{
  "url": "https://example.com/video.mp4",
  "include_llm": true,        // 🧠 Enable AI analysis
  "content_analysis": true,
  "timeout": 300
}

GraphQL Query

query AnalyzeMedia($input: AnalysisInput!) {
  analyzeMedia(input: $input) {
    id
    status
    result {
      enhancedAnalysis {
        timecodeAnalysis { hasTimecode isDropFrame }
        mxfAnalysis { isMXFFile validationResults }
        pseAnalysis { riskLevel violations }
      }
    }
  }
}

Response Format

{
  "analysis_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "analysis": {
    "file_info": {
      "filename": "video.mp4",
      "size": 1048576,
      "duration": 60.5
    },
    "result": {
      "streams": [...],
      "format": {...},
      "enhanced_analysis": {
        "timecode_analysis": {
          "has_timecode": true,
          "is_drop_frame": false,
          "start_timecode": "01:00:00:00"
        },
        "mxf_analysis": {
          "is_mxf_file": true,
          "mxf_profile": "OP1a",
          "validation_results": {
            "overall_compliance": true
          }
        },
        "pse_analysis": {
          "pse_risk_level": "safe",
          "flash_analysis": {...}
        },
        "llm_enhanced_report": {
          "overall_qc_score": 95.5,
          "critical_findings": [],
          "risk_assessment": {
            "overall_risk_level": "low"
          }
        }
      }
    }
  }
}

🧠 GenAI Analysis Examples (Core USP)

🎯 Why GenAI Analysis Changes Everything

Traditional FFprobe Output:

{
  "codec_name": "h264",
  "width": 1920,
  "height": 1080,
  "bit_rate": "5000000"
}

FFprobe API with GenAI Output:

{
  "llm_report": "EXECUTIVE SUMMARY: Professional HD broadcast content ready for delivery. Technical Analysis: H.264 encoding at optimal bitrate (5Mbps) for 1080p resolution. Quality Assessment: Excellent visual quality with no artifacts detected. Recommendations: 1) Consider HEVC encoding for 40% size reduction while maintaining quality. 2) Add closed captions for accessibility compliance. 3) Suitable for Netflix, YouTube, and broadcast distribution. Risk Assessment: Low technical risk, compliant with industry standards. Workflow Integration: Ready for immediate delivery pipeline integration."
}

🎥 Real-World GenAI Use Cases

🚨 Safety Risk Detection

# Analyze content for PSE risks
curl -X POST \
  -F "file=@flashing_video.mp4" \
  -F "include_llm=true" \
  http://localhost:8080/api/v1/probe/file

# AI Response:
"CRITICAL ALERT: High photosensitive epilepsy risk detected. 
 Flashing patterns exceed safe thresholds (>3Hz). 
 REQUIRED ACTIONS: Add PSE warning, consider content modification."

🏆 Quality Optimization

# Get optimization recommendations
curl -X POST \
  -F "file=@large_video.mp4" \
  -F "include_llm=true" \
  http://localhost:8080/api/v1/probe/file

# AI Response:
"OPTIMIZATION OPPORTUNITIES: File is 2.5GB for 10min duration. 
 RECOMMENDED: ffmpeg -i input.mp4 -c:v libx265 -crf 23 -c:a copy output.mp4 
 RESULT: 60% smaller file, same visual quality."

📄 Executive Reporting

# Generate stakeholder-friendly reports
curl -X POST \
  -F "file=@corporate_video.mp4" \
  -F "include_llm=true" \
  http://localhost:8080/api/v1/probe/file

# AI Response:
"CLIENT REPORT: Your video meets all technical requirements for 
 social media distribution. Optimized for YouTube, Instagram, and 
 TikTok. No technical issues detected. Ready for immediate publication."

🛠️ HLS Analysis with GenAI

# Analyze HLS streams with AI insights
curl -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "source": "/path/to/hls/directory/",
    "analyze_segments": true,
    "include_llm": true
  }' \
  http://localhost:8080/api/v1/probe/hls

# AI analyzes all .ts chunks and provides:
# - Quality ladder optimization suggestions
# - ABR streaming recommendations  
# - Platform compatibility assessment
# - Bandwidth efficiency insights

🔧 Management Commands

# Service management
make start              # Start all services
make stop               # Stop all services
make restart            # Restart all services
make health             # Check service health
make logs               # View all logs

# Development
make dev                # Development environment
make shell              # Access API container
make db-shell           # Access database
make valkey-shell       # Access Valkey

# Maintenance
make update             # Update to latest versions
make backup             # Create backup
make clean              # Clean everything

📊 Monitoring & Observability

🔍 Production Monitoring (Docker Infrastructure)

Prometheus metrics with custom recording rules and alerting
Grafana dashboards with pre-built visualizations for FFprobe API
Jaeger tracing for distributed request tracking
Automated alerting for service health, performance, and security
Log aggregation with structured JSON logging
Health checks with dependency monitoring and circuit breakers

Monitor everything:

Application performance (response times, error rates, throughput)
Infrastructure resources (CPU, memory, disk, network)
Business metrics (video processing rates, quality scores)
Security events (failed auth, rate limits, suspicious activity)

📈 Basic Monitoring (All Deployments)

Service health endpoints
Dependency health validation
Model availability checking
Resource usage monitoring
Simple metrics collection

🔄 Updates & Maintenance

Automatic Updates

FFmpeg: Latest stable BtbN builds
AI Models: Model version management
Security: Regular security updates
Dependencies: Container base image updates

Manual Commands

# Update everything
make update

# Update specific components
./scripts/ffmpeg-update.sh check
./scripts/ffmpeg-update.sh update --allow-major

# Model management
docker compose exec ollama ollama list
docker compose exec ollama ollama pull gemma3:270m

🐛 Troubleshooting

Common Issues

Services won't start

# Check Docker
docker --version
docker compose version

# View logs
make logs

# Reset everything
make reset

Port conflicts

# Check ports
lsof -i :8080
lsof -i :5432

# Use custom ports
export API_PORT=8081
export POSTGRES_PORT=5433
make quick

Models not downloading

# Check Ollama
curl http://localhost:11434/api/version

# Manual download
docker compose exec ollama ollama pull gemma3:270m

📚 Documentation

🐳 Production Docker Infrastructure

🏭 Docker Production Guide - Complete production deployment
🔧 Build System - Multi-stage builds and optimization
🔒 Security Guide - Security hardening and compliance
📊 Monitoring Setup - Prometheus, Grafana, alerts

📖 Application Documentation

📖 Complete Documentation - Full documentation index
📡 API Reference - REST and GraphQL APIs
🔍 QC Features - All 20+ quality control categories
🏢 Production Guide - Enterprise deployment
🤖 AI Setup - Local AI analysis setup

🤝 Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request

📄 License

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

🆘 Support

Documentation: docs/
Issues: Create GitHub Issues for bug reports
Questions: Check documentation or create discussions

Built with ❤️ for the video processing community

Name		Name	Last commit message	Last commit date
Latest commit History 28 Commits
.github		.github
cmd/ffprobe-api		cmd/ffprobe-api
data		data
docs		docs
internal		internal
pkg/logger		pkg/logger
scripts		scripts
.env.example		.env.example
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
DOCKER-IMAGES.md		DOCKER-IMAGES.md
LICENSE		LICENSE
Makefile		Makefile
RAILWAY-DEPLOY.md		RAILWAY-DEPLOY.md
README.md		README.md
go.mod		go.mod
go.sum		go.sum
railway.env		railway.env
setup.sh		setup.sh

Uh oh!

License

Uh oh!

rendiffdev/ffprobe-api

Folders and files

Latest commit

History

Repository files navigation

FFprobe API

🧠 Core GenAI Differentiators

FFprobe API: Enhanced Video Analysis

🚀 GenAI-Powered Features

🛠️ Advanced Technical Features

🚀 Quick Start

Smart Installation with System Requirements Checking

🧠 Test GenAI Analysis (The Core USP)

📋 System Requirements

🏗️ Architecture

🛠️ Deployment Modes

🐳 NEW: Production-Grade Docker Infrastructure

🚀 Quick Production Deployment

Traditional Deployment Modes

Minimal Deployment (Testing)

Quick Start (Development)

Development Environment

Legacy Production

🔍 Advanced Quality Control Features

QC Analysis Categories Overview

Core QC Analysis (19 Categories)

AI-Enhanced Analysis (Optional)

🔒 Security Features

🛡️ Production Security (Docker Infrastructure)

🔐 Application Security (All Deployments)

⚡ Optimized Component Architecture

Essential Components (All Deployments)

Production Components (Production Only)

Development Tools (Development Only)

📖 API Documentation

Core Endpoints

Health Check

🧠 GenAI-Powered Analysis (Core USP)

Traditional Analysis (Like Basic FFprobe)

URL Analysis with GenAI

GraphQL Query

Response Format

🧠 GenAI Analysis Examples (Core USP)

🎯 Why GenAI Analysis Changes Everything

🎥 Real-World GenAI Use Cases

🚨 Safety Risk Detection

🏆 Quality Optimization

📄 Executive Reporting

🛠️ HLS Analysis with GenAI

🔧 Management Commands

📊 Monitoring & Observability

🔍 Production Monitoring (Docker Infrastructure)

📈 Basic Monitoring (All Deployments)

🔄 Updates & Maintenance

Automatic Updates

Manual Commands

🐛 Troubleshooting

Common Issues

Services won't start

Port conflicts

Models not downloading

📚 Documentation

🐳 Production Docker Infrastructure

📖 Application Documentation

🤝 Contributing

📄 License

🆘 Support

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases