tellur-core 0.3.0

Core component model for tellur: vector/raster/timeline components, layout, easing, and events
Documentation 
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
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101

//! Channel / output types: audio buffers, subtitle cues, and the
//! [`Arrangement`] tree the live UI draws.

// ── Channels / output types (`.sketch/01` A.7) ──────────────────────────────

/// Interleaved f32 samples + rate. A minimal skeleton; the encoder fixes one
/// output rate + channel layout and leaves resample into it (`.sketch/01` A.7).
#[derive(Debug, Clone, Default, PartialEq)]
pub struct AudioBuffer {
    /// Interleaved f32 PCM samples.
    pub samples: Vec<f32>,
    /// Sample rate in Hz.
    pub rate: u32,
    /// Number of interleaved channels.
    pub channels: u16,
}

impl AudioBuffer {
    /// An empty buffer at the given rate / channel layout.
    pub fn empty(rate: u32, channels: u16) -> Self {
        Self {
            samples: Vec::new(),
            rate,
            channels,
        }
    }
}

/// One subtitle interval, absolute on the timeline (after [`cues`](super::TimelineComponent::cues)).
#[derive(Debug, Clone, PartialEq)]
pub struct Cue {
    pub start: f64,
    pub end: f64,
    pub text: String,
}

/// One resolved [`Event`](super::Event) marker on a node: the absolute time it fires, plus the
/// event's optional display name (from [`Event::named`](super::Event::named)) so the live UI can
/// label the marker. The name is owned (`String`) so the arrangement is a
/// self-contained, serializable snapshot.
#[derive(Debug, Clone, PartialEq)]
pub struct TriggerMark {
    pub time: f64,
    pub name: Option<String>,
}

/// The CALL-SITE source location of a node: the `file:line` of the `.child(...)`
/// call that placed the component into its container. Surfaced so the live UI
/// can jump a clicked node back to its authoring line. Owned (`String`) so the
/// arrangement is a self-contained, serializable snapshot.
#[derive(Debug, Clone, PartialEq)]
pub struct SourceLoc {
    pub file: String,
    pub line: u32,
}

/// What the live UI draws — the resolved arrangement of a node and its
/// children. Built by walking the RESOLVED tree (`.sketch/01` A.7 / B.4).
///
/// `trim` carries the range selected by the outermost generic trim wrapper on
/// this node's immediate input clock. It is operation metadata, not necessarily
/// a media-file source range: ordered wrappers allow trimming a placement or a
/// container too. `triggers` surfaces where [`Event`](super::Event)s fire (each
/// a [`TriggerMark`] carrying the time and the event's optional name); `source`
/// is the `.child(...)` call site that placed the node (see [`SourceLoc`]).
#[derive(Debug, Clone, PartialEq)]
pub struct Arrangement {
    pub kind: NodeKind,
    pub label: String,
    /// Human-readable DISPLAY NAME for a `#[component(...)]` node, distinct from
    /// [`label`](Self::label) (which carries body-specific content such as a
    /// caption's text or a clip's source path). Auto-derived from the component's
    /// PascalCase name, or set from an explicit `name = "..."` template; `None`
    /// for nodes that have no enclosing named component.
    pub name: Option<String>,
    /// The `.child(...)` CALL SITE that placed this node, captured by the
    /// generated container setter via `#[track_caller]`; `None` for the root and
    /// for nodes built outside a tracked setter.
    pub source: Option<SourceLoc>,
    pub start: f64,
    pub end: f64,
    pub trim: Option<(f64, f64)>,
    pub triggers: Vec<TriggerMark>,
    pub children: Vec<Arrangement>,
}

/// The kind of node the live UI renders.
///
/// The display side collapses to three TRACK kinds — `Video` (映像: every
/// rasterized/timeless visual, including backdrops, captions, and reveals),
/// `Audio` (音声), and `Subtitle` (字幕) — plus the two structural containers
/// (`Timeline` / `Sequence`). There is intentionally no separate caption kind:
/// a styled `Text` telop is a visual and lives on the video track.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum NodeKind {
    Video,
    Audio,
    Subtitle,
    Timeline,
    Sequence,
}