workflow-analysis-quality

---
name: workflow-analysis-quality
description: Deep media inspection + automated QC — ffprobe stream details, MediaInfo diagnostics, VMAF/PSNR/SSIM quality metrics, PySceneDetect scene cuts, crop/silence/black-frame/interlacing detection, ffplay scope debugging, NAL/SEI bitstream forensics, metadata audits, loudness compliance against Spotify/Apple/ATSC/EBU specs, and automated CI QC gates. Use when the user says "QC this file", "run VMAF", "compare encoders", "detect scene cuts", "check loudness compliance", "validate delivery spec", "automated QC pipeline", or any deep inspection / quality gating.
argument-hint: "[ref] [out]"
---

# Workflow — Analysis + Quality

**What:** Inspect every byte and assess every rendition. The gate between "encoded" and "shipped".

## Skills used

`ffmpeg-probe`, `media-mediainfo`, `ffmpeg-quality`, `media-scenedetect`, `ffmpeg-detect`, `ffmpeg-playback`, `ffmpeg-bitstream`, `media-exiftool`, `ffmpeg-metadata`, `media-ocr-ai`, `cv-opencv`, `cv-mediapipe`, `media-tag`.

## Pipeline

### Step 1 — Probe everything

`moprobe` + `ffmpeg-probe` — full format + streams + specific stream detail + packet-level bitstream dump when needed. `moprobe --color` for HDR side data.

### Step 2 — MediaInfo deep diagnostics

`media-mediainfo` (`--Output=JSON|XML|HTML`). Shows encoded-library, CABAC/trellis/B-pyramid, source framerate variance, recording-device metadata, re-encode history. Use when ffprobe alone is insufficient.

### Step 3 — Quality metrics (VMAF / PSNR / SSIM)

`ffmpeg-quality` or `moqc`:

| Model | Use for |
|---|---|
| `vmaf_v0.6.1` | PC monitor (1920×1080 default) |
| `vmaf_v0.6.1neg` | No-enhancement (catches sharpening cheats) |
| `vmaf_4k_v0.6.1` | 4K TVs |
| `vmaf_b_v0.6.3` | Mobile / phone |

Interpretation: ≥ 95 transparent, ≥ 80 excellent, ≥ 70 good, ≥ 60 acceptable, < 60 visible loss.

### Step 4 — Scene detection

`media-scenedetect` (content method, default threshold 27). Lower (15–20) for gradual transitions; higher (35–40) for abrupt cuts only. Inline `scdet` filter in ffmpeg if you don't need PySceneDetect's graph output.

### Step 5 — Crop / silence / black / interlacing

`ffmpeg-detect`:
- `cropdetect` — auto-detect letterbox/pillarbox, emits `crop` filter args.
- `silencedetect` — `-35 dB` default for dialogue, `-50 dB` for music.
- `blackdetect` — `pic_th` 0–1 luma threshold (0.98 = near-pure-black).
- `idet` — counts fields: high TFF/BFF = interlaced, high Progressive = progressive, mixed ~60/40 = telecined (use `workflow-ai-enhancement` or `ffmpeg-ivtc` to recover).

### Step 6 — ffplay scopes

`ffmpeg-playback` — waveform, vectorscope, histogram live.

### Step 7 — Bitstream forensics

`ffmpeg-bitstream`:
- NAL dump (HEVC SPS=33, H.264 SPS=7).
- SEI dump for HDR metadata / captions / DoVi / HDR10+.

### Step 8 — Metadata audit

`media-exiftool` (image / video EXIF, XMP, IPTC). `ffmpeg-metadata` for chapter + MKV tags.

### Step 9 — Content verification with CV/AI

`media-ocr-ai` for burned text; `cv-mediapipe` for face presence; `media-tag` CLIP/SigLIP for zero-shot content tags.

### Step 10 — Loudness compliance

`media-ffmpeg-normalize --measure-only` (non-destructive). Compare to spec:

| Spec | Integrated | True peak |
|---|---|---|
| Spotify Master | −14 LUFS ± 2 | −2 dBTP |
| Apple Podcasts | −16 LUFS ± 1 | −1 dBTP |
| ATSC A/85 | −24 LUFS ± 2 | − |
| EBU R128 | −23 LUFS ± 0.5 | −1 dBTP |

### Step 11 — Automated CI QC gates

`moqc --ref source --out encoded --format json --vmaf-min 93` exits non-zero on failure. Wire into CI to fail builds that would ship broken encodes.

## Variants

- **Regression suite** — new encoder vs golden corpus, VMAF per source.
- **Streaming monitor** — every 60 s, capture 10 s, VMAF against golden.
- **Bulk spec validation** — `media-batch` parallel validate.
- **Interactive debugging** — ffplay with PTS overlay, vectorscope + waveform side-by-side.
- **ABR ladder compare** — VMAF per rung to tune quality.
- **Broadcast spec QC** — color legality (`signalstats`), interlacing (`idet`), timecode continuity, caption presence, ATSC A/85 loudness.

## Gotchas

- **VMAF reference and distorted MUST match duration and frame rate.** Mismatch = silent aligner failure → meaningless score.
- **VMAF prefers matching resolution.** If distorted is lower-res, it upscales silently. Downscale reference explicitly for HD-vs-4K comparison.
- **VMAF default model (`vmaf_v0.6.1`) is for PC monitors.** Pick `_4k`, `_mobile`, `_neg` per target.
- **PSNR-YUV vs PSNR-Y-only.** ffmpeg reports overall; Y-only via `psnr=...y`.
- **Frame drops or duplications break VMAF sync.** Need 1:1 correspondence.
- **Different YUV ranges (limited vs full)** change perceptual VMAF. Clamp to same range before compare.
- **Scene-detect threshold 27 default:** gradual transitions need 15–20, abrupt cuts tolerate 35–40.
- **`cropdetect` samples every N seconds.** Variable content = inconsistent reads. Longer duration = reliable.
- **`silencedetect -35 dB` is dialogue.** Music is −50 dB; noise floor is −60 dB.
- **`idet` gives counts, not decisions.** TFF ≈ 2.5× Progressive = telecined (5 fields per 4 frames).
- **`blackdetect pic_th` is 0–1 picture-luma, NOT dB.** 0.98 = near-pure-black only.
- **MediaInfo "Encoded Library" is a heuristic.** Re-encoded files may show wrong encoder.
- **`ffprobe duration_ts` is in stream timebase; `duration` is in seconds.** Don't conflate.
- **`nb_frames=0` means unknown** (stream not fully parsed). Use `-count_frames` for accurate.
- **ExifTool writes in place by default.** `-overwrite_original` strips backups.
- **NAL types differ between H.264 and HEVC.** Don't swap: H.264 SPS = 7, HEVC SPS = 33.
- **SEI messages in HEVC use type+size+payload** with UUID-prefixed T.35 for DoVi / HDR10+ / captions.
- **Bitstream analysis on encrypted content fails.** Widevine / FairPlay encrypt the essence below the container.
- **`ffplay` blocks.** Use `-autoexit` to exit after duration or background with `&`.
- **`ffprobe -show_streams` is INI-style by default.** Use `-of json` or `-of csv=p=0` for scripting.
- **`jq -r` drops quotes.** Omit `-r` if downstream needs JSON.
- **MediaInfo CLI `--Output=JSON` is version-gated.** v21+ produces much better JSON than v20.
- **VMAF motion metric is I/O-bound** on large sources. Use SSDs.
- **Non-deterministic encoders (x265 with threads) produce slightly different output per run.** Expect ± 0.5 VMAF variance between runs of the same command.

## Example — CI gate on an encoded asset

`moprobe --color source.mov` → sanity-check tags. `moqc --ref source.mov --out encoded.mp4 --vmaf-min 93 --format json` → fail build non-zero. `ffmpeg-detect silencedetect` confirms no > 2 s dead air. `media-ffmpeg-normalize --measure-only` confirms −16 LUFS ± 1.

## Related

- Every other workflow — this is the gate.
- `workflow-broadcast-delivery` — broadcast-spec QC subset.
- `workflow-streaming-distribution` — ABR rung comparison.