Cecil-IA Labs FFmpeg

View saved version →

---
name: ffmpeg-audio
description: Attach, generate, detect, remove, and transcode audio with FFmpeg, including silence workflows and telephony formats such as G.711 μ-law, G.711 A-law, GSM, and PCM. Use when audio is the primary media concern.
---

# FFmpeg Audio

Use this skill for audio-first workflows. For attaching or adding silence tracks to video, prefer the canonical `video attach-audio` / `video add-silence` commands; the older audio-domain aliases remain compatible.

## Activation scope

Use for:

- attaching or replacing audio on video;
- generating silence;
- adding a silence track;
- detecting silence intervals;
- removing silence from audio-only media;
- telephony transcoding and codec/container clarification.

## Do not use

Do not use for video timing edits unless audio handling is secondary to the video operation. Do not use `remove-silence` on video when doing so would create A/V desynchronization; the toolkit intentionally restricts unsafe cases.

## Required inputs

Identify:

- input media;
- whether an existing audio track may be replaced;
- silence thresholds/durations when relevant;
- telephony codec, sample rate, channels, and container requirements.

## Preflight

Probe media when stream presence matters. Never assume a video lacks audio. For telephony, distinguish codec from container before building the command.

## Toolkit surface selection

Use the highest-level toolkit surface available to the host:

1. Use the associated `scripts/run.mjs` entry point for supported audio actions.
2. For silence detection, add-silence, telephony transcoding, or other supported audio operations, use `cecilia-ffmpeg`.
3. If the global binary is unavailable, use:
   `npm exec --yes --package=@cecilialabs/ffmpeg -- cecilia-ffmpeg <command>`.
4. Use native FFmpeg only when the toolkit lacks the required operation or the user explicitly requests native syntax.

## Associated scripts

Use `scripts/run.mjs` with `input.action` set to `attach`, `silence`,
`add-silence`, `detect-silence`, `remove-silence`, or `telephony`. Audio
inputs, codec/container choices, and output policy stay explicit in `input`;
the script returns typed intervals or an FFprobe-backed artifact report.

```bash
printf '%s\n' '{"context":"codex","input":{"action":"detect-silence","input":"speech.wav","noiseDb":-35,"minDuration":0.5}}' \
  | node skills/ffmpeg-audio/scripts/run.mjs
```

## Preferred toolkit commands

```bash
cecilia-ffmpeg video attach-audio <video> <audio>
cecilia-ffmpeg audio silence
cecilia-ffmpeg video add-silence <video>
cecilia-ffmpeg audio detect-silence <input> --json
cecilia-ffmpeg audio remove-silence <input>
cecilia-ffmpeg audio telephony <input>
```

For supported operations, prefer the toolkit surface selected above over constructing arbitrary FFmpeg shell commands.

## Native FFmpeg fallback

Use native FFmpeg only when the toolkit lacks the required audio transform or the user explicitly asks for it. Keep channel layout, sample rate, sample format, codec, and container explicit.

## Output expectations

Silence detection should return typed intervals. File-producing operations should preserve non-audio streams according to the command contract and validate the result with FFprobe.

## Validation

Verify:

- audio codec;
- sample rate;
- channel count/layout;
- expected stream count;
- duration changes for silence removal;
- intended preservation/replacement behavior.

## Error recovery

- If existing audio would be destroyed, require explicit replacement intent.
- If a codec/container pairing is invalid, correct the container or codec rather than changing labels.
- If silence removal on video would desynchronize A/V, do not proceed with the audio-only workflow.
- If the user says “GSM μ-law”, clarify that GSM and G.711 μ-law are distinct codecs.

## Safety and determinism

Do not silently replace audio tracks. Do not conflate G.711 μ-law/PCMU, G.711 A-law/PCMA, GSM, and PCM.

## References

Read `references/audio-reference.md` for silence and telephony details.

Referenced files: 2

View saved version →

---
name: ffmpeg-composition
description: Compose multiple media inputs with concatenation, xfade transitions, audio crossfades, normalization, and image slideshows. Use when two or more visual sources must become one timeline.
---

# FFmpeg Composition

Use this skill for multi-source video/image timeline construction.

## Activation scope

Use for:

- concatenating multiple clips;
- adding transitions between clips;
- composing two clips with a specific transition;
- image slideshows in vertical-stack or sequence style;
- sequence slideshows with transitions/include/exclude selection;
- `zoomin` and explicit custom `zoomout` transitions;
- workflows requiring normalization before `xfade`.

## Do not use

Do not use for single-file edits or repair. Do not choose non-standard filters such as `gltransition` unless environment capabilities confirm them and the toolkit path is insufficient.

## Required inputs

Identify:

- ordered inputs;
- transition type and duration;
- target dimensions/FPS;
- audio policy;
- slideshow duration/style/direction, transition, include/exclude patterns, and output format where relevant.

## Preflight

Probe every media input. Before transitions, normalize properties that FFmpeg requires to agree: scale/pad geometry, PTS, FPS, pixel format, and time base.

## Toolkit surface selection

Use the highest-level toolkit surface available to the host:

1. Use the associated `scripts/run.mjs` entry point for supported composition actions.
2. For explicit transition commands, slideshows, or other composition capabilities, use `cecilia-ffmpeg`.
3. If the global binary is unavailable, use:
   `npm exec --yes --package=@cecilialabs/ffmpeg -- cecilia-ffmpeg <command>`.
4. Use native FFmpeg only for unsupported composition graphs or an explicit native-command request.

## Associated scripts

Use `scripts/run.mjs` with `input.action` `concat`, `transition`, or
`slideshow`. Provide ordered `inputs` for concatenation, `left`/`right` for a
transition, or `directory` for a slideshow. The script preserves the typed
normalization and audio policy before execution.

```bash
printf '%s\n' '{"context":"codex","input":{"action":"concat","inputs":["one.mp4","two.mp4"],"transition":"fade","output":"joined.mp4"}}' \
  | node skills/ffmpeg-composition/scripts/run.mjs
```

## Preferred toolkit commands

```bash
cecilia-ffmpeg compose concat <inputs...>
cecilia-ffmpeg compose concat <inputs...> --transition fade
cecilia-ffmpeg compose transition <left> <right>
cecilia-ffmpeg compose slideshow <directory>
cecilia-ffmpeg compose slideshow <directory> --style sequence --transition zoomin
```

For supported operations, prefer the toolkit surface selected above over constructing arbitrary FFmpeg shell commands.

## Native FFmpeg fallback

Use native FFmpeg only for unsupported composition graphs or user-requested native syntax. Retain the same normalization discipline before `xfade`.

## Output expectations

Return a single deterministic output with explicit warnings when audio cannot be preserved automatically.

## Validation

Probe the final file and verify:

- expected total duration;
- target dimensions/FPS/pixel format;
- audio presence;
- transition completion without filter reinitialization/timebase errors.

## Error recovery

- For timebase/FPS mismatch, normalize before transition instead of retrying the same graph.
- For missing audio on one input, use an explicit audio policy rather than constructing an invalid `acrossfade`.
- For unsupported transition filters, select a native `xfade` transition or inspect capabilities.

## Safety and determinism

Preserve input order. Do not use `eval` or shell-expanded filter graphs. Keep normalization explicit and repeatable.

## References

Read `references/composition-reference.md` for normalization order and transition guidance.

Referenced files: 2

View saved version →

---
name: ffmpeg-conversion
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.
---

# FFmpeg Conversion

Use this skill for supported single-file and batch format conversions.

## Activation scope

Use for:

- video conversion between MP4/WebM and supported animation targets;
- image conversion among GIF, WebP, PNG, and JPEG/JPG;
- audio conversion among WAV, MP3, AAC, M4A, FLAC, Opus, and Ogg;
- extracting an audio-only target from media that contains video;
- directory batch conversions with selection and output policies.

## Do not use

Do not use conversion as a substitute for composition, repair, or editing when format change is incidental. Use the corresponding domain skill first.

## Required inputs

Identify:

- source file or directory;
- source format for batch selection;
- target format;
- output directory/path;
- recursion, include/exclude patterns, concurrency, and existing-output policy when batching.

## Preflight

Probe 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.

## Toolkit surface selection

Use the highest-level toolkit surface available to the host:

1. Use the associated `scripts/run.mjs` entry point for supported conversion actions.
2. For directory batch conversion, use the global `cecilia-ffmpeg` binary.
3. If the global binary is unavailable, use:
   `npm exec --yes --package=@cecilialabs/ffmpeg -- cecilia-ffmpeg <command>`.
4. Use native FFmpeg only for unsupported format pairs or an explicit native-command request.

For 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.

## Associated scripts

Use `scripts/run.mjs` with `input.action` `file` or `batch`. File requests
require `input` and `to`; batch requests require `directory`, `from`, and
`to`. Include selection, concurrency, and existing-output policy in the JSON
request instead of reproducing traversal in a shell loop.

```bash
printf '%s\n' '{"context":"codex","input":{"action":"file","input":"clip.mp4","to":"webm","output":"clip.webm"}}' \
  | node skills/ffmpeg-conversion/scripts/run.mjs
```

## Preferred toolkit commands

```bash
cecilia-ffmpeg convert file <input> --to <format>
cecilia-ffmpeg convert batch <directory> --from <format> --to <format>
```

Prefer toolkit profiles over ad-hoc per-file shell loops.

For supported operations, prefer the toolkit surface selected above over constructing arbitrary FFmpeg shell commands.

## Native FFmpeg fallback

Use 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.

## Output expectations

Batch reports should distinguish discovered, attempted, succeeded, failed, and skipped items. File output should be probed after conversion.

## Validation

Verify target codec/container/image/audio format, stream presence, dimensions/FPS or sample-rate/channel properties where relevant, and all requested batch items.

## Error recovery

- On partial batch failure, preserve successful outputs and report failed items.
- Resolve output collisions before execution.
- Use `existing=skip|replace|error` intentionally.
- If a target encoder is missing, inspect environment capabilities rather than silently switching formats.

## Safety and determinism

No implicit overwrite. No shared temporary wildcard files. Preserve directory hierarchy unless flattening was explicitly requested.

## References

Read `references/conversion-reference.md` for supported profiles and batch planning.

Referenced files: 2

View saved version →

---
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.
---

# FFmpeg Diagnostics

Use this skill when the media or FFmpeg operation is failing and the defect must be identified before repair.

## Activation scope

Use for:

- PTS/DTS or non-monotonic timestamp errors;
- timebase/FPS/CFR/VFR problems;
- corrupt packets or decode errors;
- stream mapping failures;
- filter graph reinitialization failures;
- frozen frames;
- unexpected missing streams;
- codec/container/pixel-format compatibility issues.

## Do not use

Do 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.

## Required inputs

Collect:

- failing media path;
- FFmpeg stderr/log when available;
- whether deeper freeze detection is needed;
- desired output constraints if repair is requested.

## Preflight workflow

1. Run:
   `cecilia-ffmpeg diagnose <input> --json`.
2. If the user supplied an FFmpeg log, include it with `--log`.
3. Use `--deep` only when freeze analysis is relevant.
4. Choose a repair based on observed issues.

## Toolkit surface selection

Use the highest-level toolkit surface available to the host:

1. Use the associated `scripts/run.mjs` entry point for supported diagnostic and repair actions.
2. For `repair timestamps` and `repair normalize`, use the global `cecilia-ffmpeg` binary.
3. If the global binary is unavailable, use:
   `npm exec --yes --package=@cecilialabs/ffmpeg -- cecilia-ffmpeg <command>`.
4. Use native FFmpeg only for unsupported repair cases or an explicit native-command request.

## Associated scripts

Use `scripts/run.mjs` with `input.action` `diagnose`, `repair-timestamps`, or
`repair-normalize`. Diagnosis accepts an optional log path and deep freeze
scan settings; repair actions keep the output transactional and return
before/after issue sets.

```bash
printf '%s\n' '{"context":"codex","input":{"action":"diagnose","input":"broken.mp4","deep":true}}' \
  | node skills/ffmpeg-diagnostics/scripts/run.mjs
```

## Preferred toolkit commands

```bash
cecilia-ffmpeg diagnose <input>
cecilia-ffmpeg repair timestamps <input>
cecilia-ffmpeg repair normalize <input>
```

For supported operations, prefer the toolkit surface selected above over constructing arbitrary FFmpeg shell commands.

## Native FFmpeg fallback

Use native FFmpeg only for unsupported repair cases or when explicitly requested. Preserve the diagnosis and explain what the fallback is intended to fix.

## Output expectations

Diagnostics should identify issue codes/severity and supporting observations. Repair reports should include before/after diagnostics when execution completes.

## Validation

After repair:

1. FFprobe the output.
2. Re-run diagnosis.
3. Verify requested normalized properties.
4. Do not declare success solely because FFmpeg returned exit code 0.

## Error recovery

- Non-monotonic timestamps: prefer timestamp repair/normalization.
- FPS/timebase mismatch: normalize timing before composition.
- Filter graph error: inspect input properties and filter requirements rather than repeatedly re-running.
- Stream mapping error: verify actual streams with FFprobe.
- Corrupt decode: preserve evidence and avoid misleading “fixed” claims when source damage remains.

## Safety and determinism

Repairs write to a new transactional output. Never overwrite the source implicitly. Diagnosis is read-only.

## References

Read `references/diagnostics-reference.md` for issue-to-action mapping.

Referenced files: 2

View saved version →

---
name: ffmpeg-environment
description: Inspect, validate, and troubleshoot FFmpeg/FFprobe installations, versions, codecs, filters, hardware backends, and media metadata. Use before media work when runtime capabilities are unknown, when a command depends on a codec/filter/accelerator, or when diagnosing environment-specific failures.
---

# FFmpeg Environment

Use this skill to establish what the local FFmpeg environment can actually do before choosing a media workflow.

## Activation scope

Use when the task involves environment readiness, FFmpeg/FFprobe discovery, version compatibility, codec/filter availability, hardware acceleration discovery, or media inspection with FFprobe.

## Do not use

Do not use this skill as the primary workflow for editing, audio processing, conversion, composition, streaming, or repair when the required environment facts are already known. Route those tasks to the corresponding domain skill.

## Required inputs

Collect only what is needed:

- the media path when probing a file;
- the required codec, encoder, decoder, filter, or hardware backend when capability-specific;
- explicit FFmpeg/FFprobe paths only when the user supplied or needs non-default binaries.

## Preflight workflow

1. Prefer the toolkit:
   `cecilia-ffmpeg doctor`.
2. For machine-readable capability data, use:
   `cecilia-ffmpeg environment capabilities --json`.
3. For version checks, use:
   `cecilia-ffmpeg environment version --json`.
4. For media inspection, use:
   `cecilia-ffmpeg probe <input> --json`.
5. Do not infer runtime support from package names or operating-system assumptions when the toolkit can inspect it directly.

## Toolkit surface selection

Use the highest-level toolkit surface available to the host:

1. Use the associated `scripts/inspect.mjs` entry point for supported inspection actions.
2. For `doctor`, version checks, and capability inspection, use the global `cecilia-ffmpeg` binary.
3. If the global binary is unavailable, use:
   `npm exec --yes --package=@cecilialabs/ffmpeg -- cecilia-ffmpeg <command>`.
4. Use native FFmpeg/FFprobe only when the toolkit lacks the required inspection or the user explicitly requests native syntax.

## Associated scripts

Use `scripts/inspect.mjs` for JSON-in/JSON-out inspection without shell
parsing. Set `input.action` to `doctor`, `capabilities`, `version`, or `probe`
and provide `input.input` for a media probe. The script uses the shared Skill
result envelope and keeps regular Chat in a planned state.

```bash
printf '%s\n' '{"context":"codex","input":{"action":"capabilities"}}' \
  | node skills/ffmpeg-environment/scripts/inspect.mjs
```

## Preferred toolkit commands

Prefer `@cecilialabs/ffmpeg` over ad-hoc shell parsing of `ffmpeg -version`, `-encoders`, `-filters`, or `ffprobe` output.

## Native FFmpeg fallback

Use native FFmpeg/FFprobe only when the toolkit does not expose the required inspection or the user explicitly requests the native invocation.

## Output expectations

Report observed facts separately from interpretation:

- resolved binary paths;
- parsed versions;
- capability counts or specific matched capabilities;
- relevant hardware backend compile support;
- normalized media stream metadata;
- any limitation that is compile-time-only rather than proof of usable hardware.

## Validation

For environment-dependent work, validate the exact required capability, not merely that FFmpeg launches.

For media work, use FFprobe-derived stream properties rather than filename extensions as the source of truth.

## Error recovery

- If FFmpeg or FFprobe is not found, confirm PATH or explicit binary overrides.
- If a capability is missing, do not invent an equivalent; choose a supported codec/filter or explain the installation/build requirement.
- If hardware support is reported but execution fails, distinguish compiled support from runtime device/driver availability.
- If probing fails, preserve the original error and avoid destructive media operations.

## Safety and determinism

Environment inspection should be read-only. Do not install packages, change PATH, or alter system configuration unless the user explicitly requests it.

Prefer JSON output for agent workflows and stable comparison.

## References

Read `references/environment-reference.md` for command details, capability interpretation, and troubleshooting patterns.

Referenced files: 2

View saved version →

---
name: ffmpeg-onboarding
description: Inspect and prepare an FFmpeg execution environment, routing capability checks and explicit installation guidance across ChatGPT, Work, Codex, and IDE hosts. Use before media work when the execution context or runtime availability is unknown.
---

# FFmpeg Onboarding

## Activation scope

Use this Skill when the host, Node.js/npm runtime, FFmpeg/FFprobe
installation, toolkit CLI, codec/filter support, or hardware capability is
unknown or needs explicit verification before media work.

Use it first when a user asks whether the current environment can execute a
workflow, requests installation guidance, or reports that a command works on
one host but not another.

## Do not use

Do not use this Skill as the primary workflow for editing, conversion,
composition, streaming, diagnosis, or pipeline authoring once the required
environment facts are known. Hand off to the matching domain Skill or to
ffmpeg-workflow.

Do not claim that a command ran when the host only supports copy/paste
instructions.

## Required inputs

Collect only what is needed:

- the execution context, if known;
- the requested media operation or required capability;
- the operating system and shell only when installation or command syntax
  depends on them;
- explicit authorization before installing packages or changing PATH/system
  configuration.

## Preflight

1. Identify which execution context is actually available. Do not infer local
   file or shell access from the conversation alone.
2. Inspect Node.js, npm, FFmpeg, FFprobe, and cecilia-ffmpeg without mutation.
3. Prefer toolkit capability and version inspection over parsing ad-hoc
   FFmpeg output.
4. Separate observed facts from recommendations and installation steps.
5. After an authorized installation, repeat the same checks and report the
   resolved executable paths and versions.

The onboarding script can complete the diagnostic while leaving the host
unready. Use `output.status` as the readiness decision: only `ready` permits
the next media Skill. `warning` or `blocked` requires the listed remediation
and a new check; the outer envelope uses `status: "needs-input"` for those
states and exposes the same warnings at the top level.

## Toolkit surface selection

Use the highest-level executable surface available:

1. use a Skill-associated script when the requested onboarding action exists;
2. otherwise use the global cecilia-ffmpeg binary;
3. otherwise use the explicit npm package-runner fallback below;
4. use native FFmpeg/FFprobe only when the toolkit lacks the required
   inspection or the user explicitly requests native commands.

This Skill is script/CLI-first and does not require a network service or an
alternate agent protocol.

## Associated scripts

From a checkout or installed package, send one JSON request on stdin and keep
the single JSON response as the source of truth:

    printf '%s\n' '{"context":"codex","input":{}}' | node skills/ffmpeg-onboarding/scripts/check.mjs

Plan an installation without changing anything:

    printf '%s\n' '{"context":"codex","input":{"scope":"local"}}' | node skills/ffmpeg-onboarding/scripts/install.mjs

An installation is only applied when the request contains both
`input.apply: true` and `input.authorized: true`. Supported scopes are
`global`, `local`, and `npm-exec`. The scripts never edit shell startup files,
interpolate shell commands, or claim that FFmpeg is ready from npm status alone.

## Preferred toolkit commands

For a read-only baseline, use:

    cecilia-ffmpeg doctor
    cecilia-ffmpeg environment check --json
    cecilia-ffmpeg environment version --json
    cecilia-ffmpeg environment capabilities --json

If the global binary is unavailable, use:

    npm exec --yes --package=@cecilialabs/ffmpeg -- cecilia-ffmpeg doctor

Use cecilia-ffmpeg probe INPUT --json when media metadata is part of the
readiness decision.

## Native FFmpeg fallback

Use native FFmpeg or FFprobe only when the required capability is not exposed
by the toolkit or the user explicitly asks for native syntax. Preserve the
observed error and do not silently substitute a different codec, filter, or
hardware path.

## Output expectations

Report:

- the execution context and whether it was observed or assumed;
- resolved paths for Node.js, npm, FFmpeg, FFprobe, and the toolkit CLI;
- versions and the exact capability relevant to the requested workflow;
- installation actions that were performed versus commands the user must run;
- the next domain Skill or workflow step.

## Validation

Validate the capability that the requested media workflow actually needs.
The existence of an executable alone does not prove codec, filter, device, or
hardware usability. After installation, repeat the checks from the same host.

## Error recovery

- If a binary is missing, distinguish PATH resolution from installation.
- If the toolkit is unavailable, use the explicit package-runner fallback and
  preserve its error output.
- If a codec/filter is missing, choose a supported workflow or explain the
  required FFmpeg build; do not invent an equivalent.
- If hardware is compiled in but runtime probing fails, report those as
  separate facts and fall back only when the user permits it.
- If the host cannot execute commands, stop at a reproducible guided flow.

## Safety and determinism

Environment inspection is read-only. Installation, shell startup changes,
package-manager actions, and device configuration require explicit
authorization. Never expose credentials or ask a regular chat host to expose
local media through a public domain or proxy.

## References

See references/execution-contexts.md for context routing, installation
boundaries, and result-reporting examples.

Referenced files: 4

View saved version →

---
name: ffmpeg-pipelines
description: Design, validate, and execute deterministic Cecil-IA Labs FFmpeg Media Toolkit YAML pipelines and reusable presets across multiple media operations.
---

# FFmpeg Declarative Pipelines

## Activation scope

Use 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.

Typical requests include:

- trim then resize then convert;
- apply the same resize/format preset to multiple jobs;
- author or review a `pipeline.yaml`;
- execute a pipeline through the associated script or CLI;
- inspect a pipeline with dry-run before media mutation.

## Do not use

Do not use this skill for:

- one simple operation that already maps directly to a single toolkit command/tool;
- live streaming workflows;
- arbitrary FFmpeg filter graphs not represented by the pipeline v1 schema;
- hidden shell scripting inside YAML;
- remote pipeline files that have not been made available to the local toolkit filesystem.

## Required inputs

Resolve or ask for:

1. the input media path;
2. the ordered transformations;
3. the final output path;
4. any explicit final codec assertion;
5. whether reusable presets are desired;
6. overwrite policy;
7. hardware policy when resize/conversion should use acceleration.

When editing an existing pipeline, preserve its explicit ordering and relative-path semantics unless the user asks for a structural change.

## Preflight

Before execution:

1. validate YAML syntax and the pipeline v1 schema;
2. resolve the input relative to the pipeline file directory;
3. expand all preset references;
4. reject missing presets and recursive preset cycles;
5. validate final output extension/codec consistency;
6. use dry-run when the user wants inspection before mutation.

Do not assume that an FFmpeg encoder being compiled means it is usable. Hardware-aware steps inherit the toolkit runtime-probe policy.

## Toolkit surface selection

Use the highest-level toolkit surface available:

1. Use the associated `scripts/run.mjs` entry point for supported pipeline actions.
2. Otherwise use the namespaced `cecilia-ffmpeg pipeline <file> <action>` command.
3. If the global binary is unavailable, use:
   `npm exec --yes --package=@cecilialabs/ffmpeg -- cecilia-ffmpeg pipeline <file> <action>`.
4. Use individual toolkit tools/commands only when the user explicitly wants step-by-step execution rather than a pipeline.
5. Use native FFmpeg only when pipeline v1 cannot represent the required operation or the user explicitly requests native syntax.

## Associated scripts

Use `scripts/run.mjs` with `input.action` `validate`, `print`, or `run` and
provide `input.file`, `input.text`, or a parsed `input.document`. It uses the
same schema, preset expansion, output preflight, and execution functions as
the namespaced CLI. Set top-level `dryRun: true` for a plan without mutation.

Dry-run validates schema, output contracts, and statically knowable step
transitions only. It does not execute FFmpeg or prove input-specific codec,
filter, timing, or intermediate-media compatibility. A dry-run response is
`status: "planned"` and never authorizes announcing an artifact.

```bash
printf '%s\n' '{"context":"codex","input":{"action":"validate","file":"pipeline.yaml"}}' \
  | node skills/ffmpeg-pipelines/scripts/run.mjs
```

## Preferred toolkit commands

Validate a file:

```bash
cecilia-ffmpeg pipeline pipeline.yaml validate
```

Print the normalized plan:

```bash
cecilia-ffmpeg pipeline pipeline.yaml print
```

Validate and plan immediately before execution:

```bash
cecilia-ffmpeg pipeline pipeline.yaml run --dry-run
```

Execute:

```bash
cecilia-ffmpeg pipeline pipeline.yaml run
```

Agent-readable result:

```bash
cecilia-ffmpeg pipeline pipeline.yaml run --json
```

Preserve intermediate artifacts for debugging:

```bash
cecilia-ffmpeg pipeline pipeline.yaml run --keep-temp
```

Inline pipelines use the same typed schema and step ordering without a YAML
file:

```bash
cecilia-ffmpeg pipeline \
  --step trim --input example.mp4 --trim-start 2 --output example.trim.mp4 \
  --step convert --input example.trim.mp4 --to webm --output example.webm \
  run
```

Without a global install:

```bash
npm exec --yes --package=@cecilialabs/ffmpeg -- cecilia-ffmpeg pipeline pipeline.yaml run
```

## Native FFmpeg fallback

Use 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.

If fallback is required, explain which pipeline limitation forced the fallback and keep shell interpolation out of generated commands.

## Output expectations

A valid pipeline must produce or plan:

- one resolved source;
- one final destination;
- an expanded executable step sequence;
- deterministic intermediate ordering;
- structured per-step warnings/details;
- final FFprobe media information after actual execution.

Relative media paths are relative to the pipeline file directory. Intermediate artifacts are isolated and cleaned automatically unless `--keep-temp` / `keep_temp=true` is explicit.

## Validation

After authoring a pipeline:

1. use `pipeline <file> validate` for schema and output-contract validation;
2. use `pipeline <file> print` to inspect the expanded normalized plan;
3. run `pipeline <file> run --dry-run` when practical;
4. confirm preset expansion order;
5. verify final extension and declared codec agree;
6. after execution, inspect the final structured report or FFprobe metadata;
7. verify hardware-aware steps resolved the intended backend when hardware was requested.

## Error recovery

For schema errors, fix the reported field path rather than loosening validation.

For missing presets, either define the preset or replace the reference with concrete steps.

For preset cycles, break the recursive reference chain.

For final-output conflicts, align `output.path`, `output.codec`, and the final `convert.to` or `resize.to`.

For media-domain failures, inspect the failing step's structured details and retry only after correcting that specific operation.

## Safety and determinism

- Never hide shell commands inside the YAML document.
- Never overwrite final output unless overwrite is explicit.
- Preserve declared step order.
- Do not silently remove steps when a preset expands.
- Treat pipeline dry-run as planning/validation only; it does not fabricate intermediate media.
- Keep temporary artifacts only when explicitly requested.
- Preserve the shared toolkit process boundary; pipeline execution must reuse typed domain functions.

## References

See [references/pipeline-schema.md](references/pipeline-schema.md).

Referenced files: 2

View saved version →

---
name: ffmpeg-streaming
description: Capture cameras or stream media files through FFmpeg using typed source, encoding, container, transport, and destination settings. Use for HTTP, RTMP, RTSP, SRT, UDP, or TCP streaming and for camera capture planning.
---

# FFmpeg Streaming

Use this skill for live capture and network media delivery.

## Activation scope

Use for:

- camera capture from V4L2, AVFoundation, or DirectShow;
- streaming a media file at playback rate;
- HTTP(S), RTMP(S), RTSP, SRT, UDP, or TCP destinations;
- choosing a transport-appropriate muxer and low-latency encoding.

## Do not use

Do not claim direct WebSocket support. If browser clients need WebSocket, model an explicit relay service. Do not use file-output transactional semantics for live network destinations.

## Required inputs

Identify:

- source kind: camera or file;
- camera device and capture backend when applicable;
- destination URL;
- transport/container when not inferable;
- video/audio codec policy;
- bitrate/GOP/preset constraints.

## Preflight

For file sources, probe before streaming. For camera sources, use `--dry-run` to validate the planned invocation without opening the device.

## Toolkit surface selection

1. Use the associated `scripts/run.mjs` entry point for supported streaming and capture operations.
2. If the global binary is unavailable, use:
   `npm exec --yes --package=@cecilialabs/ffmpeg -- cecilia-ffmpeg <command>`.
3. Use native FFmpeg only for unsupported streaming features or an explicit native-command request.

## Associated scripts

Use `scripts/run.mjs` with `input.action` `file` or `camera`. File requests
require `input` and `url`; camera requests require `device` and `url`. The
script produces a validated transport/encoding plan and only reports live
execution when the active host actually ran it.

```bash
printf '%s\n' '{"context":"codex","input":{"action":"file","input":"clip.mp4","url":"srt://example.test:9000"}}' \
  | node skills/ffmpeg-streaming/scripts/run.mjs
```

## Preferred toolkit commands

```bash
cecilia-ffmpeg stream camera --device <device> --url <url>
cecilia-ffmpeg stream file <input> --url <url>
```

Supported direct transport families: HTTP(S), RTMP(S), RTSP, SRT, UDP, TCP.

For supported operations, prefer the toolkit surface selected above over constructing arbitrary FFmpeg shell commands.

## Native FFmpeg fallback

Use native FFmpeg only for unsupported streaming features or explicit user requests. Maintain strict separation between input capture format, media encoding, muxer/container, and network transport.

## Output expectations

A dry run should expose the complete plan without opening sockets. A live run remains active until input completion, receiver failure, or cancellation.

## Validation

Validate URL scheme/transport agreement, muxer compatibility, encoder availability, and receiver expectations. For network problems, distinguish FFmpeg encoding failure from receiver/connectivity failure.

## Error recovery

- For a `ws://`/`wss://` destination, require an explicit relay architecture.
- For RTMP use FLV; for RTSP use the RTSP muxer; for generic HTTP/SRT/UDP/TCP use MPEG-TS in the current toolkit.
- If a receiver rejects the stream, verify its expected codec/container and listening mode.
- If a camera cannot open, verify device path/name, capture backend, permissions, and supported mode.

## Safety and determinism

Never expose credentials embedded in streaming URLs in unnecessary logs. Use cancellation through the shared runtime; do not kill unrelated FFmpeg processes.

## References

Read `references/streaming-reference.md` for transport and capture details.

Referenced files: 2

View saved version →

---
name: ffmpeg-video-editing
description: Perform deterministic video trimming, speed changes, still-image video creation, resizing, restoration, and normalization with FFmpeg. Use for temporal edits and single-video transformations that do not primarily require multi-source composition.
---

# FFmpeg Video Editing

Use this skill for typed single-video editing operations.

## Activation scope

Use for:

- removing time from the start or end;
- extracting a temporal range;
- changing playback speed;
- creating video from a still image;
- resizing/upscaling/restoration;
- normalizing a video for downstream processing.

## Do not use

Do not use for multi-input transitions or slideshows; use `ffmpeg-composition`. Do not use for audio-first tasks; use `ffmpeg-audio`. Do not use repair commands when the primary problem is malformed timestamps or decoding errors; use `ffmpeg-diagnostics`.

## Required inputs

Identify:

- input file;
- desired temporal range or speed factor;
- output path when the default is unsuitable;
- whether audio must be preserved, retimed, or dropped;
- target resolution/profile and fit mode for upscale work.

## Preflight

1. Probe the input before operations where duration, audio presence, codec, or dimensions affect the plan.
2. Use `--dry-run` when the user wants to inspect the FFmpeg invocation first.
3. Preserve audio unless the requested operation or explicit policy says otherwise.

## Toolkit surface selection

Use the highest-level toolkit surface available to the host:

1. Use the associated `scripts/run.mjs` entry point for supported video actions.
2. For speed changes, still-image video creation, trim-start/trim-end convenience commands, or other supported video operations, use `cecilia-ffmpeg`.
3. If the global binary is unavailable, use:
   `npm exec --yes --package=@cecilialabs/ffmpeg -- cecilia-ffmpeg <command>`.
4. Use native FFmpeg only for unsupported transforms or an explicit native-command request.

## Associated scripts

Use `scripts/run.mjs` with `input.action` set to `trim-start`, `trim-end`,
`trim`, `speed`, `from-image`, `restore`, or `upscale`. Common fields include
`input`, `output`, `overwrite`, and the operation-specific fields for the
selected action. The script calls the typed video domain directly and returns
the shared result envelope.

```bash
printf '%s\n' '{"context":"codex","input":{"action":"trim-start","input":"clip.mp4","seconds":5,"output":"clip.trimmed.mp4"}}' \
  | node skills/ffmpeg-video-editing/scripts/run.mjs
```

## Preferred toolkit commands

```bash
cecilia-ffmpeg video trim-start <input> --seconds <n>
cecilia-ffmpeg video trim-end <input> --seconds <n>
cecilia-ffmpeg video trim <input> --start <n> --end <n>
cecilia-ffmpeg video speed <input> --factor <n>
cecilia-ffmpeg video from-image <image> --duration <n>
cecilia-ffmpeg video upscale <input> --resolution <WxH>
cecilia-ffmpeg video attach-audio <video> <audio>
cecilia-ffmpeg video add-silence <video>
```

Prefer the toolkit over constructing arbitrary shell commands for supported operations.

For supported operations, prefer the toolkit surface selected above over constructing arbitrary FFmpeg shell commands.

## Native FFmpeg fallback

Use native FFmpeg only for unsupported transforms or when explicitly requested. Preserve the toolkit's design principles: argument arrays, explicit mapping, explicit overwrite behavior, and probe-driven decisions.

## Output expectations

A successful file-producing operation should have:

- a deterministic destination;
- explicit overwrite policy;
- a non-empty finalized file;
- FFprobe validation after transformation;
- structured warnings for copy-mode/keyframe limitations.

## Validation

Probe the result and verify the properties relevant to the request: duration, dimensions, FPS, codec, pixel format, and audio presence.

## Error recovery

- If copy trim is inaccurate, switch to accurate re-encode mode.
- If speed change causes audio issues, use the toolkit's audio tempo policy rather than changing video PTS alone.
- If upscale output is incompatible with the target workflow, normalize to explicit dimensions/FPS/pixel format/fit. `video restore` remains a compatibility alias.
- If decoding/timestamp errors appear, hand off to `ffmpeg-diagnostics`.

## Safety and determinism

Never silently overwrite an existing file. Never replace an input file in place. Prefer transactional output and explicit `--overwrite`.

## References

Read `references/video-editing-reference.md` for mode selection and validation guidance.

Referenced files: 2

View saved version →

---
name: ffmpeg-workflow
description: Translate natural-language media requests into validated FFmpeg Media Toolkit workflows, selecting domain Skills, preflighting inputs and outputs, and reporting only verified artifacts. Use for edit, convert, compose, stream, diagnose, or multi-step requests.
---

# FFmpeg Workflow

## Activation scope

Use this Skill when a user describes a media outcome in natural language and
the assistant must classify it, choose one or more domain Skills, order
preflight and execution, or report a resulting artifact.

Use ffmpeg-onboarding first when the execution context or required runtime
capability is unknown.

## Do not use

Do not use this Skill for pure environment installation or capability
discovery, which belongs to ffmpeg-onboarding. Do not use it to invent a
capability, hide a shell command inside a pipeline, or claim an artifact that
was not verified on the active host.

## Required inputs

Resolve or ask for:

- source media paths or an explicit capture source;
- the desired output and acceptable format/codec constraints;
- ordered operations and whether the request is a reusable pipeline;
- overwrite, dry-run, and temporary-artifact policy;
- execution context and authorization for writes or installation;
- hardware policy when acceleration is requested.

Make safe assumptions only when they do not change the media contract. State
the assumption before execution.

## Preflight

1. Classify the request with references/request-routing.md.
2. Select the smallest set of domain Skills needed.
3. Probe inputs when stream, timing, codec, dimensions, or audio layout matter.
4. Validate output paths, extension/codec compatibility, overwrite policy, and
   input/output collisions before expensive work.
5. Use dry-run for pipelines or whenever the user asks for a plan first.
6. Execute in declared order and preserve structured progress/errors.
7. Probe the final artifact and report it only after validation succeeds.

## Toolkit surface selection

Use the highest-level surface available:

1. use the associated Skill script when the requested workflow has one;
2. otherwise use the canonical cecilia-ffmpeg CLI and typed domain runtime;
3. use the explicit npm package-runner fallback below when the global CLI is
   unavailable;
4. use native FFmpeg only when the toolkit cannot represent the operation or
   the user explicitly requests native syntax.

The target architecture is script/Skill-first and does not require a network
service or an alternate agent protocol to make a workflow run.

## Associated scripts

This behavioral Skill delegates executable work to the selected domain Skill's
`scripts/run.mjs` entry point. Use `ffmpeg-onboarding/scripts/check.mjs` first
when the host or required capability is unknown; do not create a generic shell
runner in this routing layer.

## Request routing and associated scripts

Start from the user's desired outcome and route to the smallest domain Skill;
use this Skill to coordinate multiple domains, not to hide a generic shell
runner. The canonical request examples are in
[`../../docs/skill-request-examples.md`](../../docs/skill-request-examples.md).

When execution is available, invoke the selected domain's `scripts/run.mjs`
with one JSON request. Use `ffmpeg-onboarding/scripts/check.mjs` and
`ffmpeg-environment/scripts/inspect.mjs` before routing when the host or
required capability is unknown. Use `ffmpeg-pipelines/scripts/run.mjs` only
for ordered/reusable workflows or when the user explicitly asks for a
pipeline.

## Preferred toolkit commands

For a single operation, use the matching documented cecilia-ffmpeg command,
for example:

    cecilia-ffmpeg video trim INPUT --start 00:00:05 --end 00:00:20 --output OUTPUT

For pipelines, validate, inspect, and execute with:

    cecilia-ffmpeg pipeline pipeline.yaml validate
    cecilia-ffmpeg pipeline pipeline.yaml print
    cecilia-ffmpeg pipeline pipeline.yaml run --dry-run
    cecilia-ffmpeg pipeline pipeline.yaml run

If the global binary is unavailable:

    npm exec --yes --package=@cecilialabs/ffmpeg -- cecilia-ffmpeg pipeline pipeline.yaml run --dry-run

## Native FFmpeg fallback

Use native syntax only when a required operation is outside the typed toolkit
or the user explicitly asks for it. Explain the limitation, keep arguments
explicit, and preserve the same input/output and overwrite safety.

## Output expectations

Return:

- the selected domain Skill(s) and why they match;
- the exact command or associated script used, when execution is available;
- preflight facts and assumptions;
- structured execution status and warnings;
- the verified final path and relevant FFprobe properties;
- a clear distinction between a plan, a command supplied to the user, and a
  completed artifact.

## Validation

After authoring a workflow, parse and validate it. When practical, run a
dry-run before mutation. After execution, inspect the final artifact with
FFprobe and verify the requested codec, streams, timing, dimensions, and
container contract. For long jobs, report progress and preserve resumable
state when the associated script supports it.

## Error recovery

- For an ambiguous request, ask only for the missing media contract.
- For a missing capability, route to a supported domain or explain the
  limitation rather than substituting silently.
- For an output collision or overwrite rejection, ask for an explicit policy.
- For a failed step, report its structured details and retry only after the
  specific input, option, or capability is corrected.
- Preserve source media and temporary artifacts unless cleanup is safe and
  authorized.

## Safety and determinism

Never overwrite a source or final artifact without explicit policy. Never
embed arbitrary shell interpolation in declarative workflow files. Preserve
step order, resolve relative paths from the workflow file, use transactional
outputs, and do not report success from a dry-run.

## References

See references/request-routing.md for request classification and domain-Skill
selection examples.

Referenced files: 2