youtube-auto-dub/README.md

# YouTube Auto Dub

YouTube Auto Dub is a Python pipeline that downloads a YouTube video, transcribes its speech with Whisper, translates the subtitle text through a local LM Studio server, and renders a subtitled output video.

## What Changed

- Translation now uses an LM Studio OpenAI-compatible `/v1/chat/completions` endpoint.
- Google Translate scraping has been removed from the active runtime path.
- LM Studio is now the default and only supported translation backend.
- Translation settings can be configured with environment variables or CLI flags.

## Requirements

- Python 3.10+
- [uv](https://docs.astral.sh/uv/)
- FFmpeg and FFprobe available on `PATH`
- LM Studio running locally with an OpenAI-compatible server enabled

## Setup

Create a UV-managed virtual environment in a repo subfolder and install dependencies:

```powershell
uv venv --python "C:\pinokio\bin\miniconda\python.exe" .venv
uv pip install --python .venv\Scripts\python.exe -r requirements.txt
```

Verify the local toolchain:

```powershell
.venv\Scripts\python.exe --version
ffmpeg -version
ffprobe -version
.venv\Scripts\python.exe main.py --help
```

## LM Studio Configuration

Start LM Studio's local server and load a translation-capable model. The default model name in this repo is:

```text
gemma-3-4b-it
```

If your local LM Studio model name differs, set it with an environment variable or `--lmstudio-model`.

### Environment Variables

```powershell
$env:LM_STUDIO_BASE_URL="http://127.0.0.1:1234/v1"
$env:LM_STUDIO_API_KEY="lm-studio"
$env:LM_STUDIO_MODEL="gemma-3-4b-it"
```

Defaults if unset:

- `LM_STUDIO_BASE_URL=http://127.0.0.1:1234/v1`
- `LM_STUDIO_API_KEY=lm-studio`
- `LM_STUDIO_MODEL=gemma-3-4b-it`

## Usage

Basic example:

```powershell
.venv\Scripts\python.exe main.py "https://youtube.com/watch?v=VIDEO_ID" --lang es
```

Override the LM Studio endpoint or model from the CLI:

```powershell
.venv\Scripts\python.exe main.py "https://youtube.com/watch?v=VIDEO_ID" `
  --lang fr `
  --translation-backend lmstudio `
  --lmstudio-base-url http://127.0.0.1:1234/v1 `
  --lmstudio-model gemma-3-4b-it
```

Authentication options for restricted videos still work as before:

```powershell
.venv\Scripts\python.exe main.py "https://youtube.com/watch?v=VIDEO_ID" --lang ja --browser chrome
.venv\Scripts\python.exe main.py "https://youtube.com/watch?v=VIDEO_ID" --lang de --cookies cookies.txt
```

## CLI Options

| Option | Description |
| --- | --- |
| `url` | YouTube video URL to process |
| `--lang`, `-l` | Target language code |
| `--browser`, `-b` | Browser name for cookie extraction |
| `--cookies`, `-c` | Path to exported cookies file |
| `--gpu` | Prefer GPU acceleration when CUDA is available |
| `--whisper_model`, `-wm` | Override Whisper model |
| `--translation-backend` | Translation backend, currently `lmstudio` |
| `--lmstudio-base-url` | Override LM Studio base URL |
| `--lmstudio-model` | Override LM Studio model name |

## Translation Behavior

The LM Studio translator is tuned for subtitle-like text:

- preserves meaning, tone, and intent
- keeps punctuation natural
- returns translation text only
- preserves line and segment boundaries
- leaves names, brands, URLs, emails, code, and proper nouns unchanged unless transliteration is clearly needed
- avoids commentary, summarization, and censorship

Translation is currently performed segment-by-segment to keep subtitle ordering deterministic and reduce the risk of malformed batched output corrupting timing alignment.

## Testing

Run the focused validation suite:

```powershell
.venv\Scripts\python.exe -m pytest
.venv\Scripts\python.exe main.py --help
```

The tests cover:

- LM Studio request payload construction
- response parsing
- retry handling for transient HTTP failures
- empty or malformed response handling
- CLI and environment config precedence

## Troubleshooting

### LM Studio connection errors

- Make sure LM Studio's local server is running.
- Confirm the base URL ends in `/v1`.
- Check that the loaded model name matches `LM_STUDIO_MODEL` or `--lmstudio-model`.

### Empty or malformed translations

- Try a stronger local instruction-tuned model if your current model ignores formatting.
- Keep LM Studio in non-streaming OpenAI-compatible mode.
- Review the server logs for model-side failures.

### FFmpeg missing

If startup reports missing `ffmpeg` or `ffprobe`, install FFmpeg and add it to your system `PATH`.

## Project Layout

```text
youtube-auto-dub/
|-- main.py
|-- requirements.txt
|-- language_map.json
|-- README.md
|-- LM_STUDIO_MIGRATION.md
|-- src/
|   |-- core_utils.py
|   |-- engines.py
|   |-- media.py
|   |-- translation.py
|   `-- youtube.py
`-- tests/
    |-- conftest.py
    |-- test_main_cli.py
    `-- test_translation.py
```