zcbacxc/movie-narrator/skill

movie-narrator CLI Skill

mn is a Python CLI that generates narrated movie-recap videos from a single prompt. This document is the machine-readable capability map for AI agents — read it before issuing mn commands so you use the right command, flags, and conventions.

Install & Verify

pip install -e ".[dev]"        # dev mode with test deps
mn version                     # print version + CONTRACT_VERSION
mn --help                      # full command list

External prerequisites: FFmpeg on PATH (the renderer resolves it via utils/ffmpeg_bin.ffmpeg_bin(), preferring the bundled imageio-ffmpeg build, then the system binary). Optional extras: [media] (scene detection), [ml] (WhisperX alignment, embedding matching), [full] (all extras).

Command Reference

Core generation

Pipeline sub-steps

Task queue / async (v0.6+)

Plugins, presets, registry, artifacts

mn presets install <url-or-path> # data-only YAML, whitelist-validated mn presets show <name> / remove <name> mn plugin version` | Show CONTRACT_VERSION |

Environment & diagnostics

Common Workflows

Generate a video (basic)

mn create --movie "飞驰人生" --style "热血搞笑" --duration 60

Generate from a job YAML config

mn create --config examples/job.example.yaml

Offline / CI smoke run (no network TTS)

CI=1 mn create --movie "CI-Test" --style "热血搞笑" --duration 10 --keep-cache

Async task queue

mn submit -m "飞驰人生" -p douyin-fast    # submit async task
mn status <task_id>                       # show task status
mn serve --port 8765 --max-workers 2      # start daemon + REST API server

Pause & resume (human-in-the-loop)

mn create --movie "飞驰人生" --pause-at script                  # pause after script
mn resume --state output/<movie>/pipeline_state.json           # resume from checkpoint

Rerun from a step (deliberate re-execution)

mn rerun --list-steps                                          # ordered step names (soft steps marked)
mn rerun output/<movie>/pipeline_state.json --from render_video  # re-run render_video onward
mn rerun output/<movie>/pipeline_state.json --from render_video --dry-run  # print the plan only, no execution

Key mn create Flags

Pipeline & Soft Steps

The pipeline is a flat sequence of steps over a shared Context. Eight steps are soft (optional): research_plot, align_audio, detect_scenes, match_clips, mix_bgm, translate_subtitles, run_qa_gate, export_clips. Each writes a 5-state outcome (disabled/skipped/success/failed/partial). Use --strict to make soft failures fatal.

Conventions an Agent Must Follow

• Config priority: CLI flags > YAML config > Settings defaults.
• Settings boundary: .env (Settings) holds LLM + TTS credentials,

endpoints, models, and call params only. All pipeline behavior is configured via job.yaml params.

• Output layout: output/<sanitized_movie>/ with a cache/ dir (deleted

unless --keep-cache). Generated artifacts are gitignored.

• CI/offline: use CI=1 to force silent-audio fallback (no Edge-TTS

network calls) so the pipeline runs end-to-end without network.

• When a task has no `--movie`, the CLI may prompt interactively. Prefer

passing --movie explicitly in non-interactive/agent use.

• Generated artifacts (*.mp4, *.mp3, *.srt, *.json, output/) are

gitignored — do not commit them.

Troubleshooting Agent Interactions

• "No plugins found via entry_points" — expected if no out-of-tree plugin

packages are installed; not an error.

• Optional extras missing / pipeline soft-degrades — run mn doctor for a

per-dependency status report. Each row is one of three states:

• installed — usable, no action needed.
• not installed — the module is absent; the hint shows the pip install

command for the corresponding extra ([media] / [ml]).

• missing deps — the package is installed but a transitive dependency

failed to import; the hint names the exact missing module (e.g. torchaudio for whisperx). Install that module rather than reinstalling the whole extra.

• FFmpeg not found — ensure FFmpeg is on PATH; the renderer resolves it

via utils/ffmpeg_bin.ffmpeg_bin() (bundled imageio-ffmpeg first, then system).

• CJK font fallback — assets/fonts/NotoSansSC-Regular.otf → system

paths → install hint if missing.

• `mn` command missing — run pip install -e ".[dev]" first.