harry0703/MoneyPrinterTurbo instruction manual

1. Purpose, supported platforms, and Claude Code classification

MoneyPrinterTurbo is an MIT-licensed Python application that turns a topic, keyword, or supplied script into a finished short video. Its documented workflow can write a multilingual script, derive footage-search terms, obtain or generate visual material, synthesize narration, create subtitles, add background music, and render an HD MP4. It supports portrait `9:16` output at `1080x1920` and landscape `16:9` output at `1920x1080`. It can generate several alternatives in one batch, and the segment-duration control changes how frequently footage switches.

The four documented interfaces are an AI-agent Skill, a Streamlit WebUI, an HTTP API, and a browser-free CLI. The codebase is described as separated into controllers, services, and models. Generated videos can optionally be published to TikTok, Instagram, and YouTube Shorts. Settings can be exported or imported as preset files; the settings dialog can also back up and restore all API keys.

**Claude Code classification: unclassified.** First-party evidence documents a generic Skill for an AI agent that can read Skill documents and use a terminal, network, filesystem, and long-running commands. It does not explicitly identify Claude Code as a supported host or provide a Claude Code plugin, hook, MCP server, marketplace package, or Claude-specific installation path. A sponsor’s claim about its own Claude Code compatibility does not establish MoneyPrinterTurbo’s mechanism. Therefore, a reliable Claude Code extension classification is not supported. Independently of Claude Code, the repository is clearly a standalone video-generation application with a portable agent workflow.

Local use requires Python 3.11 or newer; Python 3.11 is recommended. Suggested systems are Windows 10, macOS 11 or newer, and mainstream Linux distributions. Minimum hardware is 4 CPU cores and 4 GB RAM; 6–8 cores and 8 GB RAM are recommended. A GPU is optional, but 4 GB or more VRAM is recommended for local transcription, faster processing, or batching. The documented Agent helper supports macOS and Windows only.

2. What the generation pipeline can do

A job begins with either a subject or a custom script. When script generation is enabled, a configured large-language-model service writes the narration and extracts keywords used to choose the visuals. Supported model families and services include Kimi/Moonshot, OpenAI, Anthropic Claude, Gemini, DeepSeek, Qwen, Azure OpenAI, Volcengine Ark, xAI Grok, MiniMax, and Xiaomi MiMo. The documentation also lists Cloudflare AI Gateway, ModelScope, AIHubMix, AIML API, EvoLink, Ollama, OneAPI, LiteLLM, Groq, and Pollinations AI as compatible gateways, aggregators, or local environments.

Visuals may come from the user’s local files or from Pexels, Pixabay, and Coverr. AI-generated footage is available through WaveSpeed AI text-to-video, with Seedance described as its default model. A separate native Volcengine Ark Seedance source accepts either a model name or inference-endpoint ID. That path is text-to-video only in its documented first version: each clip creates an asynchronous paid task, the program polls only that task ID, stops ordering when status is uncertain, and creates only enough footage to cover narration length.

Narration choices are Edge TTS, Azure Speech, SiliconFlow, Google Gemini, Xiaomi MiMo, ElevenLabs, self-hosted Chatterbox, Fish Audio, or no narration. Voices can be previewed in real time. Edge TTS is free, needs no key, and appears in the WebUI as **Azure TTS V1**; Azure TTS V2 and other cloud providers need their own credentials.

Subtitles can be styled by font, position, color, size, outline, and background. Background music can be selected randomly or explicitly and its volume adjusted. Included songs reside in `resource/songs`; the README warns that some defaults came from YouTube and should be removed if they infringe rights. Subtitle fonts reside in `resource/fonts`, where custom fonts may also be placed. An optional `twelvelabs` dependency exists for TwelveLabs video-understanding/embedding integration when `twelvelabs_api_keys` is configured.

3. Installation and deployment choices

For a normal local checkout, clone the repository:

git clone https://github.com/harry0703/MoneyPrinterTurbo.git

The first launch can create `config.toml` from `config.example.toml`; model providers, footage sources, and keys can then be set in the WebUI. Windows paths should not contain Chinese characters, special characters, or spaces.

The preferred manual setup uses `uv` and the locked dependency set:

git clone https://github.com/harry0703/MoneyPrinterTurbo.git
cd MoneyPrinterTurbo
uv python install 3.11
uv sync --frozen

`pyproject.toml` is the primary dependency definition, `uv.lock` fixes resolved versions, and `requirements.txt` remains only for legacy pip compatibility. The documented alternative is:

python3.11 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

For an isolated deployment, first copy `config.example.toml` to `config.toml` so the container can mount it, then run the documented prebuilt-image configuration:

cd MoneyPrinterTurbo
docker compose -f docker-compose.release.yml up

This pulls `ghcr.io/harry0703/moneyprinterturbo:latest`. `docker compose up` is the documented alternative when a local image rebuild is needed. The WebUI is then at `http://127.0.0.1:8501`; OpenAPI documentation is at `http://127.0.0.1:8080/docs` or `http://127.0.0.1:8080/redoc`.

Windows users may instead download the latest one-click package from `https://github.com/harry0703/MoneyPrinterTurbo/releases/latest`. Extract it to a compliant path, run `update.bat`, and then run `start.bat`; the browser opens automatically. Chrome or Edge is suggested if the page is blank. A repository notebook is also linked for Google Colab use. Docker Desktop is required for the Docker route, with Microsoft WSL/container documentation linked for Windows.

4. WebUI, API, CLI, and batch operation

Run interface commands from the repository root. On Windows, start the WebUI with:

.\webui.bat

CMD may use `webui.bat`. The launcher prefers the project `.venv` or bundled Python and falls back to `uv run streamlit` when `uv` is available. To expose it to other LAN devices, first set `MPT_WEBUI_HOST=0.0.0.0`, then run the batch file. On macOS or Linux:

sh webui.sh

For LAN access:

MPT_WEBUI_HOST=0.0.0.0 sh webui.sh

Start the API service with:

uv run python main.py

If the virtual environment is already activated, the documented alternative is `python main.py`. API browser access is same-origin by default. Only a separate browser frontend making cross-origin requests should set `CORS_ALLOWED_ORIGINS` to trusted comma-separated origins, such as `http://localhost:3000,https://frontend.example.com`. CORS does not restrict curl, Postman, n8n, or server-to-server clients.

Generate one video without a browser:

uv run python cli.py --video-subject "人工智能如何改变日常生活"

Inspect all documented CLI options with:

uv run python cli.py --help

Explicit CLI subtitle and narration options override `[ui]` values saved in `config.toml`, which override built-in defaults. Other settings—such as music, video count, and paragraph count—do not automatically inherit saved WebUI values. Uploaded narration paths are not saved, so CLI jobs must explicitly pass `--custom-audio-file`.

Sequential batch execution accepts a UTF-8 JSON array or JSONL manifest:

uv run python cli.py --batch-file ./tasks.json --stop-at video

CLI arguments become global defaults, while each manifest object may override `VideoParams` fields. A manifest is limited to 100 jobs and 1 MiB. All entries and local files are prechecked before the first job. One failure does not stop later jobs, and a combined JSON summary is printed at the end. Relative custom-audio and local-media paths resolve from the manifest’s directory.

5. AI-agent Skill workflow

The README supplies this copy-paste request for an agent that can read Skill documents and operate a local terminal:

使用这个 Skill：https://raw.githubusercontent.com/harry0703/MoneyPrinterTurbo/main/docs/skill/SKILL.md
帮我生成一个主题为“人工智能如何改变普通人的日常生活”的视频。

The Skill targets a final MP4, not merely setup guidance. It covers installation, reuse of existing configuration, detection of missing credentials, generation, waiting, failure repair, and returning the generated file path. Its defaults are one Chinese portrait `9:16` video using Pexels, the default Chinese Edge TTS voice, subtitles, and music, installed under the user’s home directory.

The adjacent helper is `docs/skill/mpt_agent.py`. The documented foreground invocation, run from the Skill directory with a timeout of at least 20 minutes, is:

uv run --no-project --python 3.11 python mpt_agent.py --subject "<video topic>"

If `uv` is explicitly reported missing, the Skill documents these installers:

curl -LsSf https://astral.sh/uv/install.sh | sh

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Success emits `MPT_RESULT` plus absolute `VIDEO_FILE`, `TASK_DIR`, `LOG_FILE`, and `RESULT_FILE` paths. The helper reports the video only after checking it exists and is non-empty. Exit code 10 means required credentials are missing; possible environment fields are `MPT_LLM_PROVIDER`, `MPT_LLM_API_KEY`, `MPT_LLM_BASE_URL`, `MPT_LLM_MODEL_NAME`, `MPT_PEXELS_API_KEY`, and `MPT_VOLCENGINE_ARK_API_KEY`. Exit code 1 indicates a repairable or reportable failure.

The Skill forbids exposing keys or the full configuration. Seedance requires explicit paid-task confirmation before adding `--confirm-seedance-charge`. Extra video requirements may be passed after `--`; `cli.py --help` is used only to verify an unfamiliar option. This workflow supports macOS and Windows, uses only `uv` and the CLI, and excludes Docker, WebUI, API startup, and concurrent video jobs.

6. Subtitles, providers, publishing, and configuration

The default subtitle provider is `edge`, which derives timing from TTS timestamps and does not need a GPU. The `whisper` provider uses local `faster-whisper` transcription for potentially more accurate timing; its first run downloads a model. Configure the smaller, faster approximately 1.6 GB model as follows:

[app]
subtitle_provider = "whisper"

[whisper]
model_size = "large-v3-turbo"

The default `large-v3` is described as approximately 3 GB. If automatic Hugging Face download fails, manually download `Systran/faster-whisper-large-v3`, extract the complete model into `MoneyPrinterTurbo/models/whisper-large-v3`, and preserve files such as `config.json`, `model.bin`, `preprocessor_config.json`, `tokenizer.json`, and `vocabulary.json`.

To publish after rendering, obtain an Upload-Post key and add:

[app]
upload_post_enabled = true
upload_post_api_key = "your-api-key"
upload_post_username = "your-username"
upload_post_platforms = ["tiktok", "instagram", "youtube"]
upload_post_auto_upload = true
upload_post_youtube_privacy_status = "public"

Restart the application after saving. YouTube visibility may be `public`, `unlisted`, or `private`.

For native Volcengine Ark Seedance, use:

[app]
volcengine_seedance_api_key = "your-ark-api-key"
volcengine_seedance_model = "doubao-seedance-1-0-pro-250528"
volcengine_seedance_base_url = "https://ark.cn-beijing.volces.com/api/v3"

When the dedicated key is empty, lookup falls back first to `VOLCENGINE_ARK_API_KEY`, then to the existing `volcengine_api_key` LLM setting. Select “Volcengine Seedance” as the video source and explicitly confirm the paid job before generation; CLI use additionally requires `--confirm-seedance-charge`.

Configuration carries sensitive provider credentials. Use WebUI controls for provider selection and voice preview, and use preset export/import for generation settings. The settings dialog separately supports backing up and restoring all API keys. Do not publish `config.toml`, exported credentials, or keys in logs or issue reports.

7. Troubleshooting and operating boundaries

If FFmpeg cannot be found, it is normally downloaded and detected automatically. When that fails, download an FFmpeg build from the README’s linked source and set the executable’s actual path:

[app]
# 请根据你的实际路径设置，注意 Windows 路径分隔符为 \\
ffmpeg_path = "C:\\Users\\harry\\Downloads\\ffmpeg.exe"

On systems that report `OSError: [Errno 24] Too many open files`, inspect the open-file limit:

ulimit -n

If it is too low, the documented example raises it for the current environment:

ulimit -n 10240

Whisper messages mentioning `LocalEntryNotFoundError`, disabled outgoing traffic, or a missing cached snapshot indicate that the model was not obtained. Use the manual model placement described in the subtitle section. A GPU is not mandatory, but local Whisper, heavier processing, and multi-video generation benefit from one. Cloud LLM, TTS, and footage workflows depend more heavily on CPU, memory, credentials, network availability, provider quotas, and provider terms.

The supplied documentation establishes only the listed platforms and workflows. The Agent Skill is narrower than the application: it supports only macOS and Windows, requires terminal/network/filesystem/long-running-command capabilities, and mandates `uv`. The broader README also documents Linux, legacy pip, Docker, WebUI, and API operation. Do not assume the Skill’s automation is available in every agent host.

Stock-media licensing and generated-content rights still need user review. The project describes Pexels, Pixabay, and Coverr material as freely usable, but users should verify each asset’s applicable terms. Provider calls may be paid, especially one asynchronous Ark task per Seedance clip. Social publishing sends completed videos and account information to Upload-Post and the selected platforms. API keys should be restricted and protected. The README’s promotional provider claims and discounts are sponsor statements, not verified application guarantees.

8. Testing, maintenance, security, and support

The test suite contains task-pipeline tests, in-memory and Redis queue tests, domain-split API controller tests, video and voice service tests, and an application-entry-point test. Run all tests with the CI-style command:

uv run python -X utf8 -m pytest -q test

Run one file, class, or method with the documented forms:

uv run python -X utf8 -m pytest -q test/services/test_video.py
uv run python -X utf8 -m pytest -q test/services/test_video.py::TestVideoService
uv run python -X utf8 -m pytest -q test/services/test_video.py::TestVideoService::test_preprocess_video

Run the same branch-coverage check used by CI:

uv run python -X utf8 -m coverage run -m pytest -q test
uv run python -m coverage report

Coverage is configured for `app`, `cli`, `webui`, `main`, and `docs/skill`, with branch measurement and a 70% failure threshold. Tests may use pytest functions or `unittest.TestCase`; names must start with `test_`. New files should be named `test_<domain>.py`, broad controller suites should be divided by domain, and test assets belong in `test/resources`. Live provider tests are skipped unless `MPT_RUN_INTEGRATION_TESTS=1` is set and the required TTS or LLM credentials are provided.

The application is versioned as `1.3.5` in `pyproject.toml`, requires Python 3.11+, and is configured as an application rather than an installable Python package (`package = false`). The repository metadata identifies the MIT License. Security fixes are best-effort for the latest `main` branch and most recent release line.

Do not place vulnerability details, payloads, proof-of-concept code, or sensitive paths in public issues. Prefer GitHub private vulnerability reporting. If unavailable, create only a minimal public request for a private channel and wait for a maintainer. A private report should identify the affected commit/tag/release, attack surface, impact, reproduction conditions, and any suggested fix. Allow reasonable remediation time before coordinated disclosure. Ordinary bugs and proposals may be submitted through repository issues or pull requests.