movie-narrator 0.3.3

Generate narrated movie recap videos from a single prompt.

🎬 Movie Narrator

One Prompt → One Narrated Movie Video

Movie Narrator is an open-source toolkit that automatically generates movie recap videos with narration, subtitles, and rendered output from a simple command.

---

Features

• 🎬 Generate movie recap scripts with LLMs
• 🔊 Text-to-Speech narration (Edge-TTS by default)
• 💬 Automatic SRT subtitle generation
• 🎞️ Video rendering with MoviePy and FFmpeg
• 📝 Script markdown export (script.md)
• 🎵 Background music integration (BGM)
• 🎬 Scene-level clip export
• 📦 Metadata export
• 🔌 Extensible pipeline architecture
• 🐍 Pure Python implementation

---

Installation

Requirements

• Python 3.10+
• FFmpeg

Install FFmpeg

macOS

brew install ffmpeg

Ubuntu / Debian

sudo apt install ffmpeg

Windows

# Option 1: winget
winget install Gyan.FFmpeg

# Option 2: chocolatey
choco install ffmpeg

# Option 3: Manual download from https://ffmpeg.org/

Verify installation:

ffmpeg -version

---

Install Movie Narrator

From PyPI

pip install movie-narrator

From Source

git clone https://github.com/zcbacxc/movie-narrator.git
cd movie-narrator
pip install -e .

Optional extras

# Scene detection (PySceneDetect)
pip install "movie-narrator[media]"

# WhisperX + semantic search (requires PyTorch)
pip install "movie-narrator[ml]"

# Everything
pip install "movie-narrator[full]"

For development:

pip install -e ".[dev]"

---

Quick Start

Prerequisites

• LLM: Default uses local Ollama (ollama serve to start). Or configure remote LLM via .env file.
• FFmpeg: Required for video rendering.

Basic Usage

# Generate a narrated movie video
mn create --movie "飞驰人生" --style "热血搞笑" --duration 60

# With custom voice and format
mn create --movie "飞驰人生" --voice "zh-CN-XiaoxiaoNeural" --format "9:16"

# Keep TTS cache for debugging
mn create --movie "飞驰人生" --keep-cache

CLI Options

Option	Description	Default
--movie, -m	Movie name (required)	-
--style, -s	Narration style	热血搞笑
--duration, -d	Target duration (seconds)	60
--voice, -v	Edge-TTS voice	zh-CN-YunxiNeural
--format, -f	Video format (16:9 or 9:16)	16:9
--video, -V	Source movie file path	-
--library-dir	Movie library directory	-
--research	Enable plot research via LLM	false
--no-research	Disable plot research	-
--bgm	Background music file path	-
--no-bgm	Disable BGM even if default is set	false
--no-clips	Skip scene-level clip export	false
--strict	Abort pipeline on soft step failure	false
--config	Path to job YAML (movie/steps/params); CLI flags override YAML	-

Job YAML config (v0.3)

# Drive a job from YAML (movie may live only in the file)
mn create --config examples/job.example.yaml

# CLI flags still win over YAML
mn create --config examples/job.example.yaml --movie "OtherTitle" --no-clips

See examples/job.example.yaml for the full whitelist: soft-step toggles under steps: (research, align, scene, match, bgm, export) and params (scene_threshold, match_min_score, research_provider). Relative video / bgm / library_dir paths resolve against the YAML file's directory. LLM credentials stay in .env / MN_* only.

Offline Demo (No LLM Required)

# CI=1 uses silent audio fallback, bypasses LLM and Edge-TTS
CI=1 mn create --movie "Demo" --duration 10

Other Commands

mn version   # Show version
mn --help    # Show help

---

Configuration

All settings use the MN_ prefix to avoid conflicts with other tools.

Via .env file (recommended)

Create .env in your project directory (or ~/.movie-narrator/.env for global config — this file lives outside the package, so pip install/upgrade/uninstall never touches it):

MN_LLM_BASE_URL=http://localhost:11434/v1
MN_LLM_API_KEY=ollama
MN_LLM_MODEL=qwen2.5:7b
MN_DEFAULT_VOICE=zh-CN-YunxiNeural
MN_DEFAULT_FORMAT=16:9

Via environment variables

# PowerShell
$env:MN_LLM_BASE_URL="http://localhost:11434/v1"
$env:MN_LLM_MODEL="qwen2.5:7b"
mn create --movie "飞驰人生" --duration 60

# Linux / macOS
export MN_LLM_BASE_URL=http://localhost:11434/v1
export MN_LLM_MODEL=qwen2.5:7b
mn create --movie "飞驰人生" --duration 60

Config lookup order

Priority	Location	Notes
1	Environment variables (MN_*)	Highest
2	当前目录/.env	Project-level
3	~/.movie-narrator/.env	User-level, never lost on pip install/upgrade/uninstall
4	Built-in defaults	Local Ollama

Full reference

Variable	Description	Default
MN_LLM_BASE_URL	LLM API endpoint	http://localhost:11434/v1
MN_LLM_API_KEY	LLM API key	ollama
MN_LLM_MODEL	LLM model name	qwen2.5:7b
MN_DEFAULT_VOICE	Edge-TTS voice	zh-CN-YunxiNeural
MN_DEFAULT_FORMAT	Video aspect ratio	16:9
MN_LIBRARY_DIR	Movie library path	-
MN_DEFAULT_BGM	Default BGM file	-
MN_RESEARCH_ENABLED	Auto-enable research	false
MN_RESEARCH_PROVIDER	Research backend	llm
MN_SCENE_THRESHOLD	PySceneDetect threshold	27.0
MN_SCENE_FRAME_SKIP	Frames to skip in scene detection	10
MN_MATCH_MIN_SCORE	Minimum match score	0.25
MN_EXPORT_CLIPS_DEFAULT	Auto-export clips	true

---

Output

output/
└── 飞驰人生/
    ├── narration.mp3       # TTS narration audio
    ├── mixed.mp3            # Narration + BGM mix (when BGM enabled)
    ├── subtitle.srt
    ├── script.md
    ├── script.json
    ├── research.json        # (when --research)
    ├── scenes.json          # (when video provided)
    ├── matches.json         # (when video provided)
    ├── metadata.json
    ├── final.mp4
    └── clips/               # (when --no-clips not set)

File	Description
narration.mp3	AI-generated narration audio
mixed.mp3	Narration + BGM overlay (when BGM enabled; otherwise narration.mp3 used directly)
subtitle.srt	Synchronized subtitle file
script.md	Human-readable script
script.json	Machine-readable script segments
research.json	Movie research data (when --research)
scenes.json	Detected scene boundaries (when video provided)
metadata.json	Segment timings, pipeline status, config
final.mp4	Rendered video (16:9 or 9:16)
matches.json	Scene-to-segment clip matching (when video provided)
clips/	Per-segment clip .mp4 files (when --no-clips not set)

---

Pipeline

14-step sequential pipeline (see Architecture):

resolve_video → prepare_assets → research_plot → generate_script →
export_script_md → generate_voice → align_audio → detect_scenes →
match_clips → mix_bgm → generate_subtitle → render_video →
export_clips

Soft steps (research, align, scene detect, scene match, BGM, clip export) gracefully skip when optional dependencies are missing. Use --strict to abort instead.

---

Project Structure

movie-narrator/
├── src/movie_narrator/
│   ├── __init__.py          # Package metadata (__version__)
│   ├── cli.py               # Typer CLI entry point
│   ├── config.py            # Pydantic settings
│   ├── models.py            # Data models (Context, Status, etc.)
│   ├── pipeline/
│   │   ├── runner.py        # 14-step pipeline orchestrator
│   │   ├── resolve.py       # Source video resolution
│   │   ├── assets.py        # Asset validation
│   │   ├── research.py      # LLM movie research
│   │   ├── script.py        # LLM script generation
│   │   ├── script_export.py # Script markdown export
│   │   ├── tts.py           # Edge-TTS with caching
│   │   ├── align.py         # WhisperX audio alignment
│   │   ├── scenes.py        # PySceneDetect scene detection
│   │   ├── match.py         # Heuristic clip matching
│   │   ├── bgm.py           # Background music mixing
│   │   ├── subtitle.py      # SRT generation
│   │   ├── render.py        # MoviePy video rendering
│   │   ├── export_clips.py  # Per-segment clip export
│   │   └── errors.py        # PipelineStrictError
│   ├── workflow/
│   │   ├── schema.py        # JobConfig / JobSteps / JobParams
│   │   ├── load.py          # YAML loader + validation
│   │   ├── merge.py         # CLI > YAML > Settings merge
│   │   └── errors.py        # JobConfigError
│   └── utils/
│       ├── async_utils.py   # Sync/async bridge
│       ├── environment.py   # Environment collection
│       ├── font.py          # CJK font fallback
│       ├── json_parser.py   # LLM JSON extraction
│       ├── llm.py           # OpenAI client wrapper
│       ├── optional_deps.py # Optional dependency probing
│       └── prompts.py       # Prompt templates
├── tests/
│   ├── test_context.py
│   ├── test_settings.py
│   ├── test_errors.py
│   ├── test_align.py
│   ├── test_assets.py
│   ├── test_bgm.py
│   ├── test_cli_config.py
│   ├── test_cli_resolve.py
│   ├── test_match.py
│   ├── test_optional_deps.py
│   ├── test_render_real.py
│   ├── test_research.py
│   ├── test_resolve.py
│   ├── test_runner_strict.py
│   ├── test_runner_workflow_metadata.py
│   ├── test_scenes.py
│   ├── test_script_export.py
│   └── test_workflow_steps.py
├── docs/
├── assets/
└── .github/workflows/

---

Roadmap

v0.1.x — Core Pipeline ✅

• CLI interface (mn create, mn version)
• LLM script generation with JSON output
• Edge-TTS narration with concurrent generation
• SRT subtitle generation with millisecond precision
• MoviePy video rendering (16:9 / 9:16)
• TTS result caching with content-addressable keys
• Metadata export (JSON)
• CI pipeline (unit tests + smoke test)

v0.2.x — Scene & Media ✅

• Research agent for movie plot research (--research)
• WhisperX audio-text alignment
• Scene detection from movie videos
• Automatic clip matching based on script
• Semantic scene search (embedding-based, requires [ml])
• Background music integration (BGM mixing)
• Script markdown export (script.md)
• Scene-level clip output (clips/)

v0.3.x — Platform & Workflow ✅

• Declarative workflow config for soft-step toggles + params
• YAML-based job configuration (mn create --config)
• Web UI (Gradio / FastAPI)
• Multi-language subtitle support

v0.4.x — Extensibility

• Plugin system for custom pipeline steps
• Python SDK for programmatic usage
• Third-party extension support

---

Documentation

• Roadmap
• Architecture
• Contributing

---

License

Licensed under the AGPL-3.0 License.