Skip to main content

alpha2_model/
data.rs

1//! Data sets, the values an extractor derived from media, recorded in the project and anchored to
2//! a source's clock or the timeline's.
3//!
4//! The engine consumes data in two ways. Values and caption tracks bind to a data set and
5//! follow it at render time through the same time map the picture uses; edit operations apply
6//! interval data to the document once. No extractor runs while a frame renders.
7
8use crate::{ClipId, DataSetId, MediaFingerprint, NodeId};
9use alpha2_media::SourceId;
10use alpha2_time::MediaTime;
11use serde::{Deserialize, Serialize};
12use std::fmt;
13
14/// Most data sets in one project.
15///
16/// The per-set limits below bound one set; together they admit far more than a document holds.
17/// The byte cap ([`crate::MAX_PROJECT_JSON_BYTES`]) binds first: about 6 million values of full
18/// precision fill it, and every writer refuses a project past it.
19pub const MAX_DATA_SETS: usize = 256;
20/// Most channels of one `points` or `scalars` data set.
21pub const MAX_DATA_CHANNELS: usize = 64;
22/// Most values (numbers or lost markers) of one sampled data set.
23pub const MAX_DATA_VALUES: usize = 4_000_000;
24/// Most words of one `words` data set.
25pub const MAX_DATA_WORDS: usize = 200_000;
26/// Most intervals of one `intervals` data set.
27pub const MAX_DATA_INTERVALS: usize = 200_000;
28/// Most bytes of an interval label, a word's text or speaker, or a channel name.
29pub const MAX_DATA_LABEL_BYTES: usize = 256;
30/// Most bytes of a data set's id.
31pub const MAX_DATA_ID_BYTES: usize = 64;
32/// Largest magnitude of a normalized coordinate (points, similarity translation).
33pub const MAX_DATA_COORDINATE: f32 = 16.0;
34/// Largest magnitude of a scalar or an interval score.
35pub const MAX_DATA_SCALAR: f32 = 1e9;
36/// Largest magnitude of a similarity rotation, in degrees.
37pub const MAX_DATA_ROTATION_DEGREES: f32 = 36_000.0;
38/// Largest similarity scale; the smallest is just above zero.
39pub const MAX_DATA_SCALE: f32 = 1_000.0;
40/// Longest chain of canvas-space follows from one clip, counted in links.
41pub const MAX_FOLLOW_DEPTH: usize = 8;
42
43/// The clock a data set's times are on.
44#[derive(Clone, Debug, Eq, PartialEq, Hash, Serialize)]
45#[serde(tag = "type", rename_all = "snake_case")]
46pub enum DataAnchor {
47    /// Source time, the presentation times the source's pictures and sound carry once decoded.
48    /// Points are normalized to the displayed source picture.
49    Source {
50        /// The source.
51        source_id: SourceId,
52    },
53    /// Timeline time. Points are normalized to the canvas.
54    Timeline,
55}
56
57impl DataAnchor {
58    /// The anchored source, if any.
59    #[must_use]
60    pub const fn source(&self) -> Option<&SourceId> {
61        match self {
62            Self::Source { source_id } => Some(source_id),
63            Self::Timeline => None,
64        }
65    }
66}
67
68#[derive(Deserialize)]
69#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
70#[cfg_attr(feature = "schema", schemars(rename = "DataAnchor"))]
71#[serde(tag = "type", rename_all = "snake_case", deny_unknown_fields)]
72enum DataAnchorWire {
73    /// Source time, the presentation times the source's pictures and sound carry once decoded.
74    /// Points are normalized to the displayed source picture.
75    Source {
76        /// The source.
77        source_id: SourceId,
78    },
79    /// Timeline time. Points are normalized to the canvas.
80    Timeline {},
81}
82
83impl<'de> Deserialize<'de> for DataAnchor {
84    fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
85        Ok(match DataAnchorWire::deserialize(deserializer)? {
86            DataAnchorWire::Source { source_id } => Self::Source { source_id },
87            DataAnchorWire::Timeline {} => Self::Timeline,
88        })
89    }
90}
91
92#[cfg(feature = "schema")]
93impl schemars::JsonSchema for DataAnchor {
94    fn schema_name() -> std::borrow::Cow<'static, str> {
95        DataAnchorWire::schema_name()
96    }
97
98    fn json_schema(generator: &mut schemars::SchemaGenerator) -> schemars::Schema {
99        DataAnchorWire::json_schema(generator)
100    }
101}
102
103/// How a sampled data set reads between its samples.
104#[derive(Copy, Clone, Debug, Default, Deserialize, Eq, PartialEq, Hash, Serialize)]
105#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
106#[serde(rename_all = "snake_case")]
107pub enum DataInterpolation {
108    /// The sample at or before the time, as the picture shown at that time is chosen.
109    #[default]
110    Hold,
111    /// A straight line between the samples around the time.
112    Linear,
113}
114
115/// What a data set holds; each kind has a consumer in the engine.
116#[derive(Copy, Clone, Debug, Deserialize, Eq, PartialEq, Hash, Serialize)]
117#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
118#[serde(rename_all = "snake_case")]
119pub enum DataKind {
120    /// Named channels of normalized `(x, y)` points.
121    Points,
122    /// Named channels of numbers.
123    Scalars,
124    /// One translation, rotation and uniform scale per sample.
125    Similarity,
126    /// Timed words with text.
127    Words,
128    /// Timed ranges, a zero-length one being an instant.
129    Intervals,
130}
131
132impl DataKind {
133    /// Numbers per channel and sample of a sampled kind; `None` for words and intervals.
134    #[must_use]
135    pub const fn arity(self) -> Option<usize> {
136        match self {
137            Self::Points => Some(2),
138            Self::Scalars => Some(1),
139            Self::Similarity => Some(SIMILARITY_ARITY),
140            Self::Words | Self::Intervals => None,
141        }
142    }
143
144    /// The kind's wire name.
145    #[must_use]
146    pub const fn name(self) -> &'static str {
147        match self {
148            Self::Points => "points",
149            Self::Scalars => "scalars",
150            Self::Similarity => "similarity",
151            Self::Words => "words",
152            Self::Intervals => "intervals",
153        }
154    }
155}
156
157impl fmt::Display for DataKind {
158    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
159        formatter.write_str(self.name())
160    }
161}
162
163/// Numbers per similarity sample: `tx`, `ty`, rotation in degrees, scale.
164pub const SIMILARITY_ARITY: usize = 4;
165
166/// Samples on one time grid, stored by column.
167///
168/// `values` holds `times.len() * channels * arity` numbers: sample after sample, channel after
169/// channel within a sample, components within a channel. `None` marks a channel lost at that
170/// sample, and covers all of its components.
171#[derive(Clone, Debug, Default, PartialEq)]
172pub struct DataSamples {
173    /// How the values read between samples.
174    pub interpolation: DataInterpolation,
175    /// Channel names, unique; empty for `similarity`.
176    pub channels: Vec<String>,
177    /// Sample times in ticks on the anchor's clock, strictly ascending.
178    pub times: Vec<MediaTime>,
179    /// The values, as described on the type.
180    pub values: Vec<Option<f32>>,
181}
182
183impl DataSamples {
184    /// The position of `channel`, if the set has it.
185    #[must_use]
186    pub fn channel(&self, channel: &str) -> Option<usize> {
187        self.channels.iter().position(|name| name == channel)
188    }
189}
190
191/// One timed word.
192#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
193#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
194#[serde(deny_unknown_fields)]
195pub struct DataWord {
196    /// When the word starts, in ticks on the anchor's clock.
197    pub start: MediaTime,
198    /// When it ends; after `start`.
199    pub end: MediaTime,
200    /// The word, non-empty, at most [`MAX_DATA_LABEL_BYTES`] bytes.
201    pub text: String,
202    /// Who says it, at most [`MAX_DATA_LABEL_BYTES`] bytes.
203    #[serde(default, skip_serializing_if = "Option::is_none")]
204    pub speaker: Option<String>,
205}
206
207/// One timed range; `start == end` is an instant.
208#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
209#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
210#[serde(deny_unknown_fields)]
211pub struct DataInterval {
212    /// When it starts, in ticks on the anchor's clock.
213    pub start: MediaTime,
214    /// When it ends; not before `start`.
215    pub end: MediaTime,
216    /// A free label, at most [`MAX_DATA_LABEL_BYTES`] bytes. Edit operations ignore it.
217    #[serde(default, skip_serializing_if = "Option::is_none")]
218    pub label: Option<String>,
219    /// A free, finite score of at most [`MAX_DATA_SCALAR`] in magnitude; edit operations ignore it.
220    #[serde(default, skip_serializing_if = "Option::is_none")]
221    pub score: Option<f32>,
222}
223
224/// The values of a data set, by kind.
225#[derive(Clone, Debug, PartialEq)]
226pub enum DataValues {
227    /// Channels of `(x, y)` points.
228    Points(DataSamples),
229    /// Channels of numbers.
230    Scalars(DataSamples),
231    /// `tx`, `ty`, rotation in degrees and scale per sample, with no channels.
232    Similarity(DataSamples),
233    /// Words sorted by `(start, end)`; they may overlap.
234    Words(Vec<DataWord>),
235    /// Intervals sorted by `(start, end)`; they may overlap.
236    Intervals(Vec<DataInterval>),
237}
238
239impl DataValues {
240    /// The kind of these values.
241    #[must_use]
242    pub const fn kind(&self) -> DataKind {
243        match self {
244            Self::Points(_) => DataKind::Points,
245            Self::Scalars(_) => DataKind::Scalars,
246            Self::Similarity(_) => DataKind::Similarity,
247            Self::Words(_) => DataKind::Words,
248            Self::Intervals(_) => DataKind::Intervals,
249        }
250    }
251
252    /// The samples of a sampled kind.
253    #[must_use]
254    pub const fn samples(&self) -> Option<&DataSamples> {
255        match self {
256            Self::Points(samples) | Self::Scalars(samples) | Self::Similarity(samples) => {
257                Some(samples)
258            }
259            Self::Words(_) | Self::Intervals(_) => None,
260        }
261    }
262}
263
264/// Which extractor made a data set. Recorded for hosts; the engine never reads it.
265#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
266#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
267#[serde(deny_unknown_fields)]
268pub struct MadeBy {
269    /// The extractor's reverse-DNS id.
270    pub extractor: String,
271    /// The extractor's output-contract version.
272    pub version: u32,
273    /// The parameters it ran with.
274    #[serde(default)]
275    pub params: serde_json::Map<String, serde_json::Value>,
276    /// The plugin that ran, when the extractor was one.
277    #[serde(default, skip_serializing_if = "Option::is_none")]
278    pub plugin: Option<MadeByPlugin>,
279}
280
281/// The plugin build that made a data set.
282#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
283#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
284#[serde(deny_unknown_fields)]
285pub struct MadeByPlugin {
286    /// The package's semantic version.
287    pub version: String,
288    /// SHA-256 of the artifact that ran, as 64 lowercase hexadecimal digits.
289    pub artifact_sha256: String,
290}
291
292/// Values derived from media, anchored to a source or to the timeline.
293#[derive(Clone, Debug, PartialEq)]
294pub struct DataSet {
295    /// Stable identity; at most [`MAX_DATA_ID_BYTES`] bytes.
296    pub id: DataSetId,
297    /// The clock the times are on.
298    pub anchor: DataAnchor,
299    /// The values.
300    pub values: DataValues,
301    /// Which extractor made it.
302    pub made_by: Option<MadeBy>,
303    /// The original source's fingerprint when the data was made; absent for timeline anchors.
304    /// Hosts compare it with the source's current one to report stale data.
305    pub made_from: Option<MediaFingerprint>,
306}
307
308impl DataSet {
309    /// Its latest time: the last sample, or the latest word or interval end.
310    #[must_use]
311    pub fn last_time(&self) -> Option<MediaTime> {
312        match &self.values {
313            DataValues::Points(samples)
314            | DataValues::Scalars(samples)
315            | DataValues::Similarity(samples) => samples.times.last().copied(),
316            DataValues::Words(words) => words.iter().map(|word| word.end).max(),
317            DataValues::Intervals(intervals) => intervals.iter().map(|interval| interval.end).max(),
318        }
319    }
320
321    /// The kind of the values.
322    #[must_use]
323    pub const fn kind(&self) -> DataKind {
324        self.values.kind()
325    }
326}
327
328// The schema of a `DataSet`: one flat object per kind with only that kind's fields.
329/// Values derived from media, anchored to a source's clock or the timeline's.
330#[cfg(feature = "schema")]
331#[allow(dead_code)]
332#[derive(schemars::JsonSchema)]
333#[schemars(rename = "DataSet")]
334#[serde(tag = "kind", rename_all = "snake_case", deny_unknown_fields)]
335enum DataSetSchema {
336    /// Named channels of normalized `(x, y)` points, each pair `null` when lost.
337    Points {
338        /// Stable identity, 1 to 64 bytes.
339        id: DataSetId,
340        /// The clock the times are on.
341        anchor: DataAnchor,
342        /// How the values read between samples.
343        interpolation: DataInterpolation,
344        /// Channel names, unique, 1 to 256 bytes each.
345        #[cfg_attr(feature = "schema", schemars(length(max = crate::MAX_DATA_CHANNELS)))]
346        channels: Vec<String>,
347        /// Sample times in ticks on the anchor's clock, strictly ascending.
348        #[cfg_attr(feature = "schema", schemars(length(max = crate::MAX_DATA_VALUES)))]
349        times: Vec<MediaTime>,
350        /// `times.len() * channels.len() * 2` numbers, sample after sample, channel after channel.
351        #[cfg_attr(feature = "schema", schemars(length(max = crate::MAX_DATA_VALUES)))]
352        values: Vec<Option<f32>>,
353        /// Which extractor made it.
354        #[serde(default)]
355        made_by: Option<MadeBy>,
356        /// The original source's fingerprint when it was made.
357        #[serde(default)]
358        made_from: Option<MediaFingerprint>,
359    },
360    /// Named channels of numbers, each `null` when lost.
361    Scalars {
362        /// Stable identity, 1 to 64 bytes.
363        id: DataSetId,
364        /// The clock the times are on.
365        anchor: DataAnchor,
366        /// How the values read between samples.
367        interpolation: DataInterpolation,
368        /// Channel names, unique, 1 to 256 bytes each.
369        #[cfg_attr(feature = "schema", schemars(length(max = crate::MAX_DATA_CHANNELS)))]
370        channels: Vec<String>,
371        /// Sample times in ticks on the anchor's clock, strictly ascending.
372        #[cfg_attr(feature = "schema", schemars(length(max = crate::MAX_DATA_VALUES)))]
373        times: Vec<MediaTime>,
374        /// `times.len() * channels.len()` numbers, sample after sample, channel after channel.
375        #[cfg_attr(feature = "schema", schemars(length(max = crate::MAX_DATA_VALUES)))]
376        values: Vec<Option<f32>>,
377        /// Which extractor made it.
378        #[serde(default)]
379        made_by: Option<MadeBy>,
380        /// The original source's fingerprint when it was made.
381        #[serde(default)]
382        made_from: Option<MediaFingerprint>,
383    },
384    /// Translation (normalized), rotation (degrees) and uniform scale about the picture's
385    /// center, per sample; four `null`s when lost.
386    Similarity {
387        /// Stable identity, 1 to 64 bytes.
388        id: DataSetId,
389        /// The clock the times are on.
390        anchor: DataAnchor,
391        /// How the values read between samples.
392        interpolation: DataInterpolation,
393        /// Sample times in ticks on the anchor's clock, strictly ascending.
394        #[cfg_attr(feature = "schema", schemars(length(max = crate::MAX_DATA_VALUES)))]
395        times: Vec<MediaTime>,
396        /// `times.len() * 4` numbers: `tx`, `ty`, rotation, scale per sample.
397        #[cfg_attr(feature = "schema", schemars(length(max = crate::MAX_DATA_VALUES)))]
398        values: Vec<Option<f32>>,
399        /// Which extractor made it.
400        #[serde(default)]
401        made_by: Option<MadeBy>,
402        /// The original source's fingerprint when it was made.
403        #[serde(default)]
404        made_from: Option<MediaFingerprint>,
405    },
406    /// Timed words.
407    Words {
408        /// Stable identity, 1 to 64 bytes.
409        id: DataSetId,
410        /// The clock the times are on.
411        anchor: DataAnchor,
412        /// Words sorted by `(start, end)`.
413        #[cfg_attr(feature = "schema", schemars(length(max = crate::MAX_DATA_WORDS)))]
414        words: Vec<DataWord>,
415        /// Which extractor made it.
416        #[serde(default)]
417        made_by: Option<MadeBy>,
418        /// The original source's fingerprint when it was made.
419        #[serde(default)]
420        made_from: Option<MediaFingerprint>,
421    },
422    /// Timed ranges.
423    Intervals {
424        /// Stable identity, 1 to 64 bytes.
425        id: DataSetId,
426        /// The clock the times are on.
427        anchor: DataAnchor,
428        /// Intervals sorted by `(start, end)`.
429        #[cfg_attr(feature = "schema", schemars(length(max = crate::MAX_DATA_INTERVALS)))]
430        intervals: Vec<DataInterval>,
431        /// Which extractor made it.
432        #[serde(default)]
433        made_by: Option<MadeBy>,
434        /// The original source's fingerprint when it was made.
435        #[serde(default)]
436        made_from: Option<MediaFingerprint>,
437    },
438}
439
440#[cfg(feature = "schema")]
441impl schemars::JsonSchema for DataSet {
442    fn schema_name() -> std::borrow::Cow<'static, str> {
443        DataSetSchema::schema_name()
444    }
445
446    fn json_schema(generator: &mut schemars::SchemaGenerator) -> schemars::Schema {
447        DataSetSchema::json_schema(generator)
448    }
449}
450
451/// Every field any kind has, read without buffering, then checked against the kind.
452#[derive(Deserialize)]
453#[serde(deny_unknown_fields)]
454struct DataSetFlat {
455    id: DataSetId,
456    anchor: DataAnchor,
457    kind: DataKind,
458    #[serde(default)]
459    interpolation: Option<DataInterpolation>,
460    #[serde(default)]
461    #[serde(deserialize_with = "crate::bounded::option_seq::<_, _, { crate::MAX_DATA_CHANNELS }>")]
462    channels: Option<Vec<String>>,
463    #[serde(default)]
464    #[serde(deserialize_with = "crate::bounded::option_seq::<_, _, { crate::MAX_DATA_VALUES }>")]
465    times: Option<Vec<MediaTime>>,
466    #[serde(default)]
467    #[serde(deserialize_with = "crate::bounded::option_seq::<_, _, { crate::MAX_DATA_VALUES }>")]
468    values: Option<Vec<Option<f32>>>,
469    #[serde(default)]
470    #[serde(deserialize_with = "crate::bounded::option_seq::<_, _, { crate::MAX_DATA_WORDS }>")]
471    words: Option<Vec<DataWord>>,
472    #[serde(default)]
473    #[serde(
474        deserialize_with = "crate::bounded::option_seq::<_, _, { crate::MAX_DATA_INTERVALS }>"
475    )]
476    intervals: Option<Vec<DataInterval>>,
477    #[serde(default)]
478    made_by: Option<MadeBy>,
479    #[serde(default)]
480    made_from: Option<MediaFingerprint>,
481}
482
483impl TryFrom<DataSetFlat> for DataSet {
484    type Error = String;
485
486    fn try_from(flat: DataSetFlat) -> Result<Self, Self::Error> {
487        let kind = flat.kind;
488        let stray = |field: &str| format!("a {kind} data set has no field `{field}`");
489        let missing = |field: &str| format!("a {kind} data set needs `{field}`");
490        let values = match kind {
491            DataKind::Points | DataKind::Scalars | DataKind::Similarity => {
492                if flat.words.is_some() {
493                    return Err(stray("words"));
494                }
495                if flat.intervals.is_some() {
496                    return Err(stray("intervals"));
497                }
498                let channels = if kind == DataKind::Similarity {
499                    if flat.channels.is_some() {
500                        return Err(stray("channels"));
501                    }
502                    Vec::new()
503                } else {
504                    flat.channels.ok_or_else(|| missing("channels"))?
505                };
506                let samples = DataSamples {
507                    interpolation: flat.interpolation.ok_or_else(|| missing("interpolation"))?,
508                    channels,
509                    times: flat.times.ok_or_else(|| missing("times"))?,
510                    values: flat.values.ok_or_else(|| missing("values"))?,
511                };
512                match kind {
513                    DataKind::Points => DataValues::Points(samples),
514                    DataKind::Scalars => DataValues::Scalars(samples),
515                    _ => DataValues::Similarity(samples),
516                }
517            }
518            DataKind::Words | DataKind::Intervals => {
519                for (field, present) in [
520                    ("interpolation", flat.interpolation.is_some()),
521                    ("channels", flat.channels.is_some()),
522                    ("times", flat.times.is_some()),
523                    ("values", flat.values.is_some()),
524                ] {
525                    if present {
526                        return Err(stray(field));
527                    }
528                }
529                if kind == DataKind::Words {
530                    if flat.intervals.is_some() {
531                        return Err(stray("intervals"));
532                    }
533                    DataValues::Words(flat.words.ok_or_else(|| missing("words"))?)
534                } else {
535                    if flat.words.is_some() {
536                        return Err(stray("words"));
537                    }
538                    DataValues::Intervals(flat.intervals.ok_or_else(|| missing("intervals"))?)
539                }
540            }
541        };
542        Ok(Self {
543            id: flat.id,
544            anchor: flat.anchor,
545            values,
546            made_by: flat.made_by,
547            made_from: flat.made_from,
548        })
549    }
550}
551
552impl<'de> Deserialize<'de> for DataSet {
553    fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
554        let flat = DataSetFlat::deserialize(deserializer)?;
555        Self::try_from(flat).map_err(serde::de::Error::custom)
556    }
557}
558
559#[derive(Serialize)]
560struct DataSetRef<'a> {
561    id: &'a DataSetId,
562    anchor: &'a DataAnchor,
563    kind: DataKind,
564    #[serde(skip_serializing_if = "Option::is_none")]
565    interpolation: Option<DataInterpolation>,
566    #[serde(skip_serializing_if = "Option::is_none")]
567    channels: Option<&'a [String]>,
568    #[serde(skip_serializing_if = "Option::is_none")]
569    times: Option<&'a [MediaTime]>,
570    #[serde(skip_serializing_if = "Option::is_none")]
571    values: Option<&'a [Option<f32>]>,
572    #[serde(skip_serializing_if = "Option::is_none")]
573    words: Option<&'a [DataWord]>,
574    #[serde(skip_serializing_if = "Option::is_none")]
575    intervals: Option<&'a [DataInterval]>,
576    #[serde(skip_serializing_if = "Option::is_none")]
577    made_by: Option<&'a MadeBy>,
578    #[serde(skip_serializing_if = "Option::is_none")]
579    made_from: Option<&'a MediaFingerprint>,
580}
581
582impl Serialize for DataSet {
583    fn serialize<S: serde::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
584        let mut wire = DataSetRef {
585            id: &self.id,
586            anchor: &self.anchor,
587            kind: self.kind(),
588            interpolation: None,
589            channels: None,
590            times: None,
591            values: None,
592            words: None,
593            intervals: None,
594            made_by: self.made_by.as_ref(),
595            made_from: self.made_from.as_ref(),
596        };
597        match &self.values {
598            DataValues::Points(samples)
599            | DataValues::Scalars(samples)
600            | DataValues::Similarity(samples) => {
601                wire.interpolation = Some(samples.interpolation);
602                if self.kind() != DataKind::Similarity {
603                    wire.channels = Some(&samples.channels);
604                }
605                wire.times = Some(&samples.times);
606                wire.values = Some(&samples.values);
607            }
608            DataValues::Words(words) => wire.words = Some(words),
609            DataValues::Intervals(intervals) => wire.intervals = Some(intervals),
610        }
611        wire.serialize(serializer)
612    }
613}
614
615/// A value that follows a channel of a data set at render time: the `data` value mode.
616///
617/// A source-anchored set is read through a reader (`via`) whose time map gives source time, so
618/// the value follows the picture through any speed, reverse, loop or freeze.
619#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
620#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
621#[serde(deny_unknown_fields)]
622pub struct DataBinding {
623    /// The data set, a `points` or `scalars` one.
624    pub data: DataSetId,
625    /// The channel followed.
626    pub channel: String,
627    /// The reader whose time map gives source time: required for a source-anchored set,
628    /// forbidden for a timeline-anchored one.
629    #[serde(default, skip_serializing_if = "Option::is_none")]
630    pub via: Option<DataVia>,
631    /// Where a point is read (points with `via` only, where it is required).
632    #[serde(default, skip_serializing_if = "Option::is_none")]
633    pub space: Option<DataSpace>,
634    /// `[x, y]` added after the space mapping, in that space's normalized units (points only).
635    #[serde(default, skip_serializing_if = "Option::is_none")]
636    pub offset: Option<[f32; 2]>,
637    /// A linear map of the value (scalars only).
638    #[serde(default, skip_serializing_if = "Option::is_none")]
639    pub remap: Option<DataRemap>,
640}
641
642/// The reader whose clock maps time onto a source-anchored data set.
643#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Hash, Serialize)]
644#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
645#[serde(rename_all = "snake_case", deny_unknown_fields)]
646pub enum DataVia {
647    /// A timeline clip showing the anchor's source; its picture time map gives source time.
648    Clip(ClipId),
649    /// A `media` node of the same composition reading the anchor's source; its start plus the
650    /// composition time gives source time.
651    Node(NodeId),
652}
653
654/// Where a bound point is read.
655#[derive(Copy, Clone, Debug, Deserialize, Eq, PartialEq, Hash, Serialize)]
656#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
657#[serde(rename_all = "snake_case")]
658pub enum DataSpace {
659    /// The normalized source picture, unchanged: effect params and the clip's own masks.
660    Picture,
661    /// Normalized canvas coordinates through the `via` clip's presentation and evaluated
662    /// visual: another clip's position.
663    Canvas,
664}
665
666/// A linear map from `input` to `output`, clamped to `output`.
667#[derive(Copy, Clone, Debug, Deserialize, PartialEq, Serialize)]
668#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
669#[serde(deny_unknown_fields)]
670pub struct DataRemap {
671    /// The input values mapped to `output[0]` and `output[1]`; distinct and finite.
672    pub input: [f32; 2],
673    /// The output range; finite.
674    pub output: [f32; 2],
675}
676
677impl DataRemap {
678    /// Maps `value`, clamped to the output range.
679    #[must_use]
680    pub fn apply(&self, value: f32) -> f32 {
681        let [in0, in1] = self.input.map(f64::from);
682        let [out0, out1] = self.output.map(f64::from);
683        let mapped = out0 + (f64::from(value) - in0) * (out1 - out0) / (in1 - in0);
684        let (low, high) = if out0 <= out1 {
685            (out0, out1)
686        } else {
687            (out1, out0)
688        };
689        #[allow(clippy::cast_possible_truncation)]
690        let clamped = mapped.clamp(low, high) as f32;
691        clamped
692    }
693
694    // Equal inputs give no slope; any two distinct values do.
695    #[allow(clippy::float_cmp)]
696    fn is_valid(&self) -> bool {
697        self.input
698            .iter()
699            .chain(&self.output)
700            .all(|value| value.is_finite())
701            && self.input[0] != self.input[1]
702    }
703}
704
705/// A `similarity` data set applied to a clip's own picture before its transform.
706#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
707#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
708#[serde(deny_unknown_fields)]
709pub struct CorrectionRef {
710    /// The data set, a `similarity` one anchored to the clip's source.
711    pub data: DataSetId,
712}
713
714/// Caption cues built from a `words` data set.
715#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
716#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
717#[serde(deny_unknown_fields)]
718pub struct CaptionsFromWords {
719    /// The data set, a `words` one.
720    pub data: DataSetId,
721    /// For a source-anchored set, the track whose clips showing the source give the words their
722    /// timeline times; forbidden for a timeline-anchored set.
723    #[serde(default, skip_serializing_if = "Option::is_none")]
724    pub track: Option<crate::TrackId>,
725    /// Most characters of one cue, at least 1.
726    pub max_chars: u32,
727}
728
729/// What is wrong with a data set.
730#[derive(Clone, Debug, Eq, PartialEq)]
731#[non_exhaustive]
732pub enum DataProblem {
733    /// The id is longer than [`MAX_DATA_ID_BYTES`].
734    IdTooLong,
735    /// The anchor names no source of the project.
736    UnknownSource(SourceId),
737    /// The anchor names a source that has no media clock (a generated or composition source).
738    SourceWithoutMedia(SourceId),
739    /// More than [`MAX_DATA_CHANNELS`] channels, or none.
740    ChannelCount,
741    /// A channel name is empty, too long or repeated.
742    ChannelName,
743    /// More than [`MAX_DATA_VALUES`] values.
744    TooManyValues,
745    /// `values` does not hold exactly `times * channels * arity` entries.
746    ValueCount,
747    /// Times are not strictly ascending.
748    TimesNotAscending,
749    /// A time is negative.
750    NegativeTime,
751    /// A value is not finite, outside its kind's bounds, or a lost marker covers only part of a
752    /// channel or sample.
753    InvalidValue {
754        /// The value's position in `values`.
755        index: usize,
756    },
757    /// More than [`MAX_DATA_WORDS`] words or [`MAX_DATA_INTERVALS`] intervals.
758    TooManyItems,
759    /// A word or interval is out of order, has its end before its start (or at it, for a
760    /// word), empty word text, a score out of bounds, or a text too long.
761    InvalidItem {
762        /// The item's position.
763        index: usize,
764    },
765    /// `made_by` has an empty extractor id or a malformed plugin hash.
766    InvalidMadeBy,
767    /// `made_from` has a malformed part (by field name), or is present on a timeline anchor.
768    InvalidMadeFrom(&'static str),
769}
770
771impl fmt::Display for DataProblem {
772    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
773        match self {
774            Self::IdTooLong => write!(formatter, "has an id over {MAX_DATA_ID_BYTES} bytes"),
775            Self::UnknownSource(source) => {
776                write!(formatter, "is anchored to unknown source {source}")
777            }
778            Self::SourceWithoutMedia(source) => {
779                write!(
780                    formatter,
781                    "is anchored to source {source}, which has no media"
782                )
783            }
784            Self::ChannelCount => {
785                write!(formatter, "needs 1 to {MAX_DATA_CHANNELS} channels")
786            }
787            Self::ChannelName => {
788                formatter.write_str("has an empty, overlong or repeated channel name")
789            }
790            Self::TooManyValues => write!(formatter, "has more than {MAX_DATA_VALUES} values"),
791            Self::ValueCount => {
792                formatter.write_str("does not have times * channels * arity values")
793            }
794            Self::TimesNotAscending => {
795                formatter.write_str("has times that are not strictly ascending")
796            }
797            Self::NegativeTime => formatter.write_str("has a negative time"),
798            Self::InvalidValue { index } => {
799                write!(formatter, "has an invalid value at values[{index}]")
800            }
801            Self::TooManyItems => write!(
802                formatter,
803                "has more than {MAX_DATA_WORDS} words or {MAX_DATA_INTERVALS} intervals"
804            ),
805            Self::InvalidItem { index } => write!(formatter, "has an invalid item at [{index}]"),
806            Self::InvalidMadeBy => formatter.write_str("has an invalid made_by"),
807            Self::InvalidMadeFrom(part) => write!(formatter, "has an invalid made_from.{part}"),
808        }
809    }
810}
811
812/// What is wrong with a [`DataBinding`], a [`CorrectionRef`] or a [`CaptionsFromWords`].
813#[derive(Clone, Debug, Eq, PartialEq)]
814#[non_exhaustive]
815pub enum BindingProblem {
816    /// It names no data set of the project.
817    UnknownData,
818    /// The data set's kind does not fit the place's type.
819    WrongKind(DataKind),
820    /// The value's type takes no data (an effect parameter that is not a Float or Vec2).
821    TypeRefusesData,
822    /// The place's clock refuses this anchor, as a composition-time place refuses a timeline anchor
823    /// and a picture-time place refuses any.
824    ClockRefusesAnchor,
825    /// The channel is not one of the data set's.
826    UnknownChannel,
827    /// A source-anchored set needs `via`.
828    ViaRequired,
829    /// A timeline-anchored set takes no `via`.
830    ViaForbidden,
831    /// `via` names a clip at a composition-time place, or a node at a timeline-time place.
832    ViaWrongReader,
833    /// `via` names no timeline clip.
834    UnknownViaClip,
835    /// `via` names no node of the composition, or one that is not a `media` node.
836    InvalidViaNode,
837    /// The reader does not show the data set's source.
838    ViaShowsOtherSource,
839    /// A point read through `via` needs `space`.
840    SpaceRequired,
841    /// `space`, `offset` or `remap` where it does not apply, or `canvas` through a node.
842    FieldNotApplicable(&'static str),
843    /// `remap` has a non-finite value or equal inputs; `offset` a non-finite component.
844    InvalidRemap,
845    /// Following clips in canvas space forms a cycle.
846    Cycle,
847    /// The clip follows clips in canvas space through more than [`MAX_FOLLOW_DEPTH`] links.
848    TooDeep,
849    /// A correction's data set is not anchored to the clip's own source.
850    NotOwnSource,
851    /// A caption track's `track` is missing for a source anchor, given for a timeline anchor,
852    /// or names no visual or audio track; or `max_chars` is zero.
853    InvalidCaptionTrack,
854}
855
856impl fmt::Display for BindingProblem {
857    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
858        match self {
859            Self::UnknownData => formatter.write_str("names an unknown data set"),
860            Self::WrongKind(kind) => write!(formatter, "cannot follow {kind} data"),
861            Self::TypeRefusesData => formatter.write_str("is a value whose type takes no data"),
862            Self::ClockRefusesAnchor => {
863                formatter.write_str("is keyed on a clock that refuses this anchor")
864            }
865            Self::UnknownChannel => formatter.write_str("names an unknown channel"),
866            Self::ViaRequired => formatter.write_str("needs `via` for a source-anchored data set"),
867            Self::ViaForbidden => {
868                formatter.write_str("takes no `via` for a timeline-anchored data set")
869            }
870            Self::ViaWrongReader => {
871                formatter.write_str("names a reader of the wrong kind for its clock")
872            }
873            Self::UnknownViaClip => formatter.write_str("reads through an unknown clip"),
874            Self::InvalidViaNode => formatter
875                .write_str("reads through a node that is not a media node of its composition"),
876            Self::ViaShowsOtherSource => {
877                formatter.write_str("reads through a reader of another source")
878            }
879            Self::SpaceRequired => {
880                formatter.write_str("needs `space` for a point read through `via`")
881            }
882            Self::FieldNotApplicable(field) => {
883                write!(formatter, "has `{field}` where it does not apply")
884            }
885            Self::InvalidRemap => formatter
886                .write_str("has a non-finite offset or remap, or a remap with equal inputs"),
887            Self::Cycle => formatter.write_str("follows clips in canvas space in a cycle"),
888            Self::TooDeep => write!(
889                formatter,
890                "follows clips in canvas space more than {MAX_FOLLOW_DEPTH} deep"
891            ),
892            Self::NotOwnSource => {
893                formatter.write_str("corrects with data anchored to another source")
894            }
895            Self::InvalidCaptionTrack => {
896                formatter.write_str("has an invalid words track or max_chars")
897            }
898        }
899    }
900}
901
902pub(crate) fn valid_label(text: &str) -> bool {
903    text.len() <= MAX_DATA_LABEL_BYTES
904}
905
906fn valid_sha256(hash: &str) -> bool {
907    hash.len() == 64
908        && hash
909            .bytes()
910            .all(|byte| byte.is_ascii_digit() || (b'a'..=b'f').contains(&byte))
911}
912
913/// Whether `value` is inside its kind's bounds; `component` is the position within a sample's
914/// numbers for a similarity set.
915#[must_use]
916pub fn value_in_bounds(kind: DataKind, component: usize, value: f32) -> bool {
917    value.is_finite()
918        && match kind {
919            DataKind::Points => value.abs() <= MAX_DATA_COORDINATE,
920            DataKind::Similarity => match component {
921                0 | 1 => value.abs() <= MAX_DATA_COORDINATE,
922                2 => value.abs() <= MAX_DATA_ROTATION_DEGREES,
923                _ => value > 0.0 && value <= MAX_DATA_SCALE,
924            },
925            DataKind::Scalars | DataKind::Words | DataKind::Intervals => {
926                value.abs() <= MAX_DATA_SCALAR
927            }
928        }
929}
930
931/// Checks a word's own fields (order against its neighbours is checked by the caller).
932#[must_use]
933pub fn valid_word(word: &DataWord) -> bool {
934    word.start.ticks() >= 0
935        && word.start < word.end
936        && !word.text.is_empty()
937        && valid_label(&word.text)
938        && word.speaker.as_deref().is_none_or(valid_label)
939}
940
941/// Checks an interval's own fields (order against its neighbours is checked by the caller).
942#[must_use]
943pub fn valid_interval(interval: &DataInterval) -> bool {
944    interval.start.ticks() >= 0
945        && interval.start <= interval.end
946        && interval.label.as_deref().is_none_or(valid_label)
947        && interval
948            .score
949            .is_none_or(|score| value_in_bounds(DataKind::Scalars, 0, score))
950}
951
952impl DataSet {
953    /// Checks the set on its own against the model's rules (everything but its anchor's
954    /// existence). A time past its source's recorded duration is not an invalid set but stale
955    /// data, which [`crate::Project::lint`] reports, since a host may replace the duration.
956    ///
957    /// # Errors
958    /// The first [`DataProblem`] found.
959    pub fn validate(&self) -> Result<(), DataProblem> {
960        if self.id.as_str().len() > MAX_DATA_ID_BYTES {
961            return Err(DataProblem::IdTooLong);
962        }
963        if let Some(made_by) = &self.made_by {
964            let plugin_ok = made_by.plugin.as_ref().is_none_or(|plugin| {
965                !plugin.version.is_empty() && valid_sha256(&plugin.artifact_sha256)
966            });
967            if made_by.extractor.is_empty() || !plugin_ok {
968                return Err(DataProblem::InvalidMadeBy);
969            }
970        }
971        if let Some(made_from) = &self.made_from {
972            if self.anchor == DataAnchor::Timeline {
973                return Err(DataProblem::InvalidMadeFrom("anchor"));
974            }
975            if let Some(part) = made_from.malformed_part() {
976                return Err(DataProblem::InvalidMadeFrom(part));
977            }
978        }
979        let time_ok = |time: MediaTime| -> Result<(), DataProblem> {
980            if time.ticks() < 0 {
981                return Err(DataProblem::NegativeTime);
982            }
983            Ok(())
984        };
985        let kind = self.kind();
986        match &self.values {
987            DataValues::Points(samples)
988            | DataValues::Scalars(samples)
989            | DataValues::Similarity(samples) => {
990                check_samples(kind, samples, &time_ok)?;
991            }
992            DataValues::Words(words) => {
993                if words.len() > MAX_DATA_WORDS {
994                    return Err(DataProblem::TooManyItems);
995                }
996                for (index, word) in words.iter().enumerate() {
997                    let ordered = index == 0 || {
998                        let before = &words[index - 1];
999                        (before.start, before.end) <= (word.start, word.end)
1000                    };
1001                    if !valid_word(word) || !ordered {
1002                        return Err(DataProblem::InvalidItem { index });
1003                    }
1004                    time_ok(word.start)?;
1005                    time_ok(word.end)?;
1006                }
1007            }
1008            DataValues::Intervals(intervals) => {
1009                if intervals.len() > MAX_DATA_INTERVALS {
1010                    return Err(DataProblem::TooManyItems);
1011                }
1012                for (index, interval) in intervals.iter().enumerate() {
1013                    let ordered = index == 0 || {
1014                        let before = &intervals[index - 1];
1015                        (before.start, before.end) <= (interval.start, interval.end)
1016                    };
1017                    if !valid_interval(interval) || !ordered {
1018                        return Err(DataProblem::InvalidItem { index });
1019                    }
1020                    time_ok(interval.start)?;
1021                    time_ok(interval.end)?;
1022                }
1023            }
1024        }
1025        Ok(())
1026    }
1027}
1028
1029fn check_samples(
1030    kind: DataKind,
1031    samples: &DataSamples,
1032    time_ok: &dyn Fn(MediaTime) -> Result<(), DataProblem>,
1033) -> Result<(), DataProblem> {
1034    let arity = kind.arity().unwrap_or(1);
1035    let channels = if kind == DataKind::Similarity {
1036        1
1037    } else {
1038        if samples.channels.is_empty() || samples.channels.len() > MAX_DATA_CHANNELS {
1039            return Err(DataProblem::ChannelCount);
1040        }
1041        for (index, name) in samples.channels.iter().enumerate() {
1042            if name.is_empty() || !valid_label(name) || samples.channels[..index].contains(name) {
1043                return Err(DataProblem::ChannelName);
1044            }
1045        }
1046        samples.channels.len()
1047    };
1048    if samples.values.len() > MAX_DATA_VALUES {
1049        return Err(DataProblem::TooManyValues);
1050    }
1051    let expected = samples
1052        .times
1053        .len()
1054        .checked_mul(channels * arity)
1055        .ok_or(DataProblem::ValueCount)?;
1056    if samples.values.len() != expected {
1057        return Err(DataProblem::ValueCount);
1058    }
1059    for (index, time) in samples.times.iter().enumerate() {
1060        if index > 0 && samples.times[index - 1] >= *time {
1061            return Err(DataProblem::TimesNotAscending);
1062        }
1063        time_ok(*time)?;
1064    }
1065    // A lost marker covers a whole channel of a sample: all of its components or none.
1066    for (group, values) in samples.values.chunks_exact(arity).enumerate() {
1067        let lost = values[0].is_none();
1068        for (component, value) in values.iter().enumerate() {
1069            let index = group * arity + component;
1070            let ok = match value {
1071                None => lost,
1072                Some(value) => !lost && value_in_bounds(kind, component, *value),
1073            };
1074            if !ok {
1075                return Err(DataProblem::InvalidValue { index });
1076            }
1077        }
1078    }
1079    Ok(())
1080}
1081
1082impl DataBinding {
1083    /// Checks the fields that need no project: finite offset and a usable remap.
1084    pub(crate) fn fields_valid(&self) -> bool {
1085        self.offset
1086            .is_none_or(|offset| offset.iter().all(|value| value.is_finite()))
1087            && self.remap.is_none_or(|remap| remap.is_valid())
1088    }
1089}