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