diff --git a/FORK_NOTES.md b/FORK_NOTES.md index 297ca6e..ddcef8c 100644 --- a/FORK_NOTES.md +++ b/FORK_NOTES.md @@ -1,18 +1,82 @@ # DeVeDe-NG — Hardsub & Auto-split Fork -This is a fork of [DeVeDe-NG](https://gitlab.com/rastersoft/devedeng) that adds -three things aimed at producing burn-ready NTSC DVDs from arbitrary video files: +This is a fork of [DeVeDe-NG](https://gitlab.com/rastersoft/devedeng) aimed at +producing burn-ready **NTSC DVDs** from arbitrary video files, with three +additions on top of upstream: 1. **Embedded subtitle detection + hardsubbing (burn-in).** 2. **Selectable DVD encode profiles** (Compatibility / High quality / Custom). 3. **Automatic splitting of over-long projects across multiple ISOs / DVD-Rs.** +It also hardens the app itself: a test suite, deadlock-proof subprocess +handling, and clearer error reporting (see *Reliability* below). + The baseline encode is modelled on the known-good script in [`contrib/dvd-safe-converter.sh`](contrib/dvd-safe-converter.sh). +--- + +## Requirements + +**Runtime tools** (must be on `PATH`): + +- `ffmpeg` and `ffprobe` — encoding and media analysis (the default backend). +- `dvdauthor` — builds the DVD-Video structure. +- `mkisofs` *or* `genisoimage` — creates the ISO image. +- `spumux` (part of dvdauthor) — for soft (selectable) subtitles. +- Optional: a player for preview (`vlc`, `mpv`, or `mplayer`) and a burner + (`brasero`, `k3b`, or `xfburn`). + +**Python / GUI:** Python ≥ 3.12, GTK 3, PyGObject (`gi`), and `pycairo`. + +On Debian/Ubuntu: + +```bash +sudo apt install ffmpeg dvdauthor genisoimage \ + python3 python3-gi gir1.2-gtk-3.0 python3-cairo python3-gi-cairo \ + vlc # optional: preview player +``` + +On Arch: + +```bash +sudo pacman -S ffmpeg dvdauthor cdrkit gtk3 python-gobject python-cairo \ + vlc # optional: preview player +``` + +## Install + +```bash +sudo python3 -m pip install . +# if pip refuses on an externally-managed system: +sudo python3 -m pip install --break-system-packages . +``` + +Then launch it from your menu or run `devede_ng`. + +## Run from source (no install) + +Best for trying it out or developing — runs straight from the checkout: + +```bash +PYTHONPATH=src python3 -c "import devedeng.devedeng as d; d.py()" +``` + +## Tests + +```bash +python3 -m pip install --break-system-packages pytest # one-time +python3 -m pytest +``` + +The suite is headless (no display, no encoding) and runs in CI on Codeberg +(`.forgejo/workflows/tests.yml`). + +--- + ## 1. Hardsubbing embedded subtitles -The analyzer (`ffprobe` / `avprobe`) now detects embedded subtitle tracks and +The analyzer (`ffprobe`/`avprobe`) detects embedded subtitle tracks and classifies each as **text** (SubRip/ASS/mov_text/WebVTT) or **image** (PGS/VOBSUB/DVD subtitle). In a movie's *Subtitles* properties page a **"Burn in embedded subtitle"** dropdown lets you pick one track to render @@ -21,46 +85,60 @@ permanently into the picture. - **Text** subs are burned with ffmpeg's `subtitles=` (libass) filter, applied after scaling to the DVD size. - **Image** subs are composited with an `overlay` filtergraph *before* scaling, - so bitmap positioning stays aligned with the source frame. (OCR-to-text is an - optional future enhancement; the default overlays the bitmap directly.) + so bitmap positioning stays aligned with the source frame. (OCR-to-text is a + planned option; today the bitmap is overlaid directly.) Burned-in subtitles are part of the video; the existing *soft* subtitle support (spumux subpicture streams from external files) is unchanged. ## 2. Encode profiles -A project-level **Encode profile** selector (next to the disc-size control, -DVD only): +A project-level **Encode profile** selector sits next to the disc-size control +(DVD only). NTSC DVD audio is AC3 for all profiles (upstream used MP2 for NTSC), +matching the baseline script and maximising player compatibility. | Profile | Video | Audio | Notes | | --- | --- | --- | --- | -| **Compatibility (4500k)** | CBR 4500k | AC3 192k | Old-player safe baseline (~133 min / single-layer disc). | -| **High quality (fill disc)** | VBR, fills disc | AC3 448k | Best quality per disc. | -| **Custom** | user kbps | user kbps | Advanced; clamped to stay within DVD spec. | +| **Compatibility (4500k)** | CBR 4500k | AC3 192k | Old-player-safe baseline (~133 min / single-layer disc). | +| **High quality (fill disc)** | 2-pass VBR, auto | AC3 448k | Picks the **fewest** discs that hold the project, then raises the bitrate (up to ~9000k) to fill each disc. | +| **Custom** | your kbps | your kbps | Advanced; clamped to stay within DVD spec. | -NTSC DVD audio is AC3 for all profiles (the upstream default was MP2 for NTSC), -matching the baseline script and maximising player compatibility. +Selecting **Custom** reveals video/audio kbps fields. ## 3. Splitting long projects across discs -Usable disc capacity is taken from the selected disc size (with the existing -~10% safety margin). When a project does not fit on one disc at the chosen -quality, you are asked whether to: +Usable disc capacity comes from the selected disc size (with the existing ~10% +safety margin). When a project does not fit on one disc at the chosen quality, +you are asked whether to: - **Split into N discs** — keep the quality and author one DVD/ISO per disc - (`name-disc1.iso`, `name-disc2.iso`, …), **or** -- **Reduce bitrate** — squeeze everything onto a single disc (the original - behaviour). + (`name-disc1.iso`, `name-disc2.iso`, …), or +- **Reduce bitrate** — squeeze everything onto a single disc (upstream + behaviour), or **Cancel**. -Multiple titles are distributed across discs whole. A single movie that is -itself larger than one disc is split by time at the **chapter boundary nearest** -each disc's capacity (falling back to an even time cut when the movie has no -chapters). Split discs are authored without a menu — each disc plays its -segment(s) directly. +Multiple titles are distributed across discs whole. A single movie larger than +one disc is split by time at the **chapter boundary nearest** each disc's +capacity (falling back to an even time cut when it has no chapters); each +segment's chapter markers stay inside the segment. If the project has a menu +enabled, **each split disc gets its own menu** listing that disc's titles; +otherwise each disc auto-plays. -### Limitations +## Reliability -- Split discs have no DVD menu. -- Burning is per-disc: the app produces the ISOs; burn each in turn. -- Image-subtitle burn-in is supported by the ffmpeg backend; the avconv backend - handles text subtitles only. +This fork also reworks the app's process handling and error reporting: + +- **Deadlock-proof subprocesses.** Child output is drained by background reader + threads, so a long encode can't be wedged by a stalled/closed GUI (the + encoders even keep running if the editor/terminal that launched the app dies). +- **Clear errors.** A failed job leads with the step that failed, its command, + and the last lines of its output — with the full log still available. +- **Test suite + CI** guard the split planner, bitrate math, generated ffmpeg + commands, subtitle detection, and the subprocess I/O. + +## Known limitations + +- Burning multiple discs is done one at a time: the app produces the ISOs; burn + each in turn. +- Image-subtitle burn-in is supported by the ffmpeg backend; the legacy avconv + backend handles text subtitles only. +- See [ROADMAP.md](ROADMAP.md) for what's planned next.