Setup
Create a Python virtual environment
Python 3.11 is recommended to match the Docker image and ensure all dependencies resolve correctly.
Install ImageMagick
ImageMagick is required for subtitle rendering. Without it, video generation will fail.
- Windows
- macOS
- Ubuntu / Debian
- CentOS / RHEL
- Download the static library installer from imagemagick.org/script/download.php. Select the Windows version labeled static, for example:
ImageMagick-7.1.1-32-Q16-x64-static.exe. - Run the installer. Do not change the default installation path, and avoid paths containing Chinese characters.
- Open
config.tomland setimagemagick_pathto the actual path of themagick.exebinary:
Configure the application
Copy the example configuration and fill in your API keys:Open
config.toml and set at minimum:Start the Web UI
Run the following command from the root directory of the project:The Web UI runs at http://localhost:8501.
- Windows
- macOS / Linux
Double-click The script sets
webui.bat, or run it from the command prompt:PYTHONPATH automatically and launches Streamlit. Your browser should open automatically.If you need to download the Whisper model and HuggingFace is not accessible in your region, uncomment the mirror line in
webui.sh before launching:Start the API server (optional)
The API server is separate from the Web UI and exposes a REST interface for programmatic use.Once running, API documentation is available at:
| Interface | URL |
|---|---|
| Swagger UI | http://127.0.0.1:8080/docs |
| ReDoc | http://127.0.0.1:8080/redoc |
ffmpeg
ffmpeg is required for video processing. In most environments it is downloaded automatically by themoviepy package at runtime.
If automatic download fails, you will see an error like:
config.toml:
Subtitle generation modes
Thesubtitle_provider setting in config.toml controls how subtitles are generated:
| Mode | Speed | Quality | Notes |
|---|---|---|---|
edge | Fast | Good | No extra setup required. Recommended default. |
whisper | Slow | More accurate | Downloads a ~3 GB model from HuggingFace on first use. |
subtitle_provider blank to disable subtitle generation entirely.