Update FORK_NOTES: accurate features + clear setup instructions

Add a Requirements/Install/Run-from-source/Tests section (runtime tools,
Debian & Arch package lists, pip install, source-tree launch, pytest).
Correct the feature descriptions to match the code: High profile is
automatic 2-pass VBR (fewest discs, then fill); split discs now get a
per-disc menu when the project menu is enabled; add a Reliability section
covering the deadlock-proof I/O, error reporting, and test suite.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

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
+This is a fork of [DeVeDe-NG](https://gitlab.com/rastersoft/devedeng) aimed at
-three things aimed at producing burn-ready NTSC DVDs from arbitrary video files:
+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
+  so bitmap positioning stays aligned with the source frame. (OCR-to-text is a
-  optional future enhancement; the default overlays the bitmap directly.)
+  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,
+A project-level **Encode profile** selector sits next to the disc-size control
-DVD only):
+(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). |
+| **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. |
+| **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** | user kbps | user kbps | Advanced; clamped to stay within DVD spec. |
+| **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),
+Selecting **Custom** reveals video/audio kbps fields.
-matching the baseline script and maximising player compatibility.
 
 ## 3. Splitting long projects across discs
 
-Usable disc capacity is taken from the selected disc size (with the existing
+Usable disc capacity comes from the selected disc size (with the existing ~10%
-~10% safety margin). When a project does not fit on one disc at the chosen
+safety margin). When a project does not fit on one disc at the chosen quality,
-quality, you are asked whether to:
+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**
+  (`name-disc1.iso`, `name-disc2.iso`, …), or
-- **Reduce bitrate** — squeeze everything onto a single disc (the original
+- **Reduce bitrate** — squeeze everything onto a single disc (upstream
-  behaviour).
+  behaviour), or **Cancel**.
 
-Multiple titles are distributed across discs whole. A single movie that is
+Multiple titles are distributed across discs whole. A single movie larger than
-itself larger than one disc is split by time at the **chapter boundary nearest**
+one disc is split by time at the **chapter boundary nearest** each disc's
-each disc's capacity (falling back to an even time cut when the movie has no
+capacity (falling back to an even time cut when it has no chapters); each
-chapters). Split discs are authored without a menu — each disc plays its
+segment's chapter markers stay inside the segment. If the project has a menu
-segment(s) directly.
+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.
+This fork also reworks the app's process handling and error reporting:
-- 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
+- **Deadlock-proof subprocesses.** Child output is drained by background reader
-  handles text subtitles only.
+  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.