Překlad anglického videa do češtiny a vložení TTL čského hlasu jako další zvuková stopa.
  • Python 96.5%
  • Shell 3.5%
Find a file
2026-09-09 01:45:35 +02:00
mp4translate Initial implementation with optional dual audio and embedded Czech subtitles 2026-09-09 01:45:35 +02:00
tests Initial implementation with optional dual audio and embedded Czech subtitles 2026-09-09 01:45:35 +02:00
.gitignore Initial implementation with optional dual audio and embedded Czech subtitles 2026-09-09 01:45:35 +02:00
README.md Initial implementation with optional dual audio and embedded Czech subtitles 2026-09-09 01:45:35 +02:00
requirements.txt Initial implementation with optional dual audio and embedded Czech subtitles 2026-09-09 01:45:35 +02:00
setup.sh Initial implementation with optional dual audio and embedded Czech subtitles 2026-09-09 01:45:35 +02:00
translate_video.py Initial implementation with optional dual audio and embedded Czech subtitles 2026-09-09 01:45:35 +02:00

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. citeturn237722search0turn237722search1turn237722search2

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. citeturn591917search0turn591917search9

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. citeturn591917search0turn591917search10

Překlad dělej po logických segmentech.

Není nutné zachovávat doslovný překlad.

Priorita je:

  1. význam
  2. srozumitelná čeština
  3. 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. citeturn237722search3

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í:

  1. vytvořit české TTS
  2. zjistit jeho skutečnou délku
  3. porovnat ji s dostupným časovým oknem
  4. případně české audio zrychlit
  5. 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:

  1. zkus zkrátit překlad
  2. pokud to není možné, dovol mírné překrytí do následující mezery
  3. 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:

  1. zkontroluj aktuální obsah projektu
  2. nic existujícího zbytečně nemaž
  3. zjisti verzi macOS, Pythonu a architekturu CPU
  4. ověř dostupnost Homebrew a FFmpeg
  5. vytvoř .venv, pokud ještě neexistuje
  6. připrav dependencies
  7. implementuj aplikaci po výše uvedených milestonech
  8. průběžně aplikaci skutečně spouštěj
  9. opravuj chyby, které při testech vzniknou
  10. 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-volume není 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.