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

Documentation

License

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

Project links

Data verified by PyPI on Aug 3, 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 3, 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.8.3.tar.gz (472.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.8.3-py3-none-any.whl (343.1 kB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: movie_narrator-0.8.3.tar.gz
  • Upload date:
  • Size: 472.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.8.3.tar.gz
Algorithm Hash digest
SHA256 16c950b2331f1d5d78c7928c93c43ec52c64ee70206a602af734869ec6fd800b
MD5 01d1ffde8cf978fb6276ae6ee2f23e62
BLAKE2b-256 b2e9269cf312f2cb6119786fc98e9858ee016e1edcd7cfb9f7217f031083811f

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: movie_narrator-0.8.3-py3-none-any.whl
  • Upload date:
  • Size: 343.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.8.3-py3-none-any.whl
Algorithm Hash digest
SHA256 c8d5cee5574470bc70e385d7c6dccf7e0ba7494f2efd436a768f35b8e87f3067
MD5 9bc59bf0be2f83438f8b86c0b61711ce
BLAKE2b-256 3a5e4c354babb64ba0d41531b82da591c89591b287292a883859fa7578a7a498

See more details on using hashes here.

Provenance

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

This release

0.8.3 This release

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