- Python 96.5%
- Shell 3.5%
| mp4translate | ||
| tests | ||
| .gitignore | ||
| README.md | ||
| requirements.txt | ||
| setup.sh | ||
| translate_video.py | ||
mp4translate
Lokální převod anglického MP4 tutorialu na českou dabovanou verzi pro macOS Apple Silicon. Obraz zůstává bez rekomprese. České titulky se vkládají do MP4 jako přepínatelná stopa a vzniká také samostatné SRT.
Installation
brew install ffmpeg
./setup.sh
.venv/bin/python -m piper.download_voices cs_CZ-jirka-medium --data-dir models/piper
První spuštění stáhne také model Whisperu a překladače; další běhy mohou pracovat offline.
Usage
.venv/bin/python translate_video.py tutorial.mp4
Výchozí výstupy jsou tutorial_CZ.mp4 a tutorial_CZ.srt. Adresář lze zpracovat dávkově:
.venv/bin/python translate_video.py ./tutorials/
Examples
.venv/bin/python translate_video.py tutorial.mp4 --original-volume 0.08 --max-speed 1.25 --verbose
.venv/bin/python translate_video.py tutorial.mp4 --output tutorial_cesky.mp4 --no-srt
.venv/bin/python translate_video.py ./tutorials --output ./hotovo --overwrite
Zvukové stopy a titulky
.venv/bin/python translate_video.py tutorial.mp4 --dual-audio
Volba --dual-audio přidá dvě přepínatelné zvukové stopy: první „English“ je původní zvuk v plné hlasitosti, zkopírovaný bez rekomprese; druhá „Česky“ je český dabing s podkresleným originálem a je označena jako výchozí. Volby --original-volume a --dub-volume ovlivňují pouze český mix. Pro čistý český hlas použij --original-volume 0. Bez --dual-audio zůstává jedna česká mixovaná stopa.
Titulky jsou vždy vložené jako MP4 mov_text a zároveň uložené vedle videa jako SRT. Volba --no-srt vypne obě varianty. Nejsou vypálené do obrazu; lze je přepínat v nabídce titulků přehrávače. Zvuk se vybírá v nabídce zvukových stop (např. ve VLC). Výchozí výběr může přehrávač upravit podle vlastního nastavení jazyků.
.venv/bin/python translate_video.py tutorial.mp4 --dual-audio --no-srt
Testování
.venv/bin/python -m unittest discover -s tests -v
Integrační testy vyžadují FFmpeg a ffprobe. Vytvářejí krátká testovací videa bez stahování AI modelů a ověřují stopy, titulky, zachování délky i shodný obsah kopírovaného obrazu a originálního zvuku.
Options
Použij --help pro úplný přehled. Hlavní volby jsou --output, --original-volume, --dub-volume, --max-speed, --whisper-model, --translation-model, --piper-voice, --keep-temp, --overwrite, --dual-audio, --no-srt a --verbose.
Troubleshooting
- Chybějící ffmpeg/ffprobe: spusť brew install ffmpeg.
- Chybějící hlas Piperu: spusť výše uvedený příkaz piper.download_voices.
- Modely se při prvním běhu stahují; zkontroluj připojení a volné místo.
- Pro diagnostické JSON a WAV soubory použij --keep-temp --verbose.
Development notes
Lokální nástroj pro macOS, který převede anglické MP4 tutorial video na českou dabovanou verzi.
Projekt je určen primárně pro osobní použití a pro zpracování kratších tutorial videí, typicky přibližně 5 až 20 minut.
Hlavní cíl
Vytvoř Python CLI aplikaci, která provede celý proces automaticky:
anglické MP4
↓
extrakce audia
↓
speech-to-text
↓
anglický přepis s časováním
↓
překlad EN → CZ
↓
české TTS
↓
časová synchronizace
↓
mix audia
↓
české MP4
Výsledkem má být nové MP4 video se stejným obrazem a českým dabingem.
Projekt musí fungovat lokálně na macOS Apple Silicon.
Výchozí pracovní prostředí:
/Volumes/Macintosh HD/Users/cernoch/Documents/develop/mp4translate/
Základní požadavky
Preferuj lokální zpracování.
Nevyužívej cloudové API ani placené služby, pokud to není nutné.
Aplikace by po prvotním stažení modelů měla fungovat offline.
Použij samostatný Python virtual environment:
.venv
Python závislosti instaluj pouze do tohoto prostředí.
Systémové nástroje instaluj přes Homebrew.
Doporučené technologie
FFmpeg
Použij FFmpeg pro:
- extrakci audia z MP4
- převod audio formátů
- změnu rychlosti audia
- mix původního a českého audia
- vytvoření výsledného MP4
Instalace:
brew install ffmpeg
Před spuštěním programu ověř:
ffmpeg -version
ffprobe -version
Pokud FFmpeg není dostupný, aplikace má skončit s jasnou chybovou hláškou.
Speech-to-text
Pro převod anglického hlasu na text použij:
mlx-whisper
Je optimalizovaný pro Apple Silicon a používá framework MLX.
Oficiální MLX implementace podporuje instalaci:
pip install mlx-whisper
a používání z Pythonu:
import mlx_whisper
result = mlx_whisper.transcribe(...)
MLX Whisper je určen přímo pro Apple Silicon. citeturn237722search0turn237722search1turn237722search2
Použij Whisper model s dobrým kompromisem mezi přesností a rychlostí.
Preferovaný výchozí model:
mlx-community/whisper-large-v3-turbo
Pokud nebude vhodný nebo dostupný, použij aktuální ekvivalent vhodný pro mlx-whisper.
Nezůstávej slepě u názvu modelu uvedeného v README. Při implementaci ověř aktuálně doporučené MLX Whisper modely.
Důležité je získat minimálně:
[
{
"start": 12.5,
"end": 17.2,
"text": "Now open the configuration window."
}
]
tedy segmenty s:
start
end
text
Whisper musí běžet s explicitním jazykem:
English
Není třeba automatická detekce jazyka.
Překlad EN → CZ
Překlad musí běžet lokálně.
Jako první variantu použij:
Helsinki-NLP/opus-mt-en-cs
Model je určen přímo pro překlad English → Czech. citeturn591917search0turn591917search9
POZOR:
Transformers 5 už nepodporuje původní:
pipeline("translation")
stejným způsobem jako Transformers 4. Model proto načítej přímo přes:
AutoTokenizer
AutoModelForSeq2SeqLM
nebo použij jiný aktuálně doporučený způsob.
Neomezuj celý projekt na:
transformers < 5
jen kvůli zastaralému API, pokud lze použít aktuální API. Hugging Face aktuálně doporučuje přímé načtení modelu. citeturn591917search0turn591917search10
Překlad dělej po logických segmentech.
Není nutné zachovávat doslovný překlad.
Priorita je:
- význam
- srozumitelná čeština
- přibližně podobná délka jako originál
Například:
Now we're going to take a look at how we can configure the application.
nemusí být přeloženo příliš dlouze.
Preferuj:
Teď se podíváme na nastavení aplikace.
před:
Nyní se podíváme na to, jakým způsobem můžeme nakonfigurovat tuto aplikaci.
To pomůže synchronizaci dabingu.
Czech Text-to-Speech
Jako první lokální TTS engine použij Piper.
Piper má český hlas:
cs_CZ-jirka-medium
Český hlas jirka je dostupný ve variantách low a medium. Preferuj medium. citeturn237722search3
Model a jeho konfiguraci ukládej například do:
models/piper/
Například:
models/
└── piper/
├── cs_CZ-jirka-medium.onnx
└── cs_CZ-jirka-medium.onnx.json
Pokud bude aktuální Piper projekt nebo způsob instalace jiný než starší rhasspy/piper, ověř aktuálně podporovanou implementaci a použij ji.
TTS vrstvu navrhni modulárně.
Například:
class TTSBackend:
def synthesize(self, text: str, output_file: Path) -> None:
...
A konkrétní implementace:
class PiperTTS(TTSBackend):
...
Důvod je možnost později snadno vyměnit Piper za kvalitnější český TTS engine.
Zachování původního zvuku
Výsledné video nemá automaticky přijít o všechny původní zvuky.
Tutorial může obsahovat:
- kliknutí myší
- systémové zvuky
- hudbu
- jiné zvukové efekty
Proto vytvoř dvě možnosti.
Výchozí:
původní audio + český dabing
Původní audio ale silně ztlum.
Například výchozí:
original-volume = 0.10
Český dabing:
dub-volume = 1.0
CLI:
python translate_video.py tutorial.mp4
ekvivalent:
python translate_video.py tutorial.mp4 \
--original-volume 0.10
Umožni:
--original-volume 0
pro úplné odstranění původního zvuku.
Synchronizace dabingu
Toto je důležitá část projektu.
Každý Whisper segment má:
start
end
Například:
start = 10.0
end = 14.0
Má tedy prostor:
4 sekundy
České TTS ale může mít například:
5.2 sekundy
Program musí:
- vytvořit české TTS
- zjistit jeho skutečnou délku
- porovnat ji s dostupným časovým oknem
- případně české audio zrychlit
- vložit ho na správnou pozici
Omezení rychlosti
Nedělej extrémně zrychlený nepřirozený hlas.
Výchozí maximální zrychlení například:
1.30x
CLI:
--max-speed 1.30
Pokud překlad ani při 1.30x nevejde do segmentu:
- zkus zkrátit překlad
- pokud to není možné, dovol mírné překrytí do následující mezery
- jako poslední možnost toleruj přesah
Program nesmí kvůli jednomu dlouhému segmentu spadnout.
Mezery mezi větami
Nesnaž se mechanicky nutit každý Whisper segment přesně do jeho end.
Pokud například:
segment 1: 10.0 → 14.0
segment 2: 15.5 → 20.0
existuje mezi nimi:
1.5 sekundy
Český dabing prvního segmentu může část této mezery využít. přesně, pokud je jednodušší řešení lepší.
Priorita je čitelný a udržovatelný kód.
Architektura
Odděl jednotlivé kroky.
Například:
extract_audio()
transcribe_audio()
merge_segments()
translate_segments()
synthesize_segments()
build_dub_track()
mix_tracks()
create_output_video()
Každý krok musí být samostatně testovatelný.
FFmpeg
FFmpeg spouštěj přes:
subprocess.run(...)
Nepoužívej shell stringy.
Preferuj:
subprocess.run(
[
"ffmpeg",
"-i",
str(input_file),
...
],
check=True,
)
kvůli cestám obsahujícím mezery.
Projektová cesta totiž obsahuje:
Macintosh HD
Proto musí aplikace správně fungovat s cestami obsahujícími mezery.
Error handling
Používej vlastní srozumitelné chyby.
Například:
class Mp4TranslateError(Exception):
pass
Chyba jednoho video souboru v batch režimu nesmí automaticky ukončit zpracování všech ostatních.
Na konci batch režimu vypiš:
Completed: 8
Failed: 1
Skipped: 2
Zachování původního souboru
Nikdy neupravuj zdrojové MP4.
Vždy vytvoř nový soubor.
Například:
tutorial.mp4
tutorial_CZ.mp4
Metadata
Pokud je to jednoduché, zachovej základní metadata původního MP4.
Není to ale priorita první verze.
Titulky
I když primárním cílem je český dabing, vytvoř při zpracování také český:
SRT
Například:
tutorial_CZ.srt
Titulky budou užitečné pro:
- kontrolu překladu
- debugging
- případné použití samostatně
Přidej možnost:
--no-srt
Kvalita překladu
Technické tutorialy často obsahují názvy produktů, příkazů a UI prvků.
Nepřekládej automaticky například:
Visual Studio Code
Docker
SQL Server
File
Settings
Open
Save
PowerShell
Python
Git
GitHub
pokud překlad nedává v daném kontextu smysl.
Příkazy typu:
pip install
docker compose up
SELECT *
nesmí překladač poškodit.
Před překladem proto zvaž ochranu:
- příkazů
- cest
- URL
- názvů souborů
- názvů produktů
Například placeholdery:
__TERM_001__
po překladu nahraď původní hodnotou.
Tuto funkcionalitu není nutné udělat dokonale v první verzi, ale architektura ji má umožnit.
První verze
Nesnaž se nejdříve vytvořit dokonalý systém.
Postup implementace:
Milestone 1
Zprovozni:
MP4
→ audio
→ Whisper
→ JSON
Ověř segmenty a časování.
Milestone 2
Přidej:
JSON
→ EN/CZ translation
Milestone 3
Přidej:
CZ text
→ Piper TTS
Milestone 4
Přidej časovou synchronizaci.
Milestone 5
Vytvoř český audio track.
Milestone 6
Smíchej audio a vytvoř MP4.
Milestone 7
Přidej batch režim a SRT.
Po každém milestone proveď skutečný krátký test.
Testovací workflow
Pro vývoj nepoužívej vždy celé 20minutové video.
Pomocí FFmpeg vytvoř například prvních 60 sekund:
ffmpeg \
-i tutorial.mp4 \
-t 60 \
-c copy \
test_60s.mp4
Na tomto souboru prováděj vývojové testy.
Po úspěchu otestuj celé video.
Výkon
Hardware je Apple Silicon.
Preferuj MLX tam, kde to dává smysl.
Není nutné optimalizovat každou část od začátku.
Tutorial má typicky jen:
5–20 minut
Priorita je:
kvalita > jednoduchost > výkon
ale program by neměl dělat zbytečné opakované inference modelů.
Model překladače načti jednou na celé video.
Stejně tak TTS a Whisper inicializuj pouze jednou, pokud to API umožňuje.
README pro uživatele
Po dokončení implementace tento dokument zachovej, ale doplň na jeho začátek stručnou uživatelskou sekci:
Installation
Usage
Examples
Options
Troubleshooting
Technické zadání níže může zůstat jako:
Development notes
Git
Vytvoř .gitignore.
Minimálně:
.venv/
__pycache__/
*.pyc
.DS_Store
tmp/
models/
*.wav
*.aac
*_CZ.mp4
*_CZ.srt
Zdrojová MP4 automaticky neignoruj, pokud není důvod.
Bezpečnost
Neodstraňuj soubory mimo projektový temporary directory.
Před jakýmkoliv mazáním ověřuj cestu.
Nikdy nepoužívej:
rm -rf
nad cestou vytvořenou přímo ze vstupu uživatele bez validace.
Co má Codex udělat
Po přečtení tohoto README:
- zkontroluj aktuální obsah projektu
- nic existujícího zbytečně nemaž
- zjisti verzi macOS, Pythonu a architekturu CPU
- ověř dostupnost Homebrew a FFmpeg
- vytvoř
.venv, pokud ještě neexistuje - připrav dependencies
- implementuj aplikaci po výše uvedených milestonech
- průběžně aplikaci skutečně spouštěj
- opravuj chyby, které při testech vzniknou
- nepovažuj samotné napsání kódu za dokončení úkolu
Výsledkem má být skutečně spustitelná aplikace.
Definition of Done
Projekt je hotový, když funguje:
source .venv/bin/activate
python translate_video.py test.mp4
a vznikne:
test_CZ.mp4
test_CZ.srt
Výsledné:
test_CZ.mp4
musí:
- mít stejný obraz jako originál
- mít zachovanou přibližně stejnou délku
- obsahovat český dabing
- mít český hlas přibližně synchronizovaný s původním mluvčím
- nemít extrémně zrychlené věty
- neztratit původní audio úplně, pokud
--original-volumenení 0 - být normálně přehratelné v QuickTime/VLC
Poté otestuj alespoň jedno celé tutorial video.
Důležitá poznámka pro Codex
Technologie uvedené v tomto README jsou doporučený výchozí stav, nikoliv absolutní omezení.
Pokud zjistíš, že některý balík je v aktuální době zastaralý, neudržovaný nebo na aktuálním macOS nefunguje, ověř aktuální stav upstream projektu a použij moderní kompatibilní náhradu.
Neměň ale základní požadavek:
lokální EN MP4 → český dabovaný MP4
a preferuj řešení optimalizované pro Apple Silicon.
Před zásadní změnou technologického stacku nejprve zjisti, zda problém skutečně nelze vyřešit v navrženém stacku.