mirror of
https://github.com/storytold/filmcraft.git
synced 2026-10-24 10:10:05 -06:00
aiongg
0a881266c8
* Tests: one integration-test binary per crate Each crate with several tests/*.rs files keeps them as modules of tests/it/, so cargo links one test executable per crate instead of one per file. Files that change process-wide state or time a workload stay binaries of their own. * Profiles: line tables for workspace crates, no debug info for dependencies * Windows ARM64: nightly and on release pushes instead of every push to main * xtask ci: clippy and tests in the dev profile The release profile's thin LTO and single codegen unit made linking the test binaries take most of the gate. The codec and audio crates stay at opt-level 3 in the dev profile, so their tests run at release speed. * xtask ci: nextest, doctests, no examples, one wasm check Tests run with cargo nextest when it is installed (cargo test otherwise) and build with --lib --bins --tests, so examples aren't linked; doctests run separately. The wasm check keeps going past the first failing crate. VP8 fixture generation locks across processes, since nextest runs each test in its own. * VP9 synthetic fixtures: write aside and rename A test in another process could read a fixture ffmpeg was still writing. * Fuzz tests: a third of each sweep by default, all of it with FILMCRAFT_FUZZ_ITERS Every seed, mutation kind and thread count still runs. Header bytes each get one overwrite value and two bit flips in rotation, so every value and bit index still occurs across the region. FILMCRAFT_FUZZ_ITERS=N runs the whole sweep plus N random rounds per seed, as before. * Platform fallback tests: one failure point per hybrid path The failure-anywhere test injected a failure at four points around every restart point; the hybrid's paths differ only in the first GOP, around the second and last restart points, at the end and never. The replay test needs the first two GOPs. * Export tests: shorter ranges with the same checks The bitrate test measures 0.5–1.5 s, where each preset reaches its own target (on 0–3 s the simple demo left two presets at the same rate). The every-preset test exports three frames per preset. * Audio tests: effects in parallel, a table-driven FFT for the Opus quality metric The extreme-settings test keeps both settings and the 40 s tail for every effect, one thread each. The Opus quality metric's FFT builds its twiddles once and allocates nothing per transform (same algorithm and summation order). * CI: dev-profile gate with nextest xtask ci no longer builds with --release, so the release-profile overrides go; nextest is installed for the test step. * CI: apt packages through the cached install-apt-packages action * Review fixes: fuzz tests with a panic hook in their own binaries, loud fixture lock The fuzz tests of av1, h264, hevc, mpeg2v, vp8 and vp9 count panics through a process-wide hook, so a panic in another test of the same process would fail them; they are binaries of their own again. The VP8 fixture lock fails the test instead of skipping it silently, and the full-sweep doc comments say how many truncation points the full run samples. * Fuzz tests: rotate the default subset per run (FILMCRAFT_FUZZ_SEED replays one) * platform tests: decode-switch tests in their own binaries, one NVENC lock
94 lines
7.4 KiB
Markdown
94 lines
7.4 KiB
Markdown
# filmcraft-captions
|
||
|
||
Caption files and caption burn-in for FilmCraft (layer L2: depends on `filmcraft-time`,
|
||
`filmcraft-color`, `filmcraft-project`, `filmcraft-text` and `roxmltree` for TTML).
|
||
|
||
The caption *model* (caption tracks in a sequence, captions, track style) lives in
|
||
`filmcraft-project` (`caption.rs`) because it is part of the `.fcproj` document. This crate reads
|
||
and writes caption files, converts them to and from caption tracks, and draws captions.
|
||
|
||
## Formats
|
||
|
||
| Format | Read | Write | Notes |
|
||
|---|---|---|---|
|
||
| SubRip `.srt` | yes | yes | BOM, UTF-16, Windows-1252 fallback, CRLF/CR, missing or wrong indexes, `,` or `.` milliseconds, 1–9 fraction digits, missing hours, SSA coordinates, cues not separated by blank lines. Inline tags are kept as text. |
|
||
| WebVTT `.vtt` | yes | yes | Cue identifiers, cue settings (verbatim), a leading `<v Speaker>` voice span (as the caption's speaker) and STYLE / REGION / NOTE blocks are kept. A missing `WEBVTT` signature is tolerated. |
|
||
| Scenarist SCC `.scc` | yes | yes | CEA-608 at 29.97 fps, drop-frame or not. Reads pop-on, roll-up and paint-on (channel 1); writes pop-on. |
|
||
| MacCaption MCC `.mcc` | yes | yes | One SMPTE ST 334-2 caption distribution packet (CDP) per frame in MacCaption's hex text with letter abbreviations. Writes 29.97 fps (`30DF` / `30`) with CEA-608 field 1 (the SCC schedule) **and** CEA-708 service 1 (two-window pop-on emulation). Reads CEA-608 field 1 when present, else CEA-708 service 1; time code rates 30DF, 30, 60DF, 60, 25, 24, 50. |
|
||
| EBU STL `.stl` | yes | yes | EBU Tech 3264-E: GSI block + 128-byte TTI blocks, `STL25.01` (25 fps) or `STL30.01` (read/written as 29.97 fps, non-drop labels), ISO/IEC 6937 Latin text (accents as diacritic + letter), italics / underline codes as `<i>` / `<u>`, extension blocks for long subtitles, start-of-programme (TCP) subtracted. |
|
||
| TTML `.ttml` (IMSC1) | yes | yes | Writes the IMSC1 Text profile (TTML2 namespaces): `<p>` per cue, `<br/>`, styled `<span>`s for `<i>` / `<b>` / `<u>`, `ttm:agent` speakers, exact frame times (`123f`) at the sequence rate. Reads any TTML (TTML1, TTML2, the 2006 `ttaf1` drafts): clock / frame / offset / tick times, `dur`, nested time containers (`body` / `div` begins offset and ends clip their contents; `seq` containers are read as `par` with a warning), timed spans, referenced styles. |
|
||
| DFXP `.dfxp` | yes | yes | TTML1 with the DFXP presentation profile; clock times in milliseconds (frame-exact after `snap_to_frames`). |
|
||
|
||
All cue times are exact `Tick`s. Milliseconds convert exactly (1 ms = 254 016 000 ticks); SCC
|
||
frames map through `FrameRate::FPS_29_97`. `Document::snap_to_frames` snaps cues to a sequence's
|
||
frame grid (the engine does this on import) and removes overlaps.
|
||
|
||
### TTML tick timing
|
||
|
||
When `ttp:tickRate` is omitted and `ttp:frameRate` is present, tick offsets use the effective
|
||
frame rate (`frameRate` times `frameRateMultiplier`) times `subFrameRate`. The rate stays
|
||
rational, so a 30-tick offset at 30 times 1000/1001 fps is exactly 1.001 seconds. An explicit
|
||
`tickRate` takes precedence; without `frameRate`, the default is one tick per second.
|
||
This follows [W3C TTML1, third edition (2018), §6.2.10](https://www.w3.org/TR/2018/REC-ttml1-20181108/#parameter-attribute-tickRate).
|
||
|
||
### TTML speaker metadata
|
||
|
||
TTML and DFXP exports define each distinct speaker label once in the document head and refer to
|
||
it with a stable, unique `ttm:agent` ID. Names are XML-escaped full-name text with preserved
|
||
whitespace; punctuation, Unicode and literal underscores survive a round trip. Agent type is
|
||
`other` because a caption's speaker label does not say whether it denotes a person or a group.
|
||
|
||
On import, agent definitions directly under `head` or `head/metadata` resolve paragraph and timed
|
||
span speakers. Speaker metadata uses the standard TTML namespace or the April and October 2006
|
||
TTaf1 draft namespaces. Agent IDs use `xml:id`, except in the April draft, which uses unqualified
|
||
`id`. Agent definitions from unrelated application metadata are ignored. Recognized `ttm:agent`
|
||
attributes take precedence over the legacy local-name `agent` fallback. A full name is preferred,
|
||
otherwise the first nonempty name (or an explicitly empty name) is used. Multiple agent references become one display label, joined with `, ` in
|
||
reference order; the project does not retain the individual agent identities. Older FilmCraft
|
||
files without agent definitions remain readable through the previous underscore-to-space
|
||
fallback. Other agent metadata, including actor relationships, is not retained.
|
||
|
||
This mapping follows [W3C TTML1, third edition (2018), §§12.1.5–12.2.1](https://www.w3.org/TR/2018/REC-ttml1-20181108/#metadata-vocabulary-agent).
|
||
The [April 2006 TTaf1 draft, §§7.2.1 and 12.1.5–12.2.1](https://www.w3.org/TR/2006/WD-ttaf1-dfxp-20060427/)
|
||
defines its earlier metadata namespace and agent ID form.
|
||
|
||
### SCC writer
|
||
|
||
Each caption is sent as a pop-on load (RCL, ENM, then per row a preamble address code and tab
|
||
offset for centring, then text; control codes doubled) into non-displayed memory, followed by End
|
||
Of Caption exactly on the caption's first frame. The load is placed in the latest run of free
|
||
frames before the caption, so back-to-back captions load while the previous one is on screen. An
|
||
Erase Displayed Memory clears the caption at its out point unless the next caption replaces it.
|
||
Text is wrapped at 32 columns, bottom-aligned (last row 15) and centred. Characters come from the
|
||
608 basic, special and extended sets (extended characters are preceded by a basic fallback
|
||
character, as the standard requires); others are dropped. If there is no room to load a caption
|
||
before its in point (for example a caption at 00:00:00:00), it appears as soon as it is loaded.
|
||
|
||
## Burn-in
|
||
|
||
`burn::render_caption` lays out a caption with the track style (font size relative to a 1080-line
|
||
frame, colour, background box, outline, alignment, top/middle/bottom anchor and margin; WebVTT
|
||
`line:N%` and `align:` settings override them), wraps lines to 90% of the frame width and
|
||
rasterises it to a small premultiplied linear-light RGBA overlay. `filmcraft-render` composites the
|
||
overlays of visible caption tracks over the finished frame (Program monitor and export burn-in).
|
||
|
||
Text is set in **Inter SemiBold** (`assets/fonts/Inter-SemiBold.ttf`, SIL OFL 1.1, attributed in
|
||
`ATTRIBUTION.md`) by the `filmcraft-text` engine: shaped with kerning and ligatures, bidi-ordered,
|
||
and drawn from its sub-pixel positioned glyph cache.
|
||
|
||
Specifications used: SMPTE ST 334-2 (CDP structure), CEA-608 / CEA-708 (public descriptions of
|
||
the caption commands), the MacCaption MCC format description (line syntax and abbreviations),
|
||
EBU Tech 3264-E (1991), ISO/IEC 6937, W3C TTML1 (2nd ed.), TTML2 and IMSC 1.1. No other
|
||
implementation's code was consulted.
|
||
|
||
## Tests
|
||
|
||
- Unit tests per module (timestamps, decoding, sloppy SRT, WebVTT blocks and voices, CEA-608
|
||
tables, PAC round trips, known SCC pop-on and roll-up streams, layout).
|
||
- `tests/it/roundtrip.rs`: property tests — SRT (also with BOM + CRLF), WebVTT (ids, speakers,
|
||
settings, STYLE blocks), SCC and MCC (drop-frame and non-drop, gaps and back-to-back captions;
|
||
MCC also through CEA-708 alone), EBU STL (25 and 29.97 fps, accents, extension blocks), TTML
|
||
(23.976 / 25 / 29.97 / 59.94, ids, speakers) round-trip frame-exactly; DFXP round-trips after
|
||
snapping to frames; readers never panic on random bytes (also a valid STL header followed by
|
||
random blocks, and random MCC lines); SRT → VTT → SCC keeps text and frames.
|