baseline: initial working version
This commit is contained in:
167
README.md
Normal file
167
README.md
Normal file
@@ -0,0 +1,167 @@
|
||||
# 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
|
||||
```
|
||||
Reference in New Issue
Block a user