177 lines
6.5 KiB
Markdown
177 lines
6.5 KiB
Markdown
# anime_dub_sync
|
|
|
|
Transfer a dubbed audio track (e.g. German) from a low-quality source file onto a
|
|
high-quality video file, with automatic A/V offset detection and verification.
|
|
|
|
Only use this with sources you legally own. All paths and titles in this repo
|
|
are generic placeholders — do not commit real media filenames, absolute local
|
|
paths, or release-group names.
|
|
|
|
## Requirements
|
|
|
|
System tools (must be on `PATH`):
|
|
|
|
- `ffmpeg` + `ffprobe`
|
|
- `mkvmerge` (from MKVToolNix)
|
|
|
|
Python (>= 3.10):
|
|
|
|
- `opencv-python`, `scipy`, `numpy`, `soundfile`, `tqdn`
|
|
- see `requirements.txt`
|
|
|
|
Install:
|
|
|
|
```bash
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
## Repository layout
|
|
|
|
```text
|
|
main.py # batch + single-episode orchestration
|
|
utils.py # subprocess helper
|
|
audio/
|
|
__init__.py
|
|
audio_utils.py # ffmpeg extraction, concat, shifting, mux helpers
|
|
audio_cross_correlation.py # intro/outro audio offset measurement
|
|
video/
|
|
__init__.py
|
|
video_utils.py # ffprobe wrapper
|
|
scene_change_cross_correlation.py # primary video offset detection
|
|
temporal_cross_correlation.py # alternative/legacy motion-signal method
|
|
mkv/
|
|
__init__.py
|
|
chapter.py # chapter parsing, intro/outro candidate search
|
|
intro_outro.py # final sync verification
|
|
check_intro_outro.py # CLI wrapper for verification
|
|
```
|
|
|
|
## How it works
|
|
|
|
### 1. Video offset detection (`video/`)
|
|
|
|
`video/scene_change_cross_correlation.py:70` — `corelate_videos(vid1, vid2, fps)`:
|
|
|
|
1. `get_scene_change_signal` decodes each video with OpenCV at 160x90 grayscale,
|
|
computes `mean(diff^2)` per frame. Cuts produce large spikes.
|
|
2. `resample_signal` resamples both signals to a common FPS with
|
|
`scipy.signal.resample`.
|
|
3. Both signals are z-normalized, then `scipy.signal.correlate(mode='full')`
|
|
finds the lag with peak correlation.
|
|
4. Lag in samples / FPS = offset in seconds. Positive means `vid1` starts
|
|
after `vid2`.
|
|
|
|
`video/video_utils.py:14` — `probe_video(path)` returns
|
|
`(fps, duration, codec, start_time)` via `ffprobe -show_streams -show_format`.
|
|
|
|
`video/temporal_cross_correlation.py:52` — `find_temporal_offset` is a similar
|
|
motion-signal correlator. It is exported but not used by `main.py`; the active
|
|
path is `corelate_videos`.
|
|
|
|
### 2. Audio splicing (`audio/`)
|
|
|
|
`audio/audio_utils.py`:
|
|
|
|
- `extract_audio_segment_file(video, start, end, out)` — extracts `0:a:0`
|
|
with ffmpeg to stereo AAC `.mka`.
|
|
- `extract_audio_segment_tmp(file, (start, duration) | start, end, stream)` —
|
|
extracts a stream to a temp 44.1 kHz PCM WAV for analysis.
|
|
- `get_audio_duration(file)` — parses `DURATION` tag via ffprobe.
|
|
- `stick_together_audio(left, right, out)` — concatenates with the ffmpeg
|
|
concat demuxer (`-c copy`, no re-encode).
|
|
- `add_silence(file, offset)` — `adelay` (offset > 0, silence at start) or
|
|
`apad` (offset < 0, silence at end), re-encoded to Opus.
|
|
- `replace_with_shifted_mka(mkv, mka, audioline, offset)` — physically shifts
|
|
with `adelay` / `atrim+asetpts`, re-encodes to Opus 160k, replaces the track
|
|
with `mkvmerge`, tags it `ger` / `German (Opus Stereo)`.
|
|
- `get_audio_streams`, `get_track_info`, `shift_audio` — stream enumeration
|
|
and in-place shift helpers.
|
|
|
|
`audio/audio_cross_correlation.py:39` — `get_audio_offset(file1, file2, time)`:
|
|
decodes to mono 44.1 kHz WAV, mean-normalizes, `scipy.signal.correlate`, returns
|
|
lag / sample-rate in seconds.
|
|
|
|
### 3. Intro/outro verification (`mkv/`)
|
|
|
|
`mkv/chapter.py:12` — `get_chapters(file)` lists `(start, duration)` via
|
|
`ffprobe -show_chapters`.
|
|
|
|
`mkv/chapter.py:35` — `get_intro_outro(file, length=90.0)` keeps chapters with
|
|
duration within `[length/2, length*2]`. Expects exactly 2 (intro + outro).
|
|
|
|
`mkv/intro_outro.py:8` — `check_intro_outro_sync(file, length, uncertainty,
|
|
max_offset)`:
|
|
|
|
1. Trims `uncertainty` (default 10%) off each intro/outro edge.
|
|
2. Extracts first and last audio streams for intro and outro.
|
|
3. Audio-correlates intro pair and outro pair.
|
|
4. Returns `(True, mean_offset, last_stream)` if
|
|
`|mean(outro_offsets) - mean(intro_offsets)| < max_offset` (default 0.1 s),
|
|
else `(False, None, None)`.
|
|
|
|
### 4. Orchestration (`main.py`)
|
|
|
|
`main.py:18` — `mux_audio_into_output()` runs `mkvmerge` to add the synced
|
|
`.mka` as a German track.
|
|
|
|
`main.py:37` — `process_one(German_Video, Quality_Video, output_dir,
|
|
offset=None)` runs 9 `tqdm` steps:
|
|
|
|
1. `Probe video` — probe both inputs.
|
|
2. `Compute offset` — `corelate_videos`, or use supplied `offset`.
|
|
3. `Extract pre beginning` — head of quality audio before dub starts
|
|
(skipped if < 0.05 s).
|
|
4. `Extract german audio` — main dubbed segment.
|
|
5. `Extract post end` — tail of quality audio (skipped if < 0.5 s,
|
|
appended only if > `MIN_END_DUR = 2.5` s).
|
|
6. `Combine audio` — concat head + dub + tail; falls back to `add_silence`.
|
|
7. `Mux` — mkvmerge into `output_dir/<quality_stem>.mkv`.
|
|
8. `Cleanup` — removes temp `_original_audio*.mka`.
|
|
9. `Final check` — `check_intro_outro_sync`; sub-frame residual is fixed with
|
|
`replace_with_shifted_mka` if `|offset| > 1/fps`. Failures are renamed to
|
|
`[FAILED]_*.mkv`, chapterless files to `[NO CHAPTER]_*.mkv`.
|
|
|
|
## Usage
|
|
|
|
Single episode (output dir as 3rd arg, else `../output_dir`):
|
|
|
|
```bash
|
|
python main.py <dubbed_source.mkv> <high_quality_source.mkv> [output_dir]
|
|
python main.py dubbed_ep01.mkv quality_ep01.mkv ./output_dir
|
|
```
|
|
|
|
With explicit offset in seconds (bypass video correlation), pass it as 4th
|
|
argument handling inside `process_one` — currently CLI uses auto-detect; edit
|
|
or call the function directly for manual offsets.
|
|
|
|
Batch: edit `main()` in `main.py:225` (`output_dir`, `dubbed_dir`,
|
|
`quality_dir`, episode range), then:
|
|
|
|
```bash
|
|
python main.py
|
|
```
|
|
|
|
Verify an existing file without re-muxing:
|
|
|
|
```bash
|
|
python mkv/check_intro_outro.py ./output_dir/episode.mkv
|
|
```
|
|
|
|
## Configuration
|
|
|
|
- `main.py:16` `MIN_END_DUR = 2.5` — minimum tail length to append.
|
|
- `main.py:14` `DEBUG = False` — enable ffmpeg segment logging.
|
|
- `mkv/intro_outro.py:8` `length=90.0, uncertainty=0.1, max_offset=0.1` —
|
|
expected OP/ED length and tolerances.
|
|
|
|
## Notes and limitations
|
|
|
|
- Needs chapter marks to run the final check; files without them are kept
|
|
with a `[NO CHAPTER]_` prefix and return `False`.
|
|
- Scene-change correlation assumes both files are the same episode cut.
|
|
Different cuts, missing scenes, or very dark/flat video degrade the peak.
|
|
- `utils.py:4` `run(cmd)` prints combined stdout on failure, then re-raises
|
|
`CalledProcessError`.
|
|
- Do not commit `.mkv` / `.mka` media or absolute filesystem paths. Keep
|
|
`output_dir/` and temp audio out of git.
|