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

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 (v0.6.x)
│   ├── 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

Roadmap

Current focus: cloud infrastructure (distributed rendering, API gateway, cloud storage). See the full Roadmap for version-by-version details from v0.6.2 to v1.0.

Documentation

License

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

Project links

Data verified by PyPI on Jul 30, 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 Jul 30, 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 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.7.1.tar.gz (388.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.7.1-py3-none-any.whl (288.5 kB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: movie_narrator-0.7.1.tar.gz
  • Upload date:
  • Size: 388.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.7.1.tar.gz
Algorithm Hash digest
SHA256 25bfd4d4b0acff1539cc91a0d434e05c04e4dc6bc32b9e726d58fba60579d6d7
MD5 e02bd408a55481181ea3bcd4c23fb425
BLAKE2b-256 8bba060bb01cbe51302ccebdac22f27e355ce877741b0079322342c0392d1afa

See more details on using hashes here.

Provenance

The following attestation bundles were made for movie_narrator-0.7.1.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.7.1-py3-none-any.whl.

File metadata

  • Download URL: movie_narrator-0.7.1-py3-none-any.whl
  • Upload date:
  • Size: 288.5 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.7.1-py3-none-any.whl
Algorithm Hash digest
SHA256 05788dfdacc48d024ec4416a158bf7e725cc41f6ada10afc88149458bceaab8f
MD5 4ad3d274ee21a8a8a3f06e0054a4a6de
BLAKE2b-256 b8af39ae0e9b18c3420c960be2948f09aeaffd9f249801642df34ec3a8b38292

See more details on using hashes here.

Provenance

The following attestation bundles were made for movie_narrator-0.7.1-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

0.9.7

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

This release

0.7.1 This release

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