Skip to main content

alpha2_eval/edit/
request.rs

1//! What an edit operation asks for, what it reports, and why it refuses.
2
3use alpha2_model::{
4    ClipId, CompositionId, DataAnchor, DataKind, DataSetId, ModelError, NodeId, TrackId,
5};
6use alpha2_time::{MediaTime, TimeRange};
7use serde::{Deserialize, Serialize};
8use std::fmt;
9
10/// One edit operation, applied to a project once.
11#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
12#[serde(tag = "op", rename_all = "snake_case", deny_unknown_fields)]
13pub enum EditRequest {
14    /// Removes timeline ranges from the target clips, with ripple.
15    RemoveRanges {
16        /// An `intervals` data set or an anchored list.
17        ranges: Ranges,
18        /// The clips the ranges come from and apply to.
19        target: Target,
20        /// What closes the gaps; `timeline` by default.
21        #[serde(default)]
22        ripple: Ripple,
23        /// Keeps only the ranges, removing their complement within the target clips' extent.
24        #[serde(default)]
25        invert: bool,
26        /// Ticks kept at each edge of every removed range; a negative value widens each range,
27        /// which never starts before time 0.
28        #[serde(default)]
29        padding: MediaTime,
30        /// Removed ranges shorter than this, after padding, are kept.
31        #[serde(default)]
32        min_duration: MediaTime,
33    },
34    /// Splits every target clip spanning a mapped time, except where a cut would change what
35    /// the clip shows; those cuts are listed in [`EditReport::skipped`].
36    SplitAt {
37        /// An `intervals` data set's starts or an anchored list of ticks.
38        times: Times,
39        /// The clips split.
40        target: Target,
41    },
42    /// Replaces bindings with plain values.
43    Bake {
44        /// What is baked.
45        targets: Vec<BakeTarget>,
46    },
47}
48
49/// Ranges an operation reads.
50#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
51#[serde(untagged)]
52pub enum Ranges {
53    /// An `intervals` data set of the project.
54    Data(DataRef),
55    /// A list on an anchor's clock.
56    List(RangeList),
57}
58
59/// A data set an operation reads.
60#[derive(Clone, Debug, Deserialize, PartialEq, Eq, Serialize)]
61#[serde(deny_unknown_fields)]
62pub struct DataRef {
63    /// Its id.
64    pub data: DataSetId,
65}
66
67/// Ranges given in the request.
68#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
69#[serde(deny_unknown_fields)]
70pub struct RangeList {
71    /// The ranges as `{start, end}` ticks, each `start <= end`.
72    pub list: Vec<RawRange>,
73    /// The clock they are on; required.
74    #[serde(default)]
75    pub anchor: Option<DataAnchor>,
76}
77
78/// A range as written, before its order is checked.
79#[derive(Copy, Clone, Debug, Deserialize, PartialEq, Eq, Serialize)]
80#[serde(deny_unknown_fields)]
81pub struct RawRange {
82    /// Its start, in ticks.
83    pub start: MediaTime,
84    /// Its end, in ticks.
85    pub end: MediaTime,
86}
87
88/// Times an operation reads.
89#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
90#[serde(untagged)]
91pub enum Times {
92    /// The starts of an `intervals` data set's items.
93    Data(DataRef),
94    /// A list of ticks on an anchor's clock.
95    List(TimeList),
96}
97
98/// Times given in the request.
99#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
100#[serde(deny_unknown_fields)]
101pub struct TimeList {
102    /// The times, in ticks.
103    pub list: Vec<MediaTime>,
104    /// The clock they are on; required.
105    #[serde(default)]
106    pub anchor: Option<DataAnchor>,
107}
108
109/// The clips an operation works on.
110#[derive(Clone, Debug, Deserialize, PartialEq, Eq, Serialize)]
111#[serde(rename_all = "snake_case", deny_unknown_fields)]
112pub enum Target {
113    /// Every clip of a track.
114    Track(TrackId),
115    /// These clips.
116    Clips(Vec<ClipId>),
117}
118
119/// What closes the gaps a removal leaves.
120#[derive(Copy, Clone, Debug, Default, Deserialize, PartialEq, Eq, Serialize)]
121#[serde(rename_all = "snake_case")]
122pub enum Ripple {
123    /// Nothing closes them; the target clips lose the ranges and gaps stay.
124    None,
125    /// Every clip on the target clips' tracks loses the ranges and closes up; other tracks stay.
126    Track,
127    /// The ranges leave every track, so picture, sound and captions stay in sync.
128    #[default]
129    Timeline,
130}
131
132/// One value or caption track to bake.
133#[derive(Clone, Debug, Deserialize, PartialEq, Eq, Serialize)]
134#[serde(untagged)]
135pub enum BakeTarget {
136    /// A clip's property, such as `visual.position`, `masks[0].feather` or `audio.gain`.
137    Clip {
138        /// The clip.
139        clip: ClipId,
140        /// The property path.
141        property: String,
142    },
143    /// A composition node's property, such as `effect.params.radius`.
144    Node {
145        /// The composition.
146        composition: CompositionId,
147        /// The node.
148        node: NodeId,
149        /// The property path.
150        property: String,
151    },
152    /// A track's property: `captions`, `audio.gain` or `audio.pan`.
153    Track {
154        /// The track.
155        track: TrackId,
156        /// The property path.
157        property: String,
158    },
159}
160
161/// A kept stretch of timeline that moved.
162#[derive(Clone, Debug, PartialEq, Eq, Serialize)]
163pub struct Moved {
164    /// Where it was.
165    pub from: TimeRange,
166    /// Where it is.
167    pub to: TimeRange,
168}
169
170/// A clip an operation created by cutting another.
171#[derive(Clone, Debug, PartialEq, Eq, Serialize)]
172pub struct Created {
173    /// The new clip.
174    pub id: ClipId,
175    /// The clip it was cut from, which keeps its id on its first part.
176    pub from: ClipId,
177}
178
179/// Why `split_at` left a cut out.
180#[derive(Copy, Clone, Debug, PartialEq, Eq, Serialize)]
181#[serde(rename_all = "snake_case")]
182pub enum SkipReason {
183    /// The cut, or a loop part boundary it makes, falls inside one of the clip's transitions.
184    InTransition,
185    /// The cut falls inside one of the clip's fades.
186    InFade,
187    /// The clip is another clip's matte, and that clip is not cut alike.
188    MatteSource,
189    /// A binding reads through the clip (`via`), and its owner is not cut alike.
190    ReadThrough,
191}
192
193/// A cut `split_at` left out.
194#[derive(Clone, Debug, PartialEq, Eq, Serialize)]
195pub struct Skipped {
196    /// The clip.
197    pub clip: ClipId,
198    /// The cut, in timeline time.
199    pub time: MediaTime,
200    /// Why.
201    pub reason: SkipReason,
202}
203
204/// What an operation changed, so a caller can show and select it.
205#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize)]
206pub struct EditReport {
207    /// Timeline ranges removed, in the old timeline's time.
208    pub removed: Vec<TimeRange>,
209    /// Kept stretches that moved.
210    pub moved: Vec<Moved>,
211    /// Clips the operation created, with the clip each was cut from.
212    pub created: Vec<Created>,
213    /// Cuts `split_at` left out, in clip and time order; omitted when there are none.
214    #[serde(skip_serializing_if = "Vec::is_empty")]
215    pub skipped: Vec<Skipped>,
216}
217
218/// Why an operation refused.
219#[derive(Clone, Debug, PartialEq, Eq)]
220#[non_exhaustive]
221pub enum EditError {
222    /// It names no data set of the project.
223    UnknownData(DataSetId),
224    /// The data set's kind does not fit the operation.
225    WrongKind {
226        /// The data set.
227        data: DataSetId,
228        /// Its kind.
229        kind: DataKind,
230    },
231    /// It names a clip, track, composition or node the project lacks.
232    UnknownTarget(String),
233    /// The target names no clip.
234    EmptyTarget,
235    /// A list without an anchor.
236    MissingAnchor,
237    /// A range with its start after its end, by position.
238    InvalidRange(usize),
239    /// A bake target whose value is not bound to data (or a track with no words).
240    NothingToBake(String),
241    /// A correction has no keyframe equivalent.
242    CorrectionNotBakeable(String),
243    /// A bake target is a parameter of an effect the model has no range for (a host effect), so
244    /// the live value the renderer clamps cannot be written.
245    UnboundedParameter(String),
246    /// The edit cuts a matte source where a clip it mattes is not cut, or removes it from under
247    /// one, so no single part of it can stay that clip's matte.
248    MatteSource(ClipId),
249    /// The edit cuts a clip where a binding reading through it (`via`) is not cut, or removes it,
250    /// so no single part of it can be read through.
251    ReadThrough {
252        /// The clip read through.
253        clip: ClipId,
254        /// The binding's owner, such as `clip b`, `track t` or `the master bus`.
255        by: String,
256    },
257    /// A removed range's edge, or a part boundary the removal makes in a loop, falls strictly
258    /// inside a transition of the clip it cuts.
259    InTransition {
260        /// The clip cut.
261        clip: ClipId,
262        /// Where, in timeline time.
263        time: MediaTime,
264    },
265    /// A removed range's edge falls strictly inside a fade of the clip it cuts.
266    InFade {
267        /// The clip cut.
268        clip: ClipId,
269        /// Where, in timeline time.
270        time: MediaTime,
271    },
272    /// The result would hold more clips on a track than a track holds.
273    TooManyClips {
274        /// The track.
275        track: TrackId,
276        /// The clips it would hold.
277        found: usize,
278        /// The most it holds.
279        maximum: usize,
280    },
281    /// A caption bake's cues do not fit a track: more than it holds, or words past the limits of
282    /// cues from words ([`alpha2_model::MAX_DERIVED_CUES`], [`alpha2_model::MAX_DATA_WORDS`]).
283    TooManyCues {
284        /// The track.
285        track: TrackId,
286        /// The cues it would hold; `None` when the words pass the limits of cues from words.
287        found: Option<usize>,
288        /// The most it holds.
289        maximum: usize,
290    },
291    /// The edited project failed validation, which is a bug.
292    InvalidResult(ModelError),
293}
294
295impl fmt::Display for EditError {
296    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
297        match self {
298            Self::UnknownData(data) => write!(formatter, "unknown data set {data}"),
299            Self::WrongKind { data, kind } => write!(
300                formatter,
301                "data set {data} is {kind} data, which the operation does not take"
302            ),
303            Self::UnknownTarget(what) => write!(formatter, "unknown {what}"),
304            Self::EmptyTarget => formatter.write_str("the target names no clip"),
305            Self::MissingAnchor => formatter.write_str("a list needs an anchor"),
306            Self::InvalidRange(index) => write!(formatter, "range {index} starts after it ends"),
307            Self::NothingToBake(at) => write!(formatter, "{at} follows no data"),
308            Self::CorrectionNotBakeable(at) => {
309                write!(formatter, "{at} is a correction, which has no keyframes")
310            }
311            Self::UnboundedParameter(at) => write!(
312                formatter,
313                "{at} is a parameter of an effect whose range only the renderer knows"
314            ),
315            Self::MatteSource(clip) => write!(
316                formatter,
317                "clip {clip} is another clip's matte, and the edit cuts the two apart"
318            ),
319            Self::ReadThrough { clip, by } => write!(
320                formatter,
321                "{by} reads data through clip {clip}, and the edit cuts the two apart"
322            ),
323            Self::InTransition { clip, time } => write!(
324                formatter,
325                "the edit cuts clip {clip} at {} inside one of its transitions",
326                time.ticks()
327            ),
328            Self::InFade { clip, time } => write!(
329                formatter,
330                "the edit cuts clip {clip} at {} inside one of its fades",
331                time.ticks()
332            ),
333            Self::TooManyClips {
334                track,
335                found,
336                maximum,
337            } => write!(
338                formatter,
339                "the edit leaves {found} clips on track {track}; a track holds {maximum}"
340            ),
341            Self::TooManyCues {
342                track,
343                found: Some(found),
344                maximum,
345            } => write!(
346                formatter,
347                "the bake writes {found} cues on track {track}; a track holds {maximum}"
348            ),
349            Self::TooManyCues {
350                track, found: None, ..
351            } => write!(
352                formatter,
353                "the words of track {track} derive more than {} cues or map more than {} words",
354                alpha2_model::MAX_DERIVED_CUES,
355                alpha2_model::MAX_DATA_WORDS
356            ),
357            Self::InvalidResult(error) => {
358                write!(formatter, "the edited project is invalid: {error}")
359            }
360        }
361    }
362}
363
364impl std::error::Error for EditError {}
365
366impl EditError {
367    /// The refusal in snake case, as every binding reports it: `unknown_data`, `wrong_kind`,
368    /// `unknown_target`, `empty_target`, `missing_anchor`, `invalid_range`, `nothing_to_bake`,
369    /// `correction_not_bakeable`, `unbounded_parameter`, `matte_source`, `read_through`,
370    /// `in_transition`, `in_fade`, `too_many_clips`, `too_many_cues` or `invalid_result`.
371    #[must_use]
372    pub const fn kind(&self) -> &'static str {
373        match self {
374            Self::UnknownData(_) => "unknown_data",
375            Self::WrongKind { .. } => "wrong_kind",
376            Self::UnknownTarget(_) => "unknown_target",
377            Self::EmptyTarget => "empty_target",
378            Self::MissingAnchor => "missing_anchor",
379            Self::InvalidRange(_) => "invalid_range",
380            Self::NothingToBake(_) => "nothing_to_bake",
381            Self::CorrectionNotBakeable(_) => "correction_not_bakeable",
382            Self::UnboundedParameter(_) => "unbounded_parameter",
383            Self::MatteSource(_) => "matte_source",
384            Self::ReadThrough { .. } => "read_through",
385            Self::InTransition { .. } => "in_transition",
386            Self::InFade { .. } => "in_fade",
387            Self::TooManyClips { .. } => "too_many_clips",
388            Self::TooManyCues { .. } => "too_many_cues",
389            Self::InvalidResult(_) => "invalid_result",
390        }
391    }
392}