1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
//! CEA-608/708 -> WebVTT cue conversion (issue #568).
//!
//! Cite: `specs/rules/webvtt-rules.md` (curated W3C WebVTT §4 cue syntax +
//! RFC 8216 §3.5 `X-TIMESTAMP-MAP`), and CTA-608-E / CTA-708-E for the
//! caption semantics (decode owned entirely by the `cc-data` crate, feature
//! `cc-data`).
//!
//! This module is split in two independent halves:
//!
//! - [`Cue`] + [`write_document`] / [`write_segment`] (always available):
//! pure WebVTT serialization from an already-extracted cue list. No
//! dependency on `cc-data`.
//! - [`Cea608CueExtractor`] / [`Cea708CueExtractor`] (feature `cc-data`):
//! turn a decoded CEA-608 CC1 channel / CEA-708 service into a [`Cue`]
//! sequence by feeding one access unit's `cc_data()` triplets at a time,
//! tagged with that access unit's 33-bit PTS.
//! - [`TeletextCueExtractor`] (feature `teletext`): turns an EBU Teletext
//! (ETSI EN 300 706) subtitle page into a [`Cue`] sequence by feeding one
//! access unit's [`dvb_vbi::TeletextDataField`]s at a time. Unlike the CEA
//! extractors, the protocol decode (Hamming-8/4 FEC, character sets, page
//! composition) is NOT owned by the carriage crate (`dvb-vbi` is
//! deliberately carriage-only — see its module docs) — it lives in
//! [`teletext`] instead. See that module's docs for the full design.
//!
//! # Cue-boundary detection (the key design decision)
//!
//! `cc-data`'s decoders expose only *state* (`channel_text()` /
//! `service_text()`), not a "just committed" event. This module derives cue
//! boundaries by **diffing that displayed text before and after each fed
//! frame**:
//!
//! - **Pop-on**: `channel_text()`/`screen()` reflect only the *displayed*
//! memory; while composing a caption (RCL -> PAC -> characters) writes go
//! to the *non-displayed* buffer and produce no diff. The buffers swap only
//! on EOC, so a diff-detected boundary is *exactly* the EOC commit event,
//! and the next diff (typically an EDM erase, or the next EOC) is exactly
//! the "next erase/replace" the spec notes describe.
//! - **Roll-up** / **paint-on**: characters are written directly to the
//! displayed buffer, so a diff can fire on every visible change (finer
//! grained than "one cue per committed row"). In practice a roll-up row is
//! usually written in one batch before the next control code, so real
//! streams still produce one boundary per row; pathologically slow
//! per-character delivery would fragment further. Documented as a known
//! simplification (see `webvtt-rules.md`'s 608/708 mapping notes).
//!
//! # Documented losses (round-trip is NOT claimed; conversion is lossy)
//!
//! - **Placement**: no `line`/`position`/`align` cue settings are emitted —
//! `webvtt-rules.md` allows omitting them ("otherwise omit (player
//! defaults)"); row/column/window-anchor information from 608 PACs / 708
//! window geometry is dropped.
//! - **Styling**: italics/underline/colour (608 mid-row/PAC attributes, 708
//! pen attributes) are not carried into the payload as `<i>`/`<u>`/`<c>`
//! tags; only plain decoded text is emitted.
//! - **708 scope**: only a single service's window text (`service_text`) is
//! read; multi-window overlap ordering beyond priority, and non-service-1
//! services, are the caller's choice of `service_number` but are not
//! auto-merged across services.
//! - **Roll-up granularity**: see cue-boundary detection above.
pub use Cue;
pub use TeletextCueExtractor;
pub use ;
pub use ;