Skip to main content

alpha2_compose/
facts.rs

1//! What compiling needs to know about the files a spec names.
2//!
3//! The compiler reads no files. A binding lists what a spec needs ([`requirements`]), finds
4//! it out (for example with a host's `conform`), and passes it in as [`Facts`].
5
6use std::collections::BTreeMap;
7
8use alpha2_model::MediaFingerprint;
9use alpha2_time::FrameRate;
10use serde::{Deserialize, Serialize};
11
12use crate::spec::{FileKind, MediaItem, Node, VideoSpec};
13
14/// What the compiler knows of the files a spec names, keyed by the path the spec gives.
15#[derive(Clone, Debug, Default, Deserialize, PartialEq, Serialize)]
16#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
17#[serde(deny_unknown_fields)]
18pub struct Facts {
19    /// Media files' shapes and lengths.
20    #[serde(default)]
21    pub media: BTreeMap<String, MediaFacts>,
22    /// Caption files' text.
23    #[serde(default)]
24    pub texts: BTreeMap<String, String>,
25}
26
27/// One media file's shape and length.
28#[derive(Clone, Debug, Default, Deserialize, PartialEq, Serialize)]
29#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
30#[serde(deny_unknown_fields)]
31pub struct MediaFacts {
32    /// Displayed width of its pictures, in pixels.
33    #[serde(default, skip_serializing_if = "Option::is_none")]
34    pub width: Option<u32>,
35    /// Displayed height of its pictures, in pixels.
36    #[serde(default, skip_serializing_if = "Option::is_none")]
37    pub height: Option<u32>,
38    /// Its video's frame rate.
39    #[serde(default, skip_serializing_if = "Option::is_none")]
40    pub frame_rate: Option<FrameRate>,
41    /// Where it ends on its own timeline, in ticks.
42    #[serde(default, skip_serializing_if = "Option::is_none")]
43    pub duration_ticks: Option<i64>,
44    /// Whether it has an audio stream. Required for a video that plays unmuted.
45    #[serde(default, skip_serializing_if = "Option::is_none")]
46    pub has_audio: Option<bool>,
47}
48
49impl MediaFacts {
50    /// The facts a host's fingerprint of the file records, as `conform` reports them.
51    #[must_use]
52    pub fn from_fingerprint(fingerprint: &MediaFingerprint) -> Self {
53        let streams = fingerprint.streams.as_ref();
54        let video = streams.and_then(|streams| streams.video.as_ref());
55        Self {
56            width: video.map(|video| video.width),
57            height: video.map(|video| video.height),
58            frame_rate: video.and_then(|video| video.frame_rate),
59            duration_ticks: fingerprint.duration_ticks,
60            has_audio: Some(streams.is_some_and(|streams| streams.audio.is_some())),
61        }
62    }
63}
64
65/// The files a spec names.
66#[derive(Clone, Debug, Default, Deserialize, PartialEq, Serialize)]
67#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
68#[serde(deny_unknown_fields)]
69pub struct Requirements {
70    /// Media files, each once, in the order the spec first names them.
71    pub media: Vec<RequiredMedia>,
72    /// Caption files, each once, in that order.
73    pub texts: Vec<String>,
74}
75
76/// A media file a spec names.
77#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
78#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
79#[serde(deny_unknown_fields)]
80pub struct RequiredMedia {
81    /// The path as the spec gives it.
82    pub path: String,
83    /// What the compiler takes it to hold, and a host should read it as.
84    pub kind: FileKind,
85}
86
87/// What a file holds by its extension: a still for image formats the host decodes, sound for
88/// audio-only formats, video otherwise. Formats read by extension providers (animated GIF,
89/// SVG, OpenEXR) are not guessed.
90#[must_use]
91pub fn kind_of_path(path: &str) -> FileKind {
92    let name = path.rsplit(['/', '\\']).next().unwrap_or(path);
93    let extension = name
94        .rsplit_once('.')
95        .map(|(_, extension)| extension.to_ascii_lowercase())
96        .unwrap_or_default();
97    match extension.as_str() {
98        "png" | "jpg" | "jpeg" | "webp" | "bmp" | "tif" | "tiff" | "avif" => FileKind::Image,
99        "mp3" | "m4a" | "aac" | "wav" | "flac" | "ogg" | "oga" | "opus" | "aif" | "aiff"
100        | "caf" => FileKind::Audio,
101        _ => FileKind::Video,
102    }
103}
104
105/// The files `spec` names, for a binding to describe before compiling.
106#[must_use]
107pub fn requirements(spec: &VideoSpec) -> Requirements {
108    let mut found = Requirements::default();
109    let nodes = std::iter::once(&spec.body)
110        .chain(&spec.overlays)
111        .chain(&spec.audio);
112    for node in nodes {
113        walk(node, &mut found);
114    }
115    found
116}
117
118/// Lists `path` once. A file first named as sound and later as a picture is listed as the
119/// picture, whose facts serve both uses; any other second kind keeps the first.
120fn add_media(found: &mut Requirements, path: &str, kind: Option<FileKind>) {
121    let kind = kind.unwrap_or_else(|| kind_of_path(path));
122    match found.media.iter_mut().find(|media| media.path == path) {
123        Some(listed) => {
124            if listed.kind == FileKind::Audio && kind != FileKind::Audio {
125                listed.kind = kind;
126            }
127        }
128        None => found.media.push(RequiredMedia {
129            path: path.to_owned(),
130            kind,
131        }),
132    }
133}
134
135fn add_item(found: &mut Requirements, item: &MediaItem) {
136    match item {
137        MediaItem::Path(path) => add_media(found, path, None),
138        MediaItem::Node(node) => walk(node, found),
139    }
140}
141
142fn walk(node: &Node, found: &mut Requirements) {
143    match node {
144        Node::Sequence(sequence) => sequence
145            .children
146            .iter()
147            .for_each(|child| walk(child, found)),
148        Node::Stack(stack) => stack.children.iter().for_each(|child| walk(child, found)),
149        Node::Matte(matte) => {
150            walk(&matte.content, found);
151            walk(&matte.by, found);
152        }
153        Node::Mask(mask) => walk(&mask.content, found),
154        Node::Box(node) => node
155            .children
156            .iter()
157            .for_each(|child| walk(child.node(), found)),
158        Node::Group(group) => {
159            group.children.iter().for_each(|child| walk(child, found));
160            for effect in &group.effects {
161                let Some(spec) =
162                    alpha2_model::builtin_effect(&crate::lower::effect_id(&effect.effect))
163                else {
164                    continue;
165                };
166                for input in spec
167                    .inputs
168                    .iter()
169                    .filter_map(|name| effect.params.get(name))
170                {
171                    if let Ok(node) = serde_json::from_value::<Node>(input.clone()) {
172                        walk(&node, found);
173                    }
174                }
175            }
176        }
177        Node::Grid(grid) => grid.children.iter().for_each(|child| walk(child, found)),
178        Node::Media(media) => add_media(found, &media.path, media.kind),
179        Node::Audio(audio) => add_media(found, &audio.path, Some(FileKind::Audio)),
180        Node::MusicBed(music) => add_media(found, &music.path, Some(FileKind::Audio)),
181        Node::Captions(captions) => {
182            if let Some(file) = &captions.file
183                && !found.texts.contains(file)
184            {
185                found.texts.push(file.clone());
186            }
187        }
188        Node::Slideshow(slideshow) => {
189            slideshow
190                .items
191                .iter()
192                .for_each(|item| add_item(found, item));
193            if let Some(path) = &slideshow.fit_to {
194                add_media(found, path, Some(FileKind::Audio));
195            }
196        }
197        Node::CaptionedVideo(captioned) => {
198            add_item(found, &captioned.video);
199            walk(&Node::Captions((*captioned.captions).clone()), found);
200        }
201        Node::Text(_)
202        | Node::Shape(_)
203        | Node::Color(_)
204        | Node::Layout(_)
205        | Node::Raw(_)
206        | Node::Counter(_) => {}
207    }
208}