git:20261021.09ec491 to git:20261021.03f5455

- frame extraction, and image-sequence-to-MP4 conversion through installed

- FFmpeg. Use when agents need to preflight, inspect, or share media outputs.

- compatibility: Python 3.7+. Requires external FFmpeg and matching FFprobe; explicit executable overrides, then installed vx runtime, then system PATH. Never installs or downloads dependencies.

- search-hint: "media, ffmpeg, ffprobe, vx ffmpeg, check runtime, preflight, encoder, image sequence, render output, playblast, mp4, transcode, extract frames, thumbnail, probe video, audio-only, wav, ogg, vorbis"

- artifacts. FFmpeg and matching FFprobe are external, operator-approved

- prerequisites, not bundled with Core. Every media tool uses only installed

- binaries; none installs vx, downloads FFmpeg, or invokes a launcher that might

- bootstrap dependencies. A missing runtime is an actionable preflight failure.

- Use `media__check_runtime` before expensive render/export work. Prefer native

- DCC skills for creating the render output, then use `media__probe`,

- `media__sequence_to_mp4`, `media__thumbnail`, `media__transcode`,

- `media__transcode_audio`, or `media__extract_frames` to inspect or repackage

- files already on disk. Discover the capability, follow the returned load or

- describe step, and call the returned tool slug with typed arguments. Do not

- guess gateway slugs or replace the tool with arbitrary shell commands.

- `vx <command>` runner. Every tool builds a fixed argument vector for the

- resolved FFmpeg or FFprobe executable without `shell=True`, validates paths

- and enum fields, rejects option-like paths, and requires explicit overwrite

- intent before replacing outputs. Verified audio-only output is stricter: its

- destination must be fresh and cannot be overwritten.

-

- ## Runtime selection and preparation

-

- FFmpeg selection follows this priority:

-

- 1. `DCC_MCP_MEDIA_FFMPEG_BIN`, if set to an absolute executable path.

- 2. An already-installed FFmpeg in the local vx store (`VX_HOME`, or `~/.vx`

- by default), discovered from local files without executing vx.

- 3. `ffmpeg` on the server process's system `PATH` if there is no installed vx

- runtime.

- The vx lookup checks the vx 0.9.37 provider layouts under

- `<vx-root>/store/ffmpeg/<version>`, with at most 128 entries and the highest

- numeric stable version first. It does not require a vx launcher, consult

- `vx.toml` or `vx.lock`, or select preview/custom version names. Pin a version

- or use an unsupported layout through explicit executable overrides instead.

- `DCC_MCP_MEDIA_FFPROBE_BIN` may specify the matching probe's absolute

- executable path. Otherwise, resolve FFprobe only as a sibling of the resolved

- FFmpeg binary, never from an unrelated `PATH` entry. FFmpeg and FFprobe must

- have matching release/build identities. An invalid explicit override fails;

- it is not permission to switch installations or silently choose another codec.

- Override values are executable paths, not command names, shell fragments, or

- arguments. Only native ELF, PE, or Mach-O executables are accepted; scripts and

- known vx shim directories are rejected. Native wrappers cannot be identified

- reliably from file headers. Spaces in paths are supported. Configure

- these variables in the media server's environment, not only the agent's shell.

- `DCC_MCP_MEDIA_VX_BIN` and `DCC_MCP_MEDIA_AUTO_INSTALL_VX` no longer control

- media execution. Migrate an old pinned vx launcher to the FFmpeg/FFprobe

- executable overrides. `VX_INSTALL_DIR` is not a media runtime selector, and no

- installer configuration enables media-tool downloads.

- Before an approved online setup, ask the user for permission to install or

- download dependencies. Use an existing vx installation with

- `vx install ffmpeg@8.1`, or the operating system's package manager, to obtain

- FFmpeg and FFprobe together. If vx needs installation, download its official

- installer to a local file, inspect it, and execute it only after approval;

- never pipe an installer directly into a shell. Prepare approved binaries and

- required shared libraries before an offline workload. Core's MIT license does

- not replace FFmpeg's build-dependent LGPL/GPL license; review the selected

- distribution's terms before redistribution.

- agent. Runtime overrides always require absolute paths.

-

- ## Read-only runtime preflight

-

- Discover and call `media__check_runtime` before scheduling media work. Its

- optional `required_encoders` array defaults to `pcm_s16le`, `libvorbis`, and

- `pcm_f32le`; request the encoders needed for the intended workflow.

- `timeout_secs` is bounded to 60 seconds. This check creates no media output

- and performs no installation. The resolver itself starts no package manager

- or network request; preflight executes the selected local binaries for

- version and capability checks, so they remain operator-trusted code rather

- than a sandboxed guarantee against arbitrary binary behavior.

-

- Review the selected source, resolved absolute executable paths, versions,

- SHA-256 hashes, and required encoder availability. Keep this evidence with the

- job, and stop on missing binaries, build mismatches, or missing capabilities.

- Selection priority is not a trust attestation: a local vx installation or

- system path is an operator-trusted prerequisite, and a hash only identifies

- the executable bytes. Preflight does not replace native codec, output, or

- playback qualification. A later operation resolves and validates its own

- runtime; an earlier successful check is not a guarantee that files or the

- environment have remained unchanged.

- video, subtitle, data and inherited metadata are excluded. Source sample rate

- and channel count are preserved, and a known source channel layout must match.

-

- OGG output uses fixed `-page_duration 1` muxer pagination to keep the priming

- packet off the final EOS page. This avoids the documented FFmpeg single-page

- Vorbis duration-accounting issue without padding, trimming, resampling, or

- changing compressed audio packets. See the

- [upstream diagnosis](https://ffmpeg.org/pipermail/ffmpeg-devel/2022-May/295939.html).

- More pages add container overhead; the full-decode sample-count gate is still

- mandatory, including for very short clips. This is not a codec fallback.

-

-

- This operation uses the same **already installed** FFmpeg/FFprobe selection

- policy as preflight; it does not install anything. The selected executables

- are **operator-trusted prerequisites**, not a supply-chain attestation. The

- tool pins their resolved absolute paths and records each executable's version,

- SHA-256 and resolution basis. Hashes identify the bytes used; neither a hash

- nor the discovery source independently authenticates those bytes. Requested

- encoder and `pcm_f32le` verification-encoder capabilities are checked before

- encoding; a missing encoder fails without silently choosing another build.

-

- Input is limited to 128 MiB, 8–192 kHz and 1–8 channels. Full f32le PCM decode

- is streamed, never saved, with a 256 MiB cap for each source/output decode.

- Text stdout has a 1 MiB cap; stderr has a 4 MiB total cap and retains only a

- 4 KiB diagnostic tail. Crossing a stream cap stops the owned process. Output

- uses FFmpeg's `-fs` limit, owner-thread size monitoring, and a strict 64 MiB

- pre-publication acceptance gate. FFmpeg can slightly overshoot `-fs`; this is

- **not an OS disk quota**. Limits and the shared operation timeout appear in

- receipts. Hashing also checks cancellation, time and byte budgets.

- Encoding writes only to a private staging directory beside the destination.

- The final pathname is published through an atomic no-replace hard link only

- after complete validation. Filesystems without that operation fail closed;

- there is no copy/replace fallback. Failed operations retain diagnostic staging

- artifacts, never publish them or retry automatically. Successful publication

- is the commit point; a late cancellation does not retract a published file.

- Receipts bind source/output hashes, actual codec/container/rate/channels,

- full-decode sample-frame counts and PCM hashes, resolved executable evidence,

- exact argv, Core-owned job identity when present, and cleanup state. Counts

- come from decoder PCM (including its codec-delay/skip handling), not container

- duration or packet count. A count change is a failure, never repaired. Lossy

- waveform quality, independent decoder/loop-boundary checks and browser playback

- remain separate qualification; matching counts alone do not prove quality. Lossy

- Vorbis can change very short signals substantially: preserving one sample is

- not a promise to reproduce that sample's amplitude. Do not waive fidelity

- requirements, pad/trim samples, or treat count acceptance as a quality score.

- The existing Core async job lifecycle supplies job identity and cancellation.

- The owner thread checks `check_dcc_cancelled()` at most 50 ms between process

- polls, and during hashing and before publication. Cancellation and timeout stop

- the owned group and retain the original reason/receipt. Poll the Core job to

- terminal state; admission is not artifact acceptance. POSIX processes run in

- owned groups. Windows uses `taskkill /T /F` and launcher reaping; failure or an

- already-exited launcher leaves cleanup `unknown`. Windows live cancellation,

- real Core transport cancellation and native codec qualification remain separate

- from host-free/POSIX subprocess tests. Cleanup has a separate bounded grace

- period; an uncertain cleanup never grants permission to retry.