Gemini YouTube Dubber
Project overviewGitHub ↗
Practical guide · cloud + local

How to use Gemini YouTube Dubber in practice.

This page starts with the easiest working path and then covers the local app. You can go from a public YouTube URL or your own video to translated speech, subtitles and—after finalization—a dubbed MP4.

Easiest for a public YouTube URLGitHub Actions Cloud Dub → download the artifact → finalize on Windows.
Easiest for a local video fileRun the Streamlit app → upload the video → download the final MP4 directly.
What you needA Gemini API key, permission to adapt the media, and Python only for local/finalization workflows.
Start here

Choose the workflow that matches your source.

Recommended for YouTube

Cloud Dub on GitHub Actions

Use this when your source is a public YouTube URL and you do not want your computer doing the main AI/timing job. GitHub creates the dubbing audio package. Because YouTube can block GitHub runner IPs, the source video download and final mux are intentionally completed on your Windows computer.

  • Main processing runs on GitHub.
  • Reusable transcript/TTS cache reduces repeated work.
  • The validated cloud timing path uses Gemini 3.5 Flash-Lite + Edge Neural TTS.
  • Final MP4 is produced in the local finalization step.

Local Streamlit app

Use this when you have your own video file, want an interactive UI, or prefer everything to run on your computer. The app accepts a YouTube URL or one uploaded video file and can return the final MP4, SRT and transcript JSON directly.

  • YouTube URL or uploaded MP4/MOV/WebM/etc.
  • Choose target language and dubbing voices.
  • Smart Chunk fast/balanced or precise mode.
  • Automatic Edge fallback if Gemini TTS is unavailable.
Cloud path

Run a public YouTube dub on GitHub.

The Cloud workflow requires one repository secret named GEMINI_API_KEY. Never paste a real API key into a commit, issue, README or public web page.

1

Get the project

Open the repository and clone/download it if you want to use the helper scripts. Repository: FaramarzKowsari/gemini-youtube-dubber.

2

Configure the Gemini secret once

On Windows, run SETUP_GITHUB_CLOUD.bat. It uses GitHub CLI, asks for a fresh Gemini API key in a secure prompt, stores it as the encrypted repository secret GEMINI_API_KEY, and opens the Cloud Dub workflow. Alternatively, create the same secret manually in GitHub repository Settings → Secrets and variables → Actions.

3

Open Cloud Dub

Go to Actions → Cloud Dub, choose Run workflow, and keep the branch on main.

4

Fill in the workflow inputs

Paste the public YouTube URL, enter the target language, choose the primary voice and optional second voice, keep Smart Chunk at 60 for the normal fast path, and set the original-audio percentage. 0 means the cloud dub track does not intentionally mix the source soundtrack under the dub.

5

Run and wait for a green result

The workflow restores cache/checkpoints, performs translation/timing work, generates speech, enforces the 1.10× natural-rate ceiling, builds the dubbing track and uploads an artifact named like cloud-dub-package-N.

6

Download the artifact ZIP

Open the completed workflow run and download the cloud-dub-package artifact. Keep the ZIP intact; the finalizer can select and unpack it for you.

Important: A successful Cloud Dub artifact is the finished dubbing package, not necessarily the final video. This hybrid design exists because GitHub-hosted runner IPs can be blocked when they try to download YouTube media.
Final MP4

Finalize the Cloud Dub on Windows.

1

Keep the repository folder on the PC

The folder must contain FINALIZE_CLOUD_DUB_WINDOWS.bat, finalize_cloud_dub.py and the project requirements.

2

Double-click the finalizer

Run FINALIZE_CLOUD_DUB_WINDOWS.bat. If needed, it creates a Python virtual environment and installs dependencies automatically.

3

Select the artifact ZIP

The finalizer asks you to select the ZIP you downloaded from GitHub Actions. It then downloads the source YouTube video on your computer—where YouTube access is normally more reliable—and merges the cloud-generated dub into the source video.

4

Use the final MP4

After successful muxing, the final dubbed video is ready locally. The package also preserves subtitles and machine-readable transcript/manifest data for auditing or further editing.

Local app

Run everything on your own computer.

1

Install Python 3 and get the repository

On Windows, the launcher manages the virtual environment and installs requirements.txt. The project is tested on Python 3.11, 3.12 and 3.13.

2

Launch the app

For a clean Windows setup, run UPGRADE_AND_RUN_WINDOWS.bat. The Streamlit interface opens in your browser.

3

Add your Gemini key

Paste the key into the password field in the sidebar, or put GEMINI_API_KEY=... in a local .env file. Do not commit .env.

4

Choose language, voice and speed mode

Select a target language or enter a custom one. Choose the primary/secondary voice. For normal use start with Smart Chunk — Fast (60 sec). Keep automatic Edge fallback enabled unless you specifically require Gemini TTS only.

5

Choose exactly one source

Either paste a public YouTube URL or upload a local video. Supported local extensions include MP4, MOV, MPEG/MPG, WebM, AVI, WMV and 3GP.

6

Create and download

Click Create dubbed video. After completion the app previews the result and provides direct buttons for Download MP4, Download SRT and Download transcript JSON.

Windows clean launch: UPGRADE_AND_RUN_WINDOWS.bat Typical local choice: Target language: Persian (فارسی) or another language TTS chunking mode: Smart Chunk — Fast (60 sec) Automatic speech fallback: On Gemini TTS pacing: Free-tier cautious Reuse cached speech: On
Settings

What do the important inputs mean?

InputRecommended starting valueMeaning
YouTube URLPublic URLThe source video Gemini analyzes. Restricted/private/DRM/age-gated content may fail.
Target languageYour real destination languagePersian is the repository default, but custom target languages are supported.
Primary / secondary voiceOne primary; secondary = Same unless neededVoice roles for dubbing. The current validated cloud path can use Edge as primary speech synthesis, so actual fallback timbre may differ from a Gemini preset name.
Smart Chunk60 secondsGroups nearby dialogue to reduce request count. 45 is more granular; 0/precise is slower and request-heavy.
Original soundtrack0–15% to startHigher values preserve more ambience but can also preserve original speech underneath the dub.
Automatic Edge fallbackOnLets speech continue when Gemini TTS quota/network access is unavailable. No second API key is required for Edge.
CacheOnReuses successful speech/transcript work and helps interrupted or repeated runs.
Outputs

What should you expect after a successful run?

Cloud workflow

The artifact includes at least the generated dubbing audio and metadata used by the finalizer, including dubbed_audio.wav, dubbed.srt, transcript.json, manifest.json and timing diagnostics. Cloud Dub #41 validated the current path end to end through package creation.

Local app

The local app creates the final dubbed_video.mp4 directly and provides downloadable SRT and transcript JSON in the UI.

Troubleshooting

If something fails, check this first.

Missing Gemini secret

If GitHub says GEMINI_API_KEY repository secret is missing, run SETUP_GITHUB_CLOUD.bat again or recreate the Actions secret manually.

429 / quota exceeded

This is a provider limit, not a corrupted video. Avoid repeated blind reruns. Cache/checkpoints can preserve completed work; capacity resets or paid quota may be needed for new AI calls.

YouTube download blocked

That is exactly why Cloud Dub is hybrid. Let GitHub create the audio package, then use the Windows finalizer to download the source video locally.

Speech is too long for a cue

The current precise cloud pipeline measures generated speech and asks Gemini to semantically compress overlong text, with a hard 1.10× natural-rate ceiling. If a new edge case still fails, inspect timing diagnostics instead of increasing the speed limit blindly.

Use only videos you own, have permission to adapt, or that are licensed for the intended reuse. Do not publish API keys or private media through a public repository.