footage-gate

by openakita

Install this Skill

curl -fsSL -o footage-gate.zip https://skill.seembox.com/api/v1/skills/footage-gate/download && unzip footage-gate.zip

Download footage-gate.zip

SKILL.md About

# 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

| Situation | Mode | Why |
|-----------|------|-----|
| You just imported the day's raw footage and want a triage report. | `source_review` | Catches resolution / mono-audio / too-short clips before you start editing. |
| A long take has obvious dead air you want trimmed. | `silence_cut` | Pure-NumPy RMS detection, no `aubio` install pain. |
| A finished cut feels flat / too dim. | `auto_color` | Sub-second sampling → ±8 % clamped grade. HDR sources auto tone-mapped. |
| You exported the master and want to verify QC before delivery. | `cut_qc` | 4 checks vs your EDL, with optional auto-remux loop (≤3). |

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

| Mode | Accepted inputs | Output artifacts |
|------|-----------------|------------------|
| `source_review` | mp4 / mov / wav / mp3 / jpg / png | `report.json` (risks, ffprobe metadata, optional transcript), 4 representative frames |
| `silence_cut`   | mp4 / mov / wav / mp3            | `output.mp4` (or `.wav`), `report.json` (intervals removed) |
| `auto_color`    | mp4 / mov                        | `graded.mp4`, `report.json` (chosen eq values, HDR flag) |
| `cut_qc`        | mp4 / mov + EDL JSON             | `report.json` (issue list per check), optional `remux_N.mp4` for each attempt |

EDL JSON canonical shape (cut_qc):

```json
{
  "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

| `error_kind` | Typical cause | Fix |
|--------------|---------------|-----|
| `dependency` | FFmpeg / FFprobe missing or too old | Settings → 系统依赖 → 一键安装 |
| `config`     | Paraformer asked but no API key      | Settings → 转写 API → 保存 |
| `input`      | Unsupported codec / corrupt file     | Re-export the source via Premiere / DaVinci to standard h264 / aac |
| `runtime`    | FFmpeg returned non-zero mid-pipeline | Open the report; the stderr tail is included |
| `cancelled`  | User cancelled the task              | Re-run via the Retry button |
| `unknown`    | Anything else                        | File an issue with the task ID — we attach the full traceback |

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

```bash
# 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.