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, 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 with source attribution
  • 🖥️ Web UI (separate movie-narrator-web package)
  • 🎞️ Video rendering (1080p/4K output)
  • 📝 Script markdown export
  • 🎵 Background music integration
  • 🔌 Extensible plugin architecture (custom TTS / LLM backends)
  • ☁️ Async task processing (submit and go, notified on completion)
  • 🌐 Remote inference via REST API
  • ✅ Final-video QA — black-frame / slideshow-risk detection
  • 🗣️ Optional Chinese ASR (automatic multi-backend fallback)

Installation

Requirements

  • Python 3.10+

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 + faster-whisper + FunASR + 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 is limited to Python < 3.14 — PyTorch itself is now 3.14-ready (2.10+), but downstream ML dependencies (WhisperX, FunASR) have not yet shipped Python 3.14 wheels; on 3.14+ it is silently skipped and the align/match steps automatically soft-degrade (see Soft steps).

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.

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              # Show full CLI help

All CLI flags and usage examples 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/FunASR align, 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)

clips/ holds a standalone clip per segment, ready for secondary editing or reuse.

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

For contributors — most users only need mn create. See Architecture for details.

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

Compliance Notices

  • Edge-TTS: the default TTS channel (edge) is built on a reverse-engineered, unofficial interface. It is provided for personal / non-commercial free testing only. For commercial deployment, switch MN_TTS_PROVIDER to openai or mimo (both built-in).
  • TMDB: movie research data is sourced from TMDB (The Movie Database). When TMDB data is used, the source attribution is recorded in research.json as required, as a courtesy.

License

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

Project links

Data verified by PyPI on Aug 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 Aug 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 s3 otel 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-1.4.1.tar.gz (758.7 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-1.4.1-py3-none-any.whl (500.9 kB view details)

Uploaded Python 3

File details

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

File metadata

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

File hashes

Hashes for movie_narrator-1.4.1.tar.gz
Algorithm Hash digest
SHA256 8f5e1fc8d1ee727057d6d9ab992585ade1745829c42c8719afe8f5fc719af8f1
MD5 1f8f1b7271a1c7c83234d901efca0057
BLAKE2b-256 b283d26338f817674aa0e807c066ee5859f4fdaece6a638e0fbe575ed91023b7

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: movie_narrator-1.4.1-py3-none-any.whl
  • Upload date:
  • Size: 500.9 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-1.4.1-py3-none-any.whl
Algorithm Hash digest
SHA256 64a3890c3882f933f4c2dc4899bcd1a63d8639a1e6fc2c2bb53b48e100a5d320
MD5 1bf48e4e89863469a7fe77a5aae7bfa2
BLAKE2b-256 f9945e82192080c8777ca0db156497b3c5a9564acd64a5fef79c89415fbc4336

See more details on using hashes here.

Provenance

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

This release

1.4.1 This release

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

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