{"id":23951,"plugin_id":"plugins_6ab29d7144e88191985ee28372ab8058","kind":"skill","collection_source":null,"comparison_source":null,"observed_at":"2026-09-30T23:17:50.763Z","digest":"7b2aa3ad32088f89de84d9d25bbb79af90927488a81648fca04fe8dd6af0bd03","against":null,"payload":{"description":"Convert individual media files or directory batches using typed FFmpeg profiles, deterministic output planning, filtering, concurrency, and structured reports. Use when the primary goal is format/container/image-animation conversion.","included_files":[{"relative_path":"references/conversion-reference.md","size_in_bytes":848},{"relative_path":"scripts/run.mjs","size_in_bytes":4009}],"name":"ffmpeg-conversion","skill_md_contents":"---\nname: ffmpeg-conversion\ndescription: Convert individual media files or directory batches using typed FFmpeg profiles, deterministic output planning, filtering, concurrency, and structured reports. Use when the primary goal is format/container/image-animation conversion.\n---\n\n# FFmpeg Conversion\n\nUse this skill for supported single-file and batch format conversions.\n\n## Activation scope\n\nUse for:\n\n- video conversion between MP4/WebM and supported animation targets;\n- image conversion among GIF, WebP, PNG, and JPEG/JPG;\n- audio conversion among WAV, MP3, AAC, M4A, FLAC, Opus, and Ogg;\n- extracting an audio-only target from media that contains video;\n- directory batch conversions with selection and output policies.\n\n## Do not use\n\nDo not use conversion as a substitute for composition, repair, or editing when format change is incidental. Use the corresponding domain skill first.\n\n## Required inputs\n\nIdentify:\n\n- source file or directory;\n- source format for batch selection;\n- target format;\n- output directory/path;\n- recursion, include/exclude patterns, concurrency, and existing-output policy when batching.\n\n## Preflight\n\nProbe source media when encoding decisions depend on audio/video presence. In batches, discover the selection before conversion and surface empty selections or output collisions explicitly.\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 conversion actions.\n2. For directory batch conversion, 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 format pairs or an explicit native-command request.\n\nFor MP4/H.264 and WebM/VP9 targets, the CLI and associated script also accept the current hardware policy introduced in v1.2: `software`, `auto`, `nvenc`, `qsv`, `vaapi`, or `videotoolbox` where codec/backend support exists.\n\n## Associated scripts\n\nUse `scripts/run.mjs` with `input.action` `file` or `batch`. File requests\nrequire `input` and `to`; batch requests require `directory`, `from`, and\n`to`. Include selection, concurrency, and existing-output policy in the JSON\nrequest instead of reproducing traversal in a shell loop.\n\n```bash\nprintf '%s\\n' '{\"context\":\"codex\",\"input\":{\"action\":\"file\",\"input\":\"clip.mp4\",\"to\":\"webm\",\"output\":\"clip.webm\"}}' \\\n  | node skills/ffmpeg-conversion/scripts/run.mjs\n```\n\n## Preferred toolkit commands\n\n```bash\ncecilia-ffmpeg convert file <input> --to <format>\ncecilia-ffmpeg convert batch <directory> --from <format> --to <format>\n```\n\nPrefer toolkit profiles over ad-hoc per-file shell loops.\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 format pairs or explicitly requested native syntax. Do not duplicate batch traversal logic in shell; keep selection/output planning deterministic.\n\n## Output expectations\n\nBatch reports should distinguish discovered, attempted, succeeded, failed, and skipped items. File output should be probed after conversion.\n\n## Validation\n\nVerify target codec/container/image/audio format, stream presence, dimensions/FPS or sample-rate/channel properties where relevant, and all requested batch items.\n\n## Error recovery\n\n- On partial batch failure, preserve successful outputs and report failed items.\n- Resolve output collisions before execution.\n- Use `existing=skip|replace|error` intentionally.\n- If a target encoder is missing, inspect environment capabilities rather than silently switching formats.\n\n## Safety and determinism\n\nNo implicit overwrite. No shared temporary wildcard files. Preserve directory hierarchy unless flattening was explicitly requested.\n\n## References\n\nRead `references/conversion-reference.md` for supported profiles and batch planning.\n"},"changes":[],"summary":"First saved snapshot. No earlier version is available for comparison.","summary_kind":"deterministic","summary_metadata":{}}