Skip to main content

alpha2_model/
timeline.rs

1use crate::{
2    AudioProperties, Captions, ClipBlendMode, ClipComposition, ClipEffect, ClipId, Easing, Matte,
3    MediaKind, ShapeMask, TimeMap, TrackAudio, TrackId, VisualProperties,
4};
5use alpha2_media::SourceId;
6use alpha2_time::TimeRange;
7use serde::{Deserialize, Serialize};
8
9/// Timeline tracks ordered from back to front for visual tracks.
10#[derive(Clone, Debug, Default, Deserialize, PartialEq, Serialize)]
11#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
12#[serde(deny_unknown_fields)]
13pub struct Timeline {
14    /// Tracks in composition order.
15    #[serde(deserialize_with = "crate::bounded::seq::<_, _, { crate::MAX_TRACKS }>")]
16    #[cfg_attr(feature = "schema", schemars(length(max = crate::MAX_TRACKS)))]
17    pub tracks: Vec<Track>,
18}
19
20impl Timeline {
21    /// The smallest interval holding every clip and caption cue. `None` for a timeline that shows
22    /// nothing. A whole-project export covers `Project::default_export_range` instead.
23    #[must_use]
24    pub fn extent(&self) -> Option<TimeRange> {
25        let mut ranges = self.tracks.iter().flat_map(|track| {
26            track.clips.iter().map(|clip| clip.timeline_range).chain(
27                track
28                    .captions
29                    .iter()
30                    .flat_map(|captions| captions.cues.iter().map(|cue| cue.timeline_range)),
31            )
32        });
33        let first = ranges.next()?;
34        let (start, end) = ranges.fold((first.start(), first.end()), |(start, end), range| {
35            (start.min(range.start()), end.max(range.end()))
36        });
37        TimeRange::new(start, end).ok()
38    }
39
40    /// Whether any track solos its bus, which silences every bus that does not
41    /// ([`TrackAudio::is_silenced`]).
42    #[must_use]
43    pub fn any_solo(&self) -> bool {
44        self.tracks.iter().any(|track| track.audio.solo)
45    }
46
47    /// The clips that are another clip's matte. Such a clip is drawn only into the mattes that
48    /// name it and never composited itself.
49    #[must_use]
50    pub fn matte_sources(&self) -> std::collections::HashSet<&ClipId> {
51        self.tracks
52            .iter()
53            .flat_map(|track| &track.clips)
54            .filter_map(|clip| clip.matte.as_ref().map(|matte| &matte.source))
55            .collect()
56    }
57}
58
59/// A homogeneous visual or audio timeline lane.
60#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
61#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
62#[serde(deny_unknown_fields)]
63#[non_exhaustive]
64pub struct Track {
65    /// Stable track identity.
66    pub id: TrackId,
67    /// User-visible track name.
68    pub name: String,
69    /// Controls source compatibility and evaluation behavior.
70    pub kind: TrackKind,
71    /// Clips on this track, in authoring order; evaluation sorts by time. A caption track has
72    /// none.
73    #[serde(default)]
74    #[serde(deserialize_with = "crate::bounded::seq::<_, _, { crate::MAX_CLIPS_PER_TRACK }>")]
75    #[cfg_attr(feature = "schema", schemars(length(max = crate::MAX_CLIPS_PER_TRACK)))]
76    pub clips: Vec<Clip>,
77    /// Explicit transitions between overlapping clips on this track.
78    #[serde(default)]
79    #[serde(
80        deserialize_with = "crate::bounded::seq::<_, _, { crate::MAX_TRANSITIONS_PER_TRACK }>"
81    )]
82    #[cfg_attr(feature = "schema", schemars(length(max = crate::MAX_TRANSITIONS_PER_TRACK)))]
83    pub transitions: Vec<ClipTransition>,
84    /// Bus controls applied to this track's mixed audio.
85    #[serde(default)]
86    pub audio: TrackAudio,
87    /// The cues and style of a caption track; present exactly for that kind.
88    #[serde(default)]
89    pub captions: Option<Captions>,
90}
91
92impl Track {
93    /// Creates an empty track with default bus controls.
94    #[must_use]
95    pub fn new(id: TrackId, name: impl Into<String>, kind: TrackKind) -> Self {
96        Self {
97            id,
98            name: name.into(),
99            kind,
100            clips: Vec::new(),
101            transitions: Vec::new(),
102            audio: TrackAudio::default(),
103            captions: (kind == TrackKind::Caption).then(Captions::default),
104        }
105    }
106}
107
108/// The media domain accepted by a track.
109#[derive(Copy, Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
110#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
111#[serde(rename_all = "snake_case")]
112#[non_exhaustive]
113pub enum TrackKind {
114    /// A composited visual track.
115    Video,
116    /// A mixed audio track.
117    Audio,
118    /// Timed text, drawn over the tracks before it and under the ones after.
119    Caption,
120}
121
122impl TrackKind {
123    pub(crate) const fn accepts(self, source: MediaKind) -> bool {
124        matches!(
125            (self, source),
126            (
127                Self::Video,
128                MediaKind::Video | MediaKind::Image | MediaKind::Generated | MediaKind::Composition
129            ) | (Self::Audio, MediaKind::Audio)
130        )
131    }
132}
133
134/// A reference to a source over independent timeline and source ranges.
135#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
136#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
137#[serde(deny_unknown_fields)]
138#[non_exhaustive]
139pub struct Clip {
140    /// Stable clip identity.
141    pub id: ClipId,
142    /// Source consumed by this clip.
143    pub source_id: SourceId,
144    /// Destination interval on the project timeline.
145    pub timeline_range: TimeRange,
146    /// Interval read from the source timeline.
147    pub source_range: TimeRange,
148    /// Resolution-independent visual presentation controls.
149    #[serde(default)]
150    pub visual: VisualProperties,
151    /// The composition graph that builds the clip's picture from its source, with the clip's
152    /// time mapping onto it. Without one the clip shows its source as is. Visual clips only.
153    #[serde(default)]
154    pub composition: Option<ClipComposition>,
155    /// Artistic operation used when this clip is composited over earlier layers.
156    #[serde(default)]
157    pub blend_mode: ClipBlendMode,
158    /// Shapes that limit where the clip is visible, applied in order after its composition and
159    /// before its transform. At most [`crate::MAX_CLIP_MASKS`]; visual clips only.
160    #[serde(default)]
161    #[serde(deserialize_with = "crate::bounded::seq::<_, _, { crate::MAX_CLIP_MASKS }>")]
162    #[cfg_attr(feature = "schema", schemars(length(max = crate::MAX_CLIP_MASKS)))]
163    pub masks: Vec<ShapeMask>,
164    /// Another visual clip whose picture sets where this clip is visible.
165    #[serde(default)]
166    pub matte: Option<Matte>,
167    /// How timeline time maps onto the source range.
168    #[serde(default)]
169    pub time_map: TimeMap,
170    /// Presentation controls applied to this clip's audio.
171    #[serde(default)]
172    pub audio: AudioProperties,
173    /// Whether a runtime may keep and reuse the clip's rendered picture. Never changes what
174    /// renders.
175    #[serde(default, skip_serializing_if = "CacheIntent::is_auto")]
176    pub cache: CacheIntent,
177}
178
179/// Whether a runtime may keep and reuse a clip's rendered picture.
180#[derive(Copy, Clone, Debug, Default, Deserialize, Eq, PartialEq, Serialize)]
181#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
182#[serde(rename_all = "snake_case")]
183pub enum CacheIntent {
184    /// The runtime decides, keeping pictures whose inputs it can identify.
185    #[default]
186    Auto,
187    /// Keep it ahead of other pictures, and bake its range when a host bakes render caches.
188    Pin,
189    /// Always render it live, never reading from or writing to a cache.
190    Bypass,
191}
192
193impl CacheIntent {
194    /// Whether it is [`CacheIntent::Auto`].
195    #[must_use]
196    pub const fn is_auto(&self) -> bool {
197        matches!(self, Self::Auto)
198    }
199}
200
201impl Clip {
202    /// Whether the clip's audio is time-stretched to keep its pitch: it asks to, plays forward
203    /// or reversed, and at a speed other than 1.
204    #[must_use]
205    pub fn stretches_audio(&self) -> bool {
206        self.audio.preserve_pitch
207            && matches!(self.time_map, TimeMap::Forward | TimeMap::Reverse)
208            && self.timeline_range.duration() != self.source_range.duration()
209    }
210
211    /// Creates a clip with default visual, blend, and audio controls and no composition.
212    #[must_use]
213    pub fn new(
214        id: ClipId,
215        source_id: SourceId,
216        timeline_range: TimeRange,
217        source_range: TimeRange,
218    ) -> Self {
219        Self {
220            id,
221            source_id,
222            timeline_range,
223            source_range,
224            visual: VisualProperties::default(),
225            composition: None,
226            blend_mode: ClipBlendMode::default(),
227            masks: Vec::new(),
228            matte: None,
229            time_map: TimeMap::Forward,
230            audio: AudioProperties::default(),
231            cache: CacheIntent::Auto,
232        }
233    }
234}
235
236/// A two-input transition over the overlap of two visual clips.
237#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
238#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
239#[serde(deny_unknown_fields)]
240pub struct ClipTransition {
241    /// Clip sampled as transition progress zero.
242    pub from_clip: ClipId,
243    /// Clip sampled as transition progress one.
244    pub to_clip: ClipId,
245    /// Half-open timeline interval over which both clips must be active.
246    pub timeline_range: TimeRange,
247    /// Timing curve applied to the transition's linear progress. The eased progress is clamped
248    /// to `0..=1`.
249    pub easing: Easing,
250    /// Versioned transition shader and named parameter values.
251    pub effect: ClipEffect,
252}