footage-gate

name: footage-gate description: Review source media, cut silence, auto color grade, and run cut-boundary QC through Footage Gate. risk_class: mutating_scoped

Skill — Footage Gate · 成片质量门

Operator manual for the footage-gate plugin (v1.0.0). Use this when you are running the plugin in production or coaching another agent through the workflow. For source-code architecture see README.md §2.

1. What it is

A four-mode local post-production quality gate. Each mode is a fully deterministic FFmpeg pipeline plus a thin Python wrapper that surfaces risks, fixes, or both. There is no LLM involvement in the default path — the only optional cloud call is a DashScope Paraformer transcription under source_review.

The plugin owns its own SQLite (tasks + config + assets_bus reserved for v2.0), its own FFmpeg installer panel (1:1 reused from seedance-video), and its own React UI (single-bundle, ≤2800 lines, 8 hard contracts aligned with tongyi-image).

2. When to use which mode

Combine them as the recommended workflow: source_review → silence_cut → auto_color → cut_qc. Each step is its own task and its output is the next step's input.

3. Inputs and outputs

EDL JSON canonical shape (cut_qc):

{
  "cuts": [
    {"source": "shot_a.mp4", "in_seconds": 0.0,   "out_seconds": 2.0},
    {"source": "shot_b.png", "in_seconds": 0.0,   "out_seconds": 1.5},
    {"source": "shot_c.mp4", "start_seconds": 5.0, "end_seconds": 7.5}
  ]
}

The start_seconds/end_seconds aliases are accepted to defend against OpenMontage issue #43.

4. Per-task params (UI ↔ API contract)

source_review:

• transcribe: bool (default false) — call Paraformer if API key set.

silence_cut:

• threshold_db: float (default -45) — silence threshold in dB.
• min_silence_len: float (s, default 0.15)
• min_sound_len: float (s, default 0.05)
• pad: float (s, default 0.05) — buffer kept around each non-silent run.

auto_color:

• preset: "auto" | "subtle" | "cinematic" (default auto; cinematic is reserved for v1.1).
• hdr_tonemap: bool (default true) — auto-prepend the TONEMAP_CHAIN filter.

cut_qc:

• edl: object — required. See §3 for shape.
• auto_remux: bool (default false, per the user's explicit requirement the UI exposes this toggle).
• max_attempts: int (default 3, range 1–3) — only honoured when auto_remux is true.

5. Status lifecycle

pending  →  running  →  done | failed | cancelled

A task in running can be cancelled from the Tasks tab; it transitions to cancelled and its work directory is left intact for inspection. A task in failed shows error_kind (one of dependency, config, input, runtime, cancelled, unknown) and error_hints (a list of zh strings — the UI also reads en if locale is en).

6. Errors you might see

7. Storage & cleanup

• data/footage_gate/uploads/{videos,audios,images,other}/ — raw uploads.
• data/footage_gate/tasks/<task_id>/ — per-task work + outputs.
• Settings → 存储 shows per-dir size + opens in OS file explorer.
• Settings → 默认参数 → 任务保留天数 controls the auto-cleanup cadence (defaults to 30 days).

8. Permissions

The plugin requests the standard Setup-Center permission set:

tools.register      # 5 AI tools
routes.register     # 16 REST routes
hooks.basic         # plugin lifecycle
config.read         # read host config
config.write        # write per-plugin settings
data.own            # exclusive access to data/footage_gate/

Plus UI permissions: upload, download, notifications, theme, clipboard. The Permissions panel in Settings highlights any missing ones with a one-click grant.

9. Known limitations (v1.0)

• cut_qc boundary frame check is histogram-diff-based. Hard-edged whip-pans may register as false positives — for now, lower the threshold via params or run with auto-remux OFF and accept the report.
• auto_color only emits a single global eq chain. Scene-aware grading is on the v1.1 roadmap.
• assets_bus table is created but not written. Cross-plugin handoff routes (/handoff/from/{plugin_id} etc.) land in v2.0 — see docs/post-production-plugins-roadmap.md.

10. Cheatsheet

# Probe a video locally
ffprobe -v error -show_entries stream=width,height,r_frame_rate -of json IN.mp4

# Reproduce silence_cut without the plugin
ffmpeg -i IN.mp4 -af silenceremove=stop_periods=-1:stop_threshold=-45dB OUT.mp4

# Reproduce auto_color (subtle preset)
ffmpeg -i IN.mp4 -vf "eq=contrast=1.05:gamma=1.02:saturation=1.04" OUT.mp4

# HDR → SDR tone-map (prepended automatically when source is HLG / PQ)
ffmpeg -i IN_HDR.mp4 -vf "zscale=t=linear:npl=100,format=gbrpf32le,zscale=p=bt709,tonemap=tonemap=hable:desat=0,zscale=t=bt709:m=bt709:r=tv,format=yuv420p" OUT_SDR.mp4

When in doubt, mirror the params in the Tasks → details JSON and pipe them through these CLI commands to verify behaviour outside the plugin.