major-ai-skills/skills/ffmpeg/gpt.md

Installable agentic skills / AI agent skills (SKILL.md) for Claude Code, Cursor, Codex CLI, Gemini CLI & Antigravity - 402+ professional app, token-efficiency, and common-sense skills. SEO/GEO ready.

---

title: "FFmpeg Media Engineering AI Skill Guide (GPT & Codex)"
description: "Comprehensive operational skill specification for OpenAI GPT and Codex to automate, script, troubleshoot, and optimize FFmpeg transcoding pipelines, asynchronous worker queues, and CLI flags."
category: "Multimedia Transcoding & Stream Processing Engine"
tags: ["ffmpeg", "python-transcoding", "async-worker", "gpt-codex", "video-pipeline", "stream-processing"]
---


# FFmpeg Media Engineering AI Skill Guide (GPT & Codex)

## Overview & Engine Architecture
FFmpeg is the computational backbone for global media pipelines. GPT/Codex acts as a Principal Media Systems Architect and Backend Developer, delivering **Python transcoding automation scripts**, **asynchronous task queue integrations (Celery/RabbitMQ/Redis)**, **hardware-accelerated container packaging**, and **robust `ffprobe` stream metadata parsers**.

### Pipeline Architecture & Developer Layer

```
┌─────────────────────────────────────────────────────────────┐
│                 FFmpeg Microservice Platform                │
│                                                             │
│  Job Ingestion & Analysis Layer                             │
│  ├── `ffprobe` JSON Stream Inspector (Streams, Format, Tags)│
│  ├── Codec & Bitrate Parameter Matrix Calculator            │
│  └── Hardware Capabilities Query (`ffmpeg -hwaccels`)       │
│                                                             │
│  Execution & Task Worker Layer                              │
│  ├── Python Subprocess / Asynchronous Worker Daemon         │
│  ├── Real-Time Progress Parser (`-progress pipe:1`)         │
│  └── Distributed Cloud Storage Pipe (S3 / GCS Direct Stream)│
└─────────────────────────────────────────────────────────────┘
```

---


## Operational Capabilities & Agent Directives

1. **Real-Time Progress Tracking & Parsing**: Construct asynchronous Python execution wrappers that consume FFmpeg's `-progress pipe:1` stream to calculate encoding FPS, current timestamp, bitrate, and percentage completion.
2. **Dynamic Codec Parameter Allocation**: Build algorithms that compute target bitrates, GOP sizes, and buffer sizes based on resolution, frame rate, and storage constraints.
3. **Lossless Video Slicing & Concatenation**: Author scripts for fast, keyframe-accurate video cutting (`-ss ... -to ... -c copy`) and demuxer concatenation (`concat -safe 0`).
4. **Hardware Acceleration Fallback Pipelines**: Implement fallback logic that attempts hardware encoding (NVENC/QSV) and automatically retries with software encoding (`libx264`/`libx265`) on driver failure.

---


## Production Python Automation: Asynchronous FFmpeg Worker with Real-Time Progress

Run this script to transcode videos asynchronously with live progress tracking and ETA calculations:

```python
"""
FFmpeg Asynchronous Transcode Worker with Real-Time Progress
Parses -progress pipe:1 to output live percentage and speed.
"""

import sys
import os
import asyncio
import subprocess
import json
import re

def get_duration(file_path: str) -> float:
    cmd = ["ffprobe", "-v", "error", "-show_entries", "format=duration", "-of", "default=noprint_wrappers=1:nokey=1", file_path]
    res = subprocess.run(cmd, capture_output=True, text=True)
    return float(res.stdout.strip()) if res.stdout else 0.0

async def transcode_with_progress(input_file: str, output_file: str):
    if not os.path.exists(input_file):
        print(f"Error: {input_file} not found.")
        return

    duration = get_duration(input_file)
    print(f"Input duration: {duration:.2f} seconds")

    cmd = [
        "ffmpeg", "-y", "-i", input_file,
        "-c:v", "libx264", "-preset", "fast", "-crf", "22",
        "-pix_fmt", "yuv420p", "-movflags", "+faststart",
        "-c:a", "aac", "-b:a", "128k",
        "-progress", "pipe:1",
        output_file
    ]

    process = await asyncio.create_subprocess_exec(
        *cmd, stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.DEVNULL
    )

    out_time_ms_regex = re.compile(r"out_time_us=(\d+)")
    speed_regex = re.compile(r"speed=([\d\.]+x)")

    while True:
        line = await process.stdout.readline()
        if not line:
            break
        text = line.decode().strip()
        
        match_time = out_time_ms_regex.match(text)
        if match_time and duration > 0:
            current_sec = int(match_time.group(1)) / 1_000_000.0
            percent = min((current_sec / duration) * 100.0, 100.0)
            sys.stdout.write(f"\r[TRANSCODING] Progress: {percent:.1f}% ({current_sec:.1f}s / {duration:.1f}s)")
            sys.stdout.flush()

    await process.wait()
    sys.stdout.write("\n")
    if process.returncode == 0:
        print(f"Transcoding completed successfully: {output_file}")
    else:
        print(f"Transcoding failed with exit code: {process.returncode}")

if __name__ == "__main__":
    if len(sys.argv) < 3:
        print("Usage: python async_transcode.py <input.mov> <output.mp4>")
        sys.exit(1)
    asyncio.run(transcode_with_progress(sys.argv[1], sys.argv[2]))
```

---


## Technical Troubleshooting Matrix

| Issue & Failure Signature | Root Cause Analysis | Diagnostic & Resolution Pathway |
| :--- | :--- | :--- |
| **`Option -crf not found` with NVENC** | NVENC does not support `-crf`; it uses Constant Quality (`-cq`) or Constant Quantization Parameter (`-cqp`). | For NVENC, use: `-c:v h264_nvenc -rc vbr -cq 20 -b:v 0`. |
| **Video Freeze on Keyframe Cut (`-ss` and `-c copy`)** | Cutting stream without re-encoding when the start timestamp `-ss` is placed on a non-keyframe (P-frame/B-frame). | 1. Place `-ss` before the input flag `-i` for fast seek to nearest I-frame.<br>2. If frame-accurate cutting is strictly required, remove `-c copy` and re-encode. |
| **`Too many packets buffered for output stream`** | Audio and video streams are interleaved with uneven buffer packet sizes. | Add `-max_muxing_queue_size 1024` or `-max_muxing_queue_size 4096` to output options. |
| **Concatenation Audio Disappears or Distorts** | Input clips have differing audio sample rates (44.1kHz vs 48kHz) or channel layouts. | 1. Resample all audio streams to 48kHz stereo before concat.<br>2. Use `-filter_complex "[0:v][0:a][1:v][1:a]concat=n=2:v=1:a=1"` rather than file demuxer. |

---


## Command Line Syntax & Batch Processing

```bash
# 1. Lossless Video Slicing (Fast Keyframe Cut)
ffmpeg -ss 00:01:30 -to 00:03:00 -i input.mp4 -c copy -avoid_negative_ts 1 output_clip.mp4

# 2. Extract High-Quality Thumbnail at Specific Second
ffmpeg -ss 00:00:15 -i input.mp4 -vframes 1 -q:v 2 thumb.jpg

# 3. Concatenate Multiple MP4 Files without Re-encoding
# contents of files.txt: file 'clip1.mp4'\nfile 'clip2.mp4'
ffmpeg -f concat -safe 0 -i files.txt -c copy merged.mp4
```

---


## Agent Operational Directive
> **MANDATORY**: For real-time progress parsing in backend workers, pipe progress metrics via `-progress pipe:1`. For NVENC rate control, use `-rc vbr -cq <N>` rather than `-crf`.