Connect the World, Frame by Frame

English｜简体中文｜繁體中文｜日本語｜Español｜Русский｜Français

🌟 Overview (Try VL Now!)

VideoLingo combines speech recognition, subtitle translation, segmentation and dubbing in a Streamlit interface. It produces subtitle files and optionally subtitled or dubbed videos. Translation quality depends on the source audio, language and chosen models.

Key features:

• 🎥 YouTube video download via yt-dlp

• Word-level speech recognition and alignment with Qwen3-ASR + Qwen3-ForcedAligner

• 📝 NLP and AI-powered subtitle segmentation

• 📚 Custom + AI-generated terminology for coherent translation

• Direct translation with optional reflection and natural rewriting

• Subtitle segmentation with configurable length limits

• 🗣️ Dubbing with GPT-SoVITS, OpenAI, Edge TTS, and more

• 🚀 One-click startup and processing in Streamlit

• 🌍 Multi-language support in Streamlit UI

• 📝 Detailed logging with progress resumption

• 🔍 Model searchbox with API auto-fetch — search and filter from your provider's full model list

• ⏯️ Task control — pause, resume, or stop processing at any step

The workflow combines transcription, translation, subtitle layout and dubbing in one project.

🎥 Demo

Language Support

Input languages:

🇺🇸 English 🤩 | 🇷🇺 Russian 😊 | 🇫🇷 French 🤩 | 🇩🇪 German 🤩 | 🇮🇹 Italian 🤩 | 🇪🇸 Spanish 🤩 | 🇯🇵 Japanese 😊 | 🇨🇳 Chinese 🤩

Dubbing languages depend on the selected TTS method.

Installation

VideoLingo supports Windows, macOS (Apple Silicon / Intel), and Linux.

Ask your local AI agent 🤖

If you use an AI agent that can operate your computer, send it this prompt:

Install and launch GitHub's Huanshere/VideoLingo on my computer.

Windows: one-click install 🎉

1. Download Source code (zip) from the latest Release, extract it to your Desktop or another folder, and open the folder.
2. Double-click OneKeyStart.bat and keep the window open. On the first run, it automatically installs uv, Python 3.12, the app dependencies, and FFmpeg. An internet connection is required.
3. After installation, VideoLingo opens automatically in your browser. Enter your API URL, key, and model in the sidebar to start using it.

Install from source (Windows, macOS, Linux)

git clone https://github.com/Huanshere/VideoLingo.git && cd VideoLingo
uv run start.py

To start it later, run uv run start.py again from the VideoLingo folder. Apple Silicon uses MLX; Intel Macs use CPU recognition. By default, Intel Mac dubbing uses the new voice without the original background sound.

Docker (optional)

For a Linux NVIDIA container deployment, install Docker, a compatible GPU driver and the NVIDIA Container Toolkit. The image uses the same Python 3.12 setup and application dependencies, with CUDA 12.8.1/cu128 by default. See Docker docs for the matched CUDA 12.6 alternative and persistence settings.

docker build -t videolingo .
docker run -d -p 8501:8501 --gpus all videolingo

HTTP API (replaces Excel batch mode)

For agents and scripts, use the local HTTP API instead of the former Excel batch mode. It shares the Streamlit pipeline and processes one operation at a time using output/. Configure config.yaml and start it from the project root. The command also installs missing dependencies on first use:

uv run start.py --api

See the HTTP API guide for input, processing, progress, downloads, retries and serial batch processing. Interactive endpoint docs: localhost:8000/docs.

LLM, ASR and TTS providers

VideoLingo supports OpenAI-Like API format and various TTS interfaces:

• LLM: choose an OpenAI-compatible Chat Completions provider and model that can return the structured JSON required by the workflow. OpenLux is recommended; set the API URL to https://api.openlux.ai/v1. Prefer GPT-6 Luna with model ID gpt-6-luna for best value, GPT-6 Sol with gpt-6-sol for better quality, or Claude Opus 5.5 with claude-opus-5-5 for best quality. OpenLux relay rates are in the install docs. Configure the API URL, key and model in the sidebar.
• Speech recognition: run Qwen3-ASR + ForcedAligner locally (default), or choose ElevenLabs or MAI-Transcribe-2 in the sidebar. MAI supports an Azure Speech key or an OpenRouter key entered in the sidebar; audio is sent to the selected provider and may incur charges. WhisperX is not installed by the installer; to use it as a backend, follow WhisperX (manual install).
• TTS: OpenAI, Fish Audio, SiliconFlow Fish/CosyVoice2, GPT-SoVITS, Edge TTS, F5-TTS and a custom adapter in core/tts_backend/custom_tts.py.

For detailed installation, LLM configuration, and usage instructions, please refer to the documentation: English | 中文

Current Limitations

1. Background noise and language-specific alignment models affect recognition and word timestamps. Vocal separation may help. Numbers and symbols may lack reliable word timings; inspect the resulting subtitles.

2. LLM output must satisfy the workflow's JSON structure. For failures, inspect output/gpt_log/error.json. Existing successful response caches and completed outputs can be reused on retry; changing the model alone does not regenerate every completed stage. Do not delete all output as the first troubleshooting step.

3. Dubbing quality and timing depend on translation, the TTS service and speech rate. Speed adjustment does not guarantee natural delivery or perfect synchronization.

4. Local recognition uses one primary recognition/alignment language per audio segment. Mixed-language speech is not guaranteed to retain accurate text and timing in every language.

5. The dubbing workflow does not automatically assign a separate voice to each speaker.

📄 License

This project is licensed under the Apache 2.0 License. Special thanks to the following open source projects for their contributions:

Qwen3-ASR, MLX Audio, whisperX, yt-dlp, json_repair, BELLE

📬 Contact Me

• Submit Issues or Pull Requests on GitHub
• DM me on Twitter: @Huanshere
• Email me at: team@videolingo.io

⭐ Star History

If you find VideoLingo helpful, please give me a ⭐️!