translatedub 0.3.0

Local-first, cross-platform video translation, subtitling and AI dubbing.

TranslateDub AI

Local-first, cross-platform video translation, subtitling, and AI dubbing — as a CLI, a Python library, or a one-command local web app.

Translate a video into another language, review the bilingual subtitles, generate a dubbed voice track, and export a ready-to-share video — all on your own machine. Your video files and API keys never leave your computer.

---

Install

Requires Python 3.9+. No code signing, no downloads to unblock, no admin rights.

pipx install translatedub          # recommended (isolated), or:
pip install translatedub
# run once without installing:
uvx translatedub serve

FFmpeg is resolved automatically: it uses a system ffmpeg if present, otherwise the bundled-per-platform binary from the imageio-ffmpeg dependency. Nothing extra to install.

For a fully free, no-API-key pipeline (recommended), install the optional extra:

pip install "translatedub[free]"

This enables local speech recognition (faster-whisper), free translation (deep-translator), and free neural voices incl. natural Vietnamese (edge-tts) — so you can transcribe, translate, and dub without any API key. With a Gemini key set, the app prefers Gemini automatically for higher quality. edge-tts (LGPLv3) is optional and invoked via its CLI; nothing here is bundled or modified.

For premium Google Cloud voices, install the optional extra and add a key:

pip install "translatedub[cloud]"

Quick start

No API key needed with the [free] extra installed:

# Translate + dub a video in one command
translatedub translate input.mp4 --to vi -o output.mp4

# …or open the visual editor in your browser (edit subtitles before export)
translatedub serve

Optional — higher quality with a Gemini key (free tier at Google AI Studio). With a key stored, the app prefers Gemini automatically for transcription and translation:

translatedub config set-key   # kept in a chmod 600 file, never in the repo

Three ways to use it

Mode	Command	Best for
CLI	translatedub translate ...	scripting, batch, power users
Web UI	translatedub serve	reviewing/editing subtitles, non-technical users
Library	from translatedub.core import ...	embedding in your own tools

CLI examples

# Subtitles only (no dubbing), burned into the video
translatedub translate talk.mp4 --to en --subtitles-only --burn-subtitles

# Premium Google Cloud voice, keep 20% of the original audio under the dub
translatedub translate vlog.mp4 --to vi --engine google_cloud \
  --voice vi-VN-Neural2-A --original-vol 0.2

# See all options
translatedub translate --help

Library example

from translatedub.pipeline import translate_video, export_video

subs = translate_video("input.mp4", "auto", "vi", gemini_key="...")
for s in subs:
    print(s.index, s.translated_text)          # review / edit programmatically
export_video("input.mp4", subs, "output.mp4", target_lang="vi")

How it works

1. Extract audio with FFmpeg.
2. Transcribe speech with faster-whisper (local, free) or Google Gemini (auto-chunked for long videos).
3. Translate with deep-translator (free) or Gemini — by default the app picks Gemini when a key is present, the free local stack otherwise.
4. Review/edit bilingual subtitles (in the web UI) or use them directly (CLI/library).
5. Generate a dubbed voice track with edge-tts (free neural voices, default), gTTS (fallback), or Google Cloud TTS (premium), with optional duration matching so speech fits each subtitle window.
6. Mux the dub over the original video, with optional burned-in or soft subtitles.

This is an independent implementation inspired by the general workflow of pyVideoTrans. It does not vendor or depend on pyVideoTrans source code, assets, or binaries.

Security & privacy

Local-first by design. Nothing is uploaded to any server run by this project.

Data	Handling
Gemini API key	Environment variable, or ~/.translatedub/config.json created chmod 600
Google Cloud service-account JSON	Same as above (env var or the config file)
Video / audio	Processed on your machine; temp files under ~/.translatedub/temp
The local web server	Bound to 127.0.0.1 and rejects non-local requests

Credential storage follows the same model as gh, aws, and npm: environment variable first, then an owner-only file. See SECURITY.md.

Supported credential environment variables: TRANSLATEDUB_GEMINI_KEY (or GEMINI_API_KEY), TRANSLATEDUB_GOOGLE_CLOUD_CREDENTIALS (or GOOGLE_APPLICATION_CREDENTIALS pointing to a JSON file).

Develop

git clone https://github.com/Phong-EpicMind/video-translate-pro.git
cd video-translate-pro
python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -e ".[dev,cloud]"
pytest

License

MIT — see LICENSE. Third-party components (FFmpeg, Google libraries, etc.) are under their own licenses; see THIRD_PARTY_NOTICES.md.

---

Tiếng Việt

TranslateDub AI là công cụ dịch video, làm phụ đề song ngữ và lồng tiếng bằng AI, chạy cục bộ trên máy (Mac/Windows/Linux). Video và API key không rời khỏi máy bạn. Dùng được theo 3 cách: dòng lệnh (CLI), giao diện web (một lệnh mở trình duyệt), hoặc thư viện Python.

Cài đặt

Cần Python 3.9+. Không cần ký app, không cảnh báo tải về.

pip install "translatedub[free]"   # bản đầy đủ, KHÔNG cần API key

FFmpeg tự lo: dùng ffmpeg hệ thống nếu có, không thì lấy bản đi kèm imageio-ffmpeg.

Bắt đầu nhanh

Không cần API key — nhận dạng giọng nói, dịch và lồng tiếng đều có sẵn bản miễn phí (faster-whisper + deep-translator + edge-tts, có giọng tiếng Việt tự nhiên):

translatedub translate input.mp4 --to vi -o out.mp4 # dịch + lồng tiếng một lệnh
translatedub serve                                  # hoặc mở giao diện web để sửa phụ đề

Muốn chất lượng cao hơn thì thêm Gemini key (có bậc miễn phí tại Google AI Studio) — app sẽ tự ưu tiên Gemini:

translatedub config set-key                         # key lưu file chmod 600 trên máy bạn

Bảo mật

Chạy cục bộ, không upload lên server nào của dự án. Key lưu trong biến môi trường hoặc file ~/.translatedub/config.json với quyền chmod 600 (giống cách gh, aws, npm làm). Server web chỉ nhận kết nối từ 127.0.0.1. Xem SECURITY.md.

Đây là dự án độc lập, lấy cảm hứng từ quy trình tổng quát của pyVideoTrans; không copy/phụ thuộc source code, asset hay binary của pyVideoTrans.

Giấy phép

MIT — xem LICENSE.