Skip to main content

xrack_runtime/
media.rs

1//! Host-independent media state shared by compiled and interpreted components.
2
3use crate::{Node, Property, Value};
4use std::{
5    cell::{Cell, RefCell},
6    collections::BTreeMap,
7    path::{Path, PathBuf},
8    rc::Rc,
9    sync::Arc,
10    time::{Duration, Instant},
11};
12
13/// One tightly packed, straight-alpha video image shared by scene snapshots.
14#[derive(Clone)]
15pub struct MediaFrame(Arc<([u32; 2], Vec<u8>)>);
16
17impl MediaFrame {
18    pub fn new(size: [u32; 2], rgba: Vec<u8>) -> Option<Self> {
19        let [width, height] = size;
20        let bytes = (width as usize)
21            .checked_mul(height as usize)?
22            .checked_mul(4)?;
23        (width > 0 && height > 0 && bytes == rgba.len()).then(|| Self(Arc::new((size, rgba))))
24    }
25    pub fn size(&self) -> [u32; 2] {
26        self.0.0
27    }
28    pub fn rgba(&self) -> &[u8] {
29        &self.0.1
30    }
31}
32
33impl PartialEq for MediaFrame {
34    fn eq(&self, other: &Self) -> bool {
35        Arc::ptr_eq(&self.0, &other.0)
36    }
37}
38
39impl std::fmt::Debug for MediaFrame {
40    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
41        f.debug_struct("MediaFrame")
42            .field("size", &self.size())
43            .finish_non_exhaustive()
44    }
45}
46
47#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
48pub enum MediaStatus {
49    #[default]
50    Empty,
51    Loading,
52    Seeking,
53    Buffering,
54    Paused,
55    Playing,
56    Stopped,
57    Ended,
58    Failed,
59}
60impl MediaStatus {
61    pub fn as_str(self) -> &'static str {
62        match self {
63            Self::Empty => "empty",
64            Self::Loading => "loading",
65            Self::Seeking => "seeking",
66            Self::Buffering => "buffering",
67            Self::Paused => "paused",
68            Self::Playing => "playing",
69            Self::Stopped => "stopped",
70            Self::Ended => "ended",
71            Self::Failed => "failed",
72        }
73    }
74}
75
76#[derive(Clone, Debug, PartialEq)]
77pub struct MediaOptions {
78    pub playback_rate: f64,
79    pub network_bandwidth: u64,
80    pub loops: i64,
81    pub audio_track: i64,
82    pub subtitle_track: i64,
83    pub subtitle_file: Option<PathBuf>,
84}
85
86impl Default for MediaOptions {
87    fn default() -> Self {
88        Self {
89            playback_rate: 1.0,
90            network_bandwidth: 0,
91            loops: 1,
92            audio_track: -1,
93            subtitle_track: -1,
94            subtitle_file: None,
95        }
96    }
97}
98
99#[derive(Clone, Debug, Default, PartialEq)]
100pub struct MediaState {
101    pub frame: Option<MediaFrame>,
102    pub position: f64,
103    pub duration: f64,
104    pub playing: bool,
105    pub ready: bool,
106    pub ended: bool,
107    pub error: String,
108    pub status: MediaStatus,
109    pub seekable: bool,
110    pub live: bool,
111    pub seek_start: f64,
112    pub seek_end: f64,
113    pub at_live_edge: bool,
114    pub has_audio: bool,
115    pub has_video: bool,
116    pub audio_tracks: i64,
117    pub subtitle_tracks: i64,
118    pub title: String,
119    pub subtitle: String,
120    pub audio_error: String,
121    pub subtitle_error: String,
122    pub buffer_progress: f64,
123    pub bitrate: i64,
124}
125
126#[derive(Clone, Copy, Debug, PartialEq)]
127pub enum MediaCommand {
128    Play,
129    Pause,
130    Stop,
131    Seek(f64),
132    GoLive,
133}
134
135pub trait MediaSession {
136    fn command(&mut self, command: MediaCommand);
137    fn set_volume(&mut self, volume: f64);
138    fn configure(&mut self, _options: &MediaOptions) {}
139    fn sample(&mut self, now: Instant) -> MediaState;
140    fn active(&self) -> bool;
141
142    fn poll_interval(&self) -> Duration {
143        Duration::from_millis(15)
144    }
145}
146
147type Factory = fn(&Path, bool, f64) -> Result<Box<dyn MediaSession>, String>;
148type SoundFactory = fn(&Path, f64) -> Result<Box<dyn MediaSession>, String>;
149thread_local! {
150    static FACTORY: Cell<Option<Factory>> = const { Cell::new(None) };
151    static SOUND_FACTORY: Cell<Option<SoundFactory>> = const { Cell::new(None) };
152}
153
154pub fn register_media_backend(factory: Factory) {
155    FACTORY.set(Some(factory));
156}
157
158/// Register the preloaded sound effect backend for this UI thread.
159#[doc(hidden)]
160pub fn register_sound_backend(factory: SoundFactory) {
161    SOUND_FACTORY.set(Some(factory));
162}
163
164/// Open a media session using the backend installed for this UI thread.
165#[doc(hidden)]
166pub fn open_media_session(
167    path: &Path,
168    autoplay: bool,
169    volume: f64,
170) -> Result<Box<dyn MediaSession>, String> {
171    FACTORY
172        .get()
173        .ok_or_else(|| "Media playback requires a media-enabled host".to_owned())?(
174        path, autoplay, volume,
175    )
176}
177
178#[doc(hidden)]
179#[derive(Default)]
180pub struct MediaSlot {
181    state: Property<MediaState>,
182    commands: RefCell<Vec<MediaCommand>>,
183}
184
185impl MediaSlot {
186    pub fn position(&self) -> f64 {
187        self.state.get(MediaState::default).position
188    }
189    pub fn duration(&self) -> f64 {
190        self.state.get(MediaState::default).duration
191    }
192    pub fn playing(&self) -> bool {
193        self.state.get(MediaState::default).playing
194    }
195    pub fn ready(&self) -> bool {
196        self.state.get(MediaState::default).ready
197    }
198    pub fn ended(&self) -> bool {
199        self.state.get(MediaState::default).ended
200    }
201    pub fn error(&self) -> String {
202        self.state.get(MediaState::default).error
203    }
204
205    pub fn status(&self) -> String {
206        self.state.get(MediaState::default).status.as_str().into()
207    }
208    pub fn seekable(&self) -> bool {
209        self.state.get(MediaState::default).seekable
210    }
211    pub fn live(&self) -> bool {
212        self.state.get(MediaState::default).live
213    }
214    pub fn seek_start(&self) -> f64 {
215        self.state.get(MediaState::default).seek_start
216    }
217    pub fn seek_end(&self) -> f64 {
218        self.state.get(MediaState::default).seek_end
219    }
220    pub fn at_live_edge(&self) -> bool {
221        self.state.get(MediaState::default).at_live_edge
222    }
223    pub fn has_audio(&self) -> bool {
224        self.state.get(MediaState::default).has_audio
225    }
226    pub fn has_video(&self) -> bool {
227        self.state.get(MediaState::default).has_video
228    }
229    pub fn audio_tracks(&self) -> i64 {
230        self.state.get(MediaState::default).audio_tracks
231    }
232    pub fn subtitle_tracks(&self) -> i64 {
233        self.state.get(MediaState::default).subtitle_tracks
234    }
235    pub fn media_title(&self) -> String {
236        self.state.get(MediaState::default).title
237    }
238    pub fn subtitle(&self) -> String {
239        self.state.get(MediaState::default).subtitle
240    }
241    pub fn audio_error(&self) -> String {
242        self.state.get(MediaState::default).audio_error
243    }
244
245    pub fn subtitle_error(&self) -> String {
246        self.state.get(MediaState::default).subtitle_error
247    }
248    pub fn buffer_progress(&self) -> f64 {
249        self.state.get(MediaState::default).buffer_progress
250    }
251
252    pub fn bitrate(&self) -> i64 {
253        self.state.get(MediaState::default).bitrate
254    }
255
256    pub fn read(&self, name: &str) -> Option<Value> {
257        Some(match name {
258            "position" => self.position().into(),
259            "duration" => self.duration().into(),
260            "playing" => self.playing().into(),
261            "ready" => self.ready().into(),
262            "ended" => self.ended().into(),
263            "error" => self.error().into(),
264            "status" => self.status().into(),
265            "seekable" => self.seekable().into(),
266            "live" => self.live().into(),
267            "seek-start" => self.seek_start().into(),
268            "seek-end" => self.seek_end().into(),
269            "at-live-edge" => self.at_live_edge().into(),
270            "has-audio" => self.has_audio().into(),
271            "has-video" => self.has_video().into(),
272            "audio-tracks" => self.audio_tracks().into(),
273            "subtitle-tracks" => self.subtitle_tracks().into(),
274            "media-title" => self.media_title().into(),
275            "subtitle" => self.subtitle().into(),
276            "audio-error" => self.audio_error().into(),
277            "subtitle-error" => self.subtitle_error().into(),
278            "buffer-progress" => self.buffer_progress().into(),
279            "bitrate" => self.bitrate().into(),
280            _ => return None,
281        })
282    }
283
284    pub fn command(&self, command: MediaCommand) {
285        self.commands.borrow_mut().push(command);
286    }
287
288    pub fn populate(self: &Rc<Self>, node: &mut Node, file: &str) {
289        let state = self.state.get(MediaState::default);
290        node.media_frame = state.frame;
291        let source = node.text("source").unwrap_or_default();
292        let path = if source.starts_with("https://") || source.starts_with("http://") {
293            Some(PathBuf::from(source))
294        } else {
295            local_source(file, source)
296        };
297        let rate = node.number("playback-rate").unwrap_or(1.0);
298        let volume = node.number("volume").unwrap_or(1.0);
299        node.media = Some(MediaRegistration {
300            slot: self.clone(),
301            path,
302            sound_effect: false,
303            autoplay: node.boolean("autoplay", false),
304            options: MediaOptions {
305                playback_rate: if rate.is_finite() {
306                    rate.clamp(0.25, 4.0)
307                } else {
308                    1.0
309                },
310                network_bandwidth: node
311                    .int("network-bandwidth")
312                    .unwrap_or(0)
313                    .clamp(0, 1_000_000_000) as u64,
314                loops: node.int("loops").unwrap_or(1).max(-1),
315                audio_track: node.int("audio-track").unwrap_or(-1),
316                subtitle_track: node.int("subtitle-track").unwrap_or(-1),
317                subtitle_file: node
318                    .text("subtitle-file")
319                    .and_then(|source| local_source(file, source)),
320            },
321            volume: effective_volume(volume, node.boolean("muted", false)),
322        });
323    }
324
325    pub fn sound_effect(
326        self: &Rc<Self>,
327        file: &str,
328        source: &str,
329        volume: f64,
330        muted: bool,
331    ) -> MediaRegistration {
332        MediaRegistration {
333            slot: self.clone(),
334            path: local_source(file, source),
335            sound_effect: true,
336            autoplay: false,
337            volume: effective_volume(volume, muted),
338            options: MediaOptions::default(),
339        }
340    }
341}
342
343fn effective_volume(volume: f64, muted: bool) -> f64 {
344    if muted || !volume.is_finite() {
345        0.0
346    } else {
347        volume.clamp(0.0, 1.0)
348    }
349}
350
351fn local_source(file: &str, source: &str) -> Option<PathBuf> {
352    if source.is_empty() {
353        return None;
354    }
355    let path = Path::new(source);
356    Some(Path::new(file).parent().unwrap_or(Path::new("")).join(path))
357}
358
359#[derive(Clone)]
360#[doc(hidden)]
361pub struct MediaRegistration {
362    slot: Rc<MediaSlot>,
363    path: Option<PathBuf>,
364    sound_effect: bool,
365    autoplay: bool,
366    volume: f64,
367    options: MediaOptions,
368}
369
370impl MediaRegistration {
371    fn open(&self, path: &Path) -> Result<Box<dyn MediaSession>, String> {
372        if self.sound_effect {
373            let open = SOUND_FACTORY
374                .get()
375                .ok_or_else(|| "SoundEffect requires a media-enabled host".to_owned())?;
376            open(path, self.volume)
377        } else {
378            open_media_session(path, self.autoplay, self.volume)
379        }
380    }
381
382    pub fn key(&self) -> usize {
383        Rc::as_ptr(&self.slot) as usize
384    }
385}
386
387impl PartialEq for MediaRegistration {
388    fn eq(&self, other: &Self) -> bool {
389        Rc::ptr_eq(&self.slot, &other.slot)
390            && self.path == other.path
391            && self.sound_effect == other.sound_effect
392            && self.autoplay == other.autoplay
393            && self.volume == other.volume
394            && self.options == other.options
395    }
396}
397
398impl std::fmt::Debug for MediaRegistration {
399    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
400        f.debug_struct("MediaRegistration")
401            .field("path", &self.path)
402            .finish_non_exhaustive()
403    }
404}
405
406struct Entry {
407    registration: MediaRegistration,
408    session: Option<Box<dyn MediaSession>>,
409}
410
411#[doc(hidden)]
412#[derive(Default)]
413pub struct MediaQueue {
414    entries: BTreeMap<usize, Entry>,
415    changed: bool,
416}
417
418impl MediaQueue {
419    pub fn sync<'a>(
420        &mut self,
421        registrations: impl IntoIterator<Item = &'a MediaRegistration>,
422    ) -> bool {
423        let mut changed = false;
424        let mut old = std::mem::take(&mut self.entries);
425        for registration in registrations {
426            let key = Rc::as_ptr(&registration.slot) as usize;
427            let previous = old.remove(&key);
428            let mut entry = match previous {
429                Some(entry)
430                    if entry.registration.path == registration.path
431                        && entry.registration.sound_effect == registration.sound_effect =>
432                {
433                    entry
434                }
435                _ => {
436                    // Keep commands from the current UI turn for the newly bound source.
437                    // A play already delivered to the previous session ends with that session.
438                    let mut state = MediaState::default();
439                    let session =
440                        registration
441                            .path
442                            .as_ref()
443                            .and_then(|path| match registration.open(path) {
444                                Ok(mut session) => {
445                                    state.status = MediaStatus::Loading;
446                                    session.configure(&registration.options);
447                                    Some(session)
448                                }
449                                Err(error) => {
450                                    state.error = error;
451                                    state.status = MediaStatus::Failed;
452                                    None
453                                }
454                            });
455                    changed |= publish(&registration.slot, state);
456                    Entry {
457                        registration: registration.clone(),
458                        session,
459                    }
460                }
461            };
462            if entry.registration.volume != registration.volume
463                && let Some(session) = &mut entry.session
464            {
465                session.set_volume(registration.volume);
466            }
467            if entry.registration.options != registration.options
468                && let Some(session) = &mut entry.session
469            {
470                session.configure(&registration.options);
471            }
472            entry.registration = registration.clone();
473            self.entries.insert(key, entry);
474        }
475        for (_, entry) in old {
476            entry.registration.slot.commands.take();
477            changed |= publish(&entry.registration.slot, MediaState::default());
478        }
479        self.changed |= changed;
480        changed
481    }
482
483    pub fn advance(&mut self, now: Instant) -> bool {
484        let mut changed = std::mem::take(&mut self.changed);
485        for entry in self.entries.values_mut() {
486            let commands = entry.registration.slot.commands.take();
487            if let Some(session) = &mut entry.session {
488                for command in commands {
489                    session.command(command);
490                }
491                changed |= publish(&entry.registration.slot, session.sample(now));
492            }
493        }
494        changed
495    }
496
497    pub fn deadline(&self, now: Instant) -> Option<Instant> {
498        if self.changed {
499            return Some(now);
500        }
501        self.entries
502            .values()
503            .filter_map(|entry| {
504                if !entry.registration.slot.commands.borrow().is_empty() {
505                    Some(now)
506                } else {
507                    entry
508                        .session
509                        .as_ref()
510                        .filter(|session| session.active())
511                        .map(|session| now + session.poll_interval())
512                }
513            })
514            .min()
515    }
516}
517
518fn publish(slot: &MediaSlot, state: MediaState) -> bool {
519    if slot.state.get(MediaState::default) == state {
520        return false;
521    }
522    slot.state.set(state);
523    true
524}