devedeng-extended/FORK_NOTES.md

# DeVeDe-NG — Hardsub & Auto-split Fork

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`) 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
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 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 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)** | 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. |

Selecting **Custom** reveals video/audio kbps fields.

## 3. Splitting long projects across discs

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 (upstream
  behaviour), or **Cancel**.

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.

## Reliability

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.