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}