{"id":23954,"plugin_id":"plugins_6ab29d7144e88191985ee28372ab8058","kind":"skill","collection_source":null,"comparison_source":null,"observed_at":"2026-09-30T23:17:50.794Z","digest":"f5d73a382e5d44a1445c4013066608cfc72e7cc1e5131f61d9684fa46f380045","against":null,"payload":{"name":"ffmpeg-diagnostics","description":"Diagnose FFmpeg media failures and apply observation-driven timestamp or normalization repairs. Use for corrupt packets, decode errors, malformed timestamps, CFR/VFR issues, timebase mismatches, stream mapping failures, filter graph errors, freezes, and compatibility problems.","included_files":[{"relative_path":"references/diagnostics-reference.md","size_in_bytes":1136},{"relative_path":"scripts/run.mjs","size_in_bytes":3122}],"skill_md_contents":"---\nname: ffmpeg-diagnostics\ndescription: Diagnose FFmpeg media failures and apply observation-driven timestamp or normalization repairs. Use for corrupt packets, decode errors, malformed timestamps, CFR/VFR issues, timebase mismatches, stream mapping failures, filter graph errors, freezes, and compatibility problems.\n---\n\n# FFmpeg Diagnostics\n\nUse this skill when the media or FFmpeg operation is failing and the defect must be identified before repair.\n\n## Activation scope\n\nUse for:\n\n- PTS/DTS or non-monotonic timestamp errors;\n- timebase/FPS/CFR/VFR problems;\n- corrupt packets or decode errors;\n- stream mapping failures;\n- filter graph reinitialization failures;\n- frozen frames;\n- unexpected missing streams;\n- codec/container/pixel-format compatibility issues.\n\n## Do not use\n\nDo not apply repair profiles blindly to healthy media. Do not use a generic re-encode as the first response when the toolkit can diagnose the observed defect.\n\n## Required inputs\n\nCollect:\n\n- failing media path;\n- FFmpeg stderr/log when available;\n- whether deeper freeze detection is needed;\n- desired output constraints if repair is requested.\n\n## Preflight workflow\n\n1. Run:\n   `cecilia-ffmpeg diagnose <input> --json`.\n2. If the user supplied an FFmpeg log, include it with `--log`.\n3. Use `--deep` only when freeze analysis is relevant.\n4. Choose a repair based on observed issues.\n\n## Toolkit surface selection\n\nUse the highest-level toolkit surface available to the host:\n\n1. Use the associated `scripts/run.mjs` entry point for supported diagnostic and repair actions.\n2. For `repair timestamps` and `repair normalize`, use the global `cecilia-ffmpeg` binary.\n3. If the global binary is unavailable, use:\n   `npm exec --yes --package=@cecilialabs/ffmpeg -- cecilia-ffmpeg <command>`.\n4. Use native FFmpeg only for unsupported repair cases or an explicit native-command request.\n\n## Associated scripts\n\nUse `scripts/run.mjs` with `input.action` `diagnose`, `repair-timestamps`, or\n`repair-normalize`. Diagnosis accepts an optional log path and deep freeze\nscan settings; repair actions keep the output transactional and return\nbefore/after issue sets.\n\n```bash\nprintf '%s\\n' '{\"context\":\"codex\",\"input\":{\"action\":\"diagnose\",\"input\":\"broken.mp4\",\"deep\":true}}' \\\n  | node skills/ffmpeg-diagnostics/scripts/run.mjs\n```\n\n## Preferred toolkit commands\n\n```bash\ncecilia-ffmpeg diagnose <input>\ncecilia-ffmpeg repair timestamps <input>\ncecilia-ffmpeg repair normalize <input>\n```\n\nFor supported operations, prefer the toolkit surface selected above over constructing arbitrary FFmpeg shell commands.\n\n## Native FFmpeg fallback\n\nUse native FFmpeg only for unsupported repair cases or when explicitly requested. Preserve the diagnosis and explain what the fallback is intended to fix.\n\n## Output expectations\n\nDiagnostics should identify issue codes/severity and supporting observations. Repair reports should include before/after diagnostics when execution completes.\n\n## Validation\n\nAfter repair:\n\n1. FFprobe the output.\n2. Re-run diagnosis.\n3. Verify requested normalized properties.\n4. Do not declare success solely because FFmpeg returned exit code 0.\n\n## Error recovery\n\n- Non-monotonic timestamps: prefer timestamp repair/normalization.\n- FPS/timebase mismatch: normalize timing before composition.\n- Filter graph error: inspect input properties and filter requirements rather than repeatedly re-running.\n- Stream mapping error: verify actual streams with FFprobe.\n- Corrupt decode: preserve evidence and avoid misleading “fixed” claims when source damage remains.\n\n## Safety and determinism\n\nRepairs write to a new transactional output. Never overwrite the source implicitly. Diagnosis is read-only.\n\n## References\n\nRead `references/diagnostics-reference.md` for issue-to-action mapping.\n"},"changes":[],"summary":"First saved snapshot. No earlier version is available for comparison.","summary_kind":"deterministic","summary_metadata":{}}