Update to Cecil-IA Labs FFmpeg

{
  "name": "ffmpeg-pipelines",
  "description": "Design, validate, and execute deterministic Cecil-IA Labs FFmpeg Media Toolkit YAML pipelines and reusable presets across multiple media operations.",
  "included_files": [
    {
      "relative_path": "references/pipeline-schema.md",
      "size_in_bytes": 1957
    },
    {
      "relative_path": "scripts/run.mjs",
      "size_in_bytes": 2405
    }
  ],
  "skill_md_contents": "---\nname: ffmpeg-pipelines\ndescription: Design, validate, and execute deterministic Cecil-IA Labs FFmpeg Media Toolkit YAML pipelines and reusable presets across multiple media operations.\n---\n\n# FFmpeg Declarative Pipelines\n\n## Activation scope\n\nUse this skill when a task requires two or more supported media transformations to be expressed or executed as one declarative workflow, when reusable named presets are useful, or when an agent should produce a deterministic YAML job instead of a sequence of ad-hoc shell commands.\n\nTypical requests include:\n\n- trim then resize then convert;\n- apply the same resize/format preset to multiple jobs;\n- author or review a `pipeline.yaml`;\n- execute a pipeline through the associated script or CLI;\n- inspect a pipeline with dry-run before media mutation.\n\n## Do not use\n\nDo not use this skill for:\n\n- one simple operation that already maps directly to a single toolkit command/tool;\n- live streaming workflows;\n- arbitrary FFmpeg filter graphs not represented by the pipeline v1 schema;\n- hidden shell scripting inside YAML;\n- remote pipeline files that have not been made available to the local toolkit filesystem.\n\n## Required inputs\n\nResolve or ask for:\n\n1. the input media path;\n2. the ordered transformations;\n3. the final output path;\n4. any explicit final codec assertion;\n5. whether reusable presets are desired;\n6. overwrite policy;\n7. hardware policy when resize/conversion should use acceleration.\n\nWhen editing an existing pipeline, preserve its explicit ordering and relative-path semantics unless the user asks for a structural change.\n\n## Preflight\n\nBefore execution:\n\n1. validate YAML syntax and the pipeline v1 schema;\n2. resolve the input relative to the pipeline file directory;\n3. expand all preset references;\n4. reject missing presets and recursive preset cycles;\n5. validate final output extension/codec consistency;\n6. use dry-run when the user wants inspection before mutation.\n\nDo not assume that an FFmpeg encoder being compiled means it is usable. Hardware-aware steps inherit the toolkit runtime-probe policy.\n\n## Toolkit surface selection\n\nUse the highest-level toolkit surface available:\n\n1. Use the associated `scripts/run.mjs` entry point for supported pipeline actions.\n2. Otherwise use the namespaced `cecilia-ffmpeg pipeline <file> <action>` command.\n3. If the global binary is unavailable, use:\n   `npm exec --yes --package=@cecilialabs/ffmpeg -- cecilia-ffmpeg pipeline <file> <action>`.\n4. Use individual toolkit tools/commands only when the user explicitly wants step-by-step execution rather than a pipeline.\n5. Use native FFmpeg only when pipeline v1 cannot represent the required operation or the user explicitly requests native syntax.\n\n## Associated scripts\n\nUse `scripts/run.mjs` with `input.action` `validate`, `print`, or `run` and\nprovide `input.file`, `input.text`, or a parsed `input.document`. It uses the\nsame schema, preset expansion, output preflight, and execution functions as\nthe namespaced CLI. Set top-level `dryRun: true` for a plan without mutation.\n\nDry-run validates schema, output contracts, and statically knowable step\ntransitions only. It does not execute FFmpeg or prove input-specific codec,\nfilter, timing, or intermediate-media compatibility. A dry-run response is\n`status: \"planned\"` and never authorizes announcing an artifact.\n\n```bash\nprintf '%s\\n' '{\"context\":\"codex\",\"input\":{\"action\":\"validate\",\"file\":\"pipeline.yaml\"}}' \\\n  | node skills/ffmpeg-pipelines/scripts/run.mjs\n```\n\n## Preferred toolkit commands\n\nValidate a file:\n\n```bash\ncecilia-ffmpeg pipeline pipeline.yaml validate\n```\n\nPrint the normalized plan:\n\n```bash\ncecilia-ffmpeg pipeline pipeline.yaml print\n```\n\nValidate and plan immediately before execution:\n\n```bash\ncecilia-ffmpeg pipeline pipeline.yaml run --dry-run\n```\n\nExecute:\n\n```bash\ncecilia-ffmpeg pipeline pipeline.yaml run\n```\n\nAgent-readable result:\n\n```bash\ncecilia-ffmpeg pipeline pipeline.yaml run --json\n```\n\nPreserve intermediate artifacts for debugging:\n\n```bash\ncecilia-ffmpeg pipeline pipeline.yaml run --keep-temp\n```\n\nInline pipelines use the same typed schema and step ordering without a YAML\nfile:\n\n```bash\ncecilia-ffmpeg pipeline \\\n  --step trim --input example.mp4 --trim-start 2 --output example.trim.mp4 \\\n  --step convert --input example.trim.mp4 --to webm --output example.webm \\\n  run\n```\n\nWithout a global install:\n\n```bash\nnpm exec --yes --package=@cecilialabs/ffmpeg -- cecilia-ffmpeg pipeline pipeline.yaml run\n```\n\n## Native FFmpeg fallback\n\nUse native FFmpeg only when the declarative schema lacks the required capability. Do not translate a valid toolkit pipeline into an arbitrary shell command merely because FFmpeg can perform the same operations.\n\nIf fallback is required, explain which pipeline limitation forced the fallback and keep shell interpolation out of generated commands.\n\n## Output expectations\n\nA valid pipeline must produce or plan:\n\n- one resolved source;\n- one final destination;\n- an expanded executable step sequence;\n- deterministic intermediate ordering;\n- structured per-step warnings/details;\n- final FFprobe media information after actual execution.\n\nRelative media paths are relative to the pipeline file directory. Intermediate artifacts are isolated and cleaned automatically unless `--keep-temp` / `keep_temp=true` is explicit.\n\n## Validation\n\nAfter authoring a pipeline:\n\n1. use `pipeline <file> validate` for schema and output-contract validation;\n2. use `pipeline <file> print` to inspect the expanded normalized plan;\n3. run `pipeline <file> run --dry-run` when practical;\n4. confirm preset expansion order;\n5. verify final extension and declared codec agree;\n6. after execution, inspect the final structured report or FFprobe metadata;\n7. verify hardware-aware steps resolved the intended backend when hardware was requested.\n\n## Error recovery\n\nFor schema errors, fix the reported field path rather than loosening validation.\n\nFor missing presets, either define the preset or replace the reference with concrete steps.\n\nFor preset cycles, break the recursive reference chain.\n\nFor final-output conflicts, align `output.path`, `output.codec`, and the final `convert.to` or `resize.to`.\n\nFor media-domain failures, inspect the failing step's structured details and retry only after correcting that specific operation.\n\n## Safety and determinism\n\n- Never hide shell commands inside the YAML document.\n- Never overwrite final output unless overwrite is explicit.\n- Preserve declared step order.\n- Do not silently remove steps when a preset expands.\n- Treat pipeline dry-run as planning/validation only; it does not fabricate intermediate media.\n- Keep temporary artifacts only when explicitly requested.\n- Preserve the shared toolkit process boundary; pipeline execution must reuse typed domain functions.\n\n## References\n\nSee [references/pipeline-schema.md](references/pipeline-schema.md).\n"
}