English 简体中文

🎬 Movie Narrator

Python License CI PyPI Downloads

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

  • 🎬 LLM-powered movie recap script generation
  • 🔊 Text-to-Speech narration (Edge-TTS by default)
  • 💬 Automatic SRT subtitle generation
  • 🌐 Multi-language subtitles with LLM translation
  • 🏁 Multi-candidate horse race — run N variations, score and auto-pick the best
  • 🎯 Reference video imitation — extract style from viral narration
  • 👁️ VLM scene captioning via cloud VLM API
  • 🎭 Narrator perspective (omniscient / character / detective)
  • 🎨 Render template system (title cards, watermarks, slogans)
  • 🔍 TMDB fact verification for movie cards
  • 🖥️ Web UI (separate movie-narrator-web package — FastAPI + React)
  • 🎞️ Video rendering with MoviePy and FFmpeg
  • 📝 Script markdown export
  • 🎵 Background music integration
  • 📦 Metadata export
  • 🔌 Extensible plugin architecture
  • ☁️ Async task queue (local + remote job submission, progress polling, retry)
  • 🌐 Remote inference via REST API
  • 🛡️ Circuit breaker + retry policy for external APIs (v0.9.1)
  • 💾 Task checkpointing with resume (v0.9.2)
  • 📦 Batch job submission + cron scheduling (v0.9.3)
  • 💀 Dead-letter queue for failed task inspection and replay (v0.9.4)
  • 🌍 Conditional distributed rendering across nodes (v0.9.4)

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; Python < 3.14)
pip install "movie-narrator[ml]"

# Web UI (FastAPI + React) — separate package
pip install movie-narrator-web

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

Note on Python 3.14+: The [ml] extra (WhisperX + sentence-transformers) is currently gated to Python < 3.14 due to upstream dependency wheel availability. On Python 3.14+, pip install "movie-narrator[full]" will install all other extras and silently skip the ML components. The align and match pipeline steps will soft-degrade (see Soft steps) instead of failing.

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"

More Commands

mn create --config examples/job.example.yaml     # Drive from YAML config
mn create --subtitle-lang en --subtitle-mode bilingual  # Multi-language subtitles
mn race --movie "飞驰人生" --video movie.mp4 --candidates 3  # Multi-candidate horse race
mn imitate --reference viral_ref.mp4 --movie "飞驰人生"  # Reference video imitation
mn serve               # Start remote inference API server (v0.6.1+)
mn submit -m <movie>   # Submit async task
mn tasks               # List recent tasks
mn version             # Show version
mn --help              # Full help with all 24 CLI flags

All 24 CLI flags are documented in examples/cli-usage.sh.

Configuration

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

Via .env file (recommended)

~/.movie-narrator/.env is auto-created with default values on first run — edit it to configure LLM, TTS, and other settings. This file lives outside the package, so pip install/upgrade/uninstall never touches it. You can also create a project-level .env in your working directory for per-project overrides.

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

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 cwd/.env Project-level
3 ~/.movie-narrator/.env User-level, never lost on pip install/upgrade/uninstall
4 Built-in defaults Local Ollama

Full reference

See .env.example for the complete list of all environment variables (LLM + TTS infrastructure only). All pipeline behavior is configured via examples/job.example.yaml — params keys covering scene detection, match, render, translate, BGM, WhisperX, async, and video sizes.

LLM Provider Guides

Movie Narrator works with any OpenAI-compatible LLM. New user? Check out the LLM Provider Guides for step-by-step registration and free-tier setup:

Provider Free Tier Best For
Ollama Completely free (local) Privacy, offline use
Zhipu (GLM) glm-4-flash unlimited free Zero-cost, no GPU
Alibaba Bailian 1M tokens per model Qwen flagship models
Xiaomi MiMo Limited-time free + ¥10 invite bonus LLM + TTS in one platform
SiliconFlow Free models + voucher credits Multi-model switching

Output

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 (original narration)
subtitle.<lang>.srt Translated subtitle (when --subtitle-lang set)
subtitle.bilingual.srt Bilingual subtitle (when --subtitle-lang set)
script.md Human-readable script
research.json Movie research data (when --research)
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

16-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 → translate_subtitles → generate_subtitle →
run_qa_gate → render_video → validate_deliverable → export_clips

Soft steps (research, align, scene detect, scene match, BGM, translate, QA gate, clip export) gracefully skip or soft-degrade when optional dependencies are missing or upstream data is unavailable. Use --strict to abort instead.

Project Structure

movie-narrator/
├── src/movie_narrator/
│   ├── cli.py               # Typer CLI entry point
│   ├── config.py            # Pydantic settings
│   ├── models.py            # Data models (Context, Status, etc.)
│   ├── contract.py          # Stable API contract surface
│   ├── pipeline/            # 16-step pipeline (runner, steps, errors)
│   ├── cloud/               # Task queue, remote inference, batch, scheduling, DLQ, distributed (v0.9.x)
│   ├── reliability/         # Circuit breaker + retry policy (v0.9.1)
│   ├── workflow/            # YAML job config (schema, loader, merge)
│   ├── tts/                 # TTS provider abstraction layer
│   └── utils/               # Shared utilities (console, log, font, etc.)
├── tests/                   # Unit + integration tests
├── docs/                    # Architecture, guides, roadmap
├── examples/                # Job YAML, CLI usage, plugins
└── .github/workflows/       # CI/CD

Documentation

License

Licensed under the AGPL-3.0-or-later License.

Project links

Data verified by PyPI on Aug 4, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (1.5.2)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for zcbacxc from gravatar.com zcbacxc

Credits

Author: zcbacxc

GitHub Statistics

Data verified by PyPI on Aug 4, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

AGPL-3.0-or-later
View SPDX License List

Requires

Python >=3.10

Provides Extra

media ml full s3 dev docs

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

movie_narrator-0.9.7.tar.gz (551.5 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

movie_narrator-0.9.7-py3-none-any.whl (392.1 kB view details)

Uploaded Python 3

File details

Details for the file movie_narrator-0.9.7.tar.gz.

File metadata

  • Download URL: movie_narrator-0.9.7.tar.gz
  • Upload date:
  • Size: 551.5 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for movie_narrator-0.9.7.tar.gz
Algorithm Hash digest
SHA256 c71e91081cb96f5b882c16e8280c047eba2a3b54ba8f59d467b6f497b1826dc0
MD5 27702507f05a16e28493c06c8edf7744
BLAKE2b-256 30c2a0a6cac6985ff2e3ca77b0f89b84133ddf4dd85f9c4fc616776da632b1b5

See more details on using hashes here.

Provenance

The following attestation bundles were made for movie_narrator-0.9.7.tar.gz:

Publisher: publish.yml on zcbacxc/movie-narrator

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file movie_narrator-0.9.7-py3-none-any.whl.

File metadata

  • Download URL: movie_narrator-0.9.7-py3-none-any.whl
  • Upload date:
  • Size: 392.1 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for movie_narrator-0.9.7-py3-none-any.whl
Algorithm Hash digest
SHA256 963ec4b121f525911540891d88a6c8e13dadd19697117fe45effc97dbac1c3b0
MD5 c69e62e1cf3bd62a46bacab280a24bd9
BLAKE2b-256 ecccac23cd387bf2370575c1a4a241cee80c9c67c6db4808e0d3ddc4e3a69b08

See more details on using hashes here.

Provenance

The following attestation bundles were made for movie_narrator-0.9.7-py3-none-any.whl:

Publisher: publish.yml on zcbacxc/movie-narrator

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

1.5.2

2 files

1.5.1

2 files

1.5.0

2 files

1.4.2

2 files

1.4.1

2 files

1.4.0

2 files

1.3.2

2 files

1.3.1

2 files

1.3.0

2 files

1.2.1

2 files

1.2.0

2 files

1.1.0

2 files

1.0.0

2 files

This release

0.9.7 This release

2 files

0.9.6

2 files

0.9.5

2 files

0.9.4

2 files

0.9.3

2 files

0.9.2

2 files

0.9.1

2 files

0.8.4

2 files

0.8.3

2 files

0.8.2

2 files

0.8.1

2 files

0.8.0

2 files

0.7.5

2 files

0.7.4

2 files

0.7.3

2 files

0.7.2

2 files

0.7.1

2 files

0.7.0

2 files

0.6.1

2 files

0.6.0

2 files

0.5.12

2 files

0.5.11

2 files

0.5.10

2 files

0.5.9

2 files

0.5.8

2 files

0.5.7

2 files

0.5.6

2 files

0.5.5

2 files

0.5.4

2 files

0.5.3

2 files

0.5.2

2 files

0.5.1

2 files

0.5.0

2 files

0.4.27

2 files

0.4.26

2 files

0.4.25

2 files

0.4.24

2 files

0.4.23

2 files

0.4.22

2 files

0.4.21

2 files

0.4.20

2 files

0.4.19

2 files

0.4.18

2 files

0.4.17

2 files

0.4.16

2 files

0.4.15

2 files

0.4.14

2 files

0.4.12

2 files

0.4.11

2 files

0.4.10

2 files

0.4.9

2 files

0.4.8

2 files

0.4.7

2 files

0.4.6

2 files

0.4.5

2 files

0.4.4

2 files

0.4.3

2 files

0.4.2

2 files

0.4.1

2 files

0.3.5

2 files

0.3.4

2 files

0.3.3

2 files

0.3.2

2 files

0.2.7

2 files

0.2.6

2 files

0.2.5

2 files

0.2.4

2 files

0.2.3

2 files

0.1.1

2 files

0.1.0

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page