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>
This commit is contained in:
Luna
parent
b6e0df4efd
commit
962a373c6c
1 changed files with 106 additions and 28 deletions
134
FORK_NOTES.md
134
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.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue