Skip to main content

hyperframes/core/
protocol.rs

1use serde::{Deserialize, Serialize};
2
3/// The seek protocol contract implemented by compositions (`window.__hf`).
4///
5/// Any web page that wants to be rendered deterministically as video
6/// implements this protocol so the headless engine can advance time
7/// frame-by-frame without clock drift.
8#[derive(Debug, Clone, Serialize, Deserialize)]
9pub struct HfProtocol {
10    /// Total duration of the composition in seconds.
11    pub duration: f64,
12    /// Target frame rate (defaults to 30.0 if not specified).
13    #[serde(default = "default_fps")]
14    pub fps: f64,
15    /// Frame width in pixels.
16    #[serde(default = "default_width")]
17    pub width: u32,
18    /// Frame height in pixels.
19    #[serde(default = "default_height")]
20    pub height: u32,
21    /// Optional media elements that the engine must extract and mix.
22    #[serde(default)]
23    pub media: Vec<HfMediaElement>,
24    /// Optional shader transition metadata.
25    #[serde(default)]
26    pub transitions: Vec<HfTransitionMeta>,
27}
28
29fn default_fps() -> f64 {
30    30.0
31}
32
33fn default_width() -> u32 {
34    1920
35}
36
37fn default_height() -> u32 {
38    1080
39}
40
41impl Default for HfProtocol {
42    fn default() -> Self {
43        Self {
44            duration: 5.0,
45            fps: 30.0,
46            width: 1920,
47            height: 1080,
48            media: Vec::new(),
49            transitions: Vec::new(),
50        }
51    }
52}
53
54/// Declares a `<video>` or `<audio>` media element the engine should handle.
55#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
56pub struct HfMediaElement {
57    /// DOM id of the media element.
58    #[serde(rename = "elementId")]
59    pub element_id: String,
60    /// Source file path or URL.
61    pub src: String,
62    /// Start time in the composition in seconds.
63    #[serde(rename = "startTime")]
64    pub start_time: f64,
65    /// End time in the composition in seconds.
66    #[serde(rename = "endTime")]
67    pub end_time: f64,
68    /// Offset into the media source in seconds (default: 0.0).
69    #[serde(rename = "mediaOffset", default)]
70    pub media_offset: f64,
71    /// Volume multiplier from 0.0 to 1.0 (default: 1.0).
72    #[serde(default = "default_volume")]
73    pub volume: f64,
74    /// Whether this element contains an audio track that should be mixed.
75    #[serde(rename = "hasAudio", default = "default_has_audio")]
76    pub has_audio: bool,
77}
78
79fn default_volume() -> f64 {
80    1.0
81}
82
83fn default_has_audio() -> bool {
84    true
85}
86
87/// Metadata for a shader transition between scenes.
88#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
89pub struct HfTransitionMeta {
90    /// Timestamp in seconds when transition begins.
91    pub time: f64,
92    /// Duration of transition in seconds.
93    pub duration: f64,
94    /// Shader identifier (or CSS crossfade if empty/none).
95    pub shader: Option<String>,
96    /// Easing curve (e.g. "power2.inOut", "linear").
97    #[serde(default = "default_ease")]
98    pub ease: String,
99    /// Scene id the transition starts from.
100    #[serde(rename = "fromScene")]
101    pub from_scene: String,
102    /// Scene id the transition transitions into.
103    #[serde(rename = "toScene")]
104    pub to_scene: String,
105}
106
107fn default_ease() -> String {
108    "power2.inOut".to_string()
109}
110
111/// Seek options passed into `window.__hf.seek(time, options)`.
112#[derive(Debug, Clone, Default, Serialize, Deserialize, PartialEq)]
113pub struct HfSeekOptions {
114    /// Suppress firing user event callbacks during discrete frame seek.
115    #[serde(rename = "suppressEvents", default)]
116    pub suppress_events: bool,
117    /// Sub-frame sampling divisions for motion blur.
118    #[serde(rename = "subFrameDivisions", default)]
119    pub sub_frame_divisions: Option<u32>,
120}
121
122/// Video output format.
123#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
124pub enum VideoFormat {
125    #[default]
126    #[serde(rename = "mp4")]
127    Mp4,
128    #[serde(rename = "mov")]
129    Mov,
130    #[serde(rename = "webm")]
131    Webm,
132    #[serde(rename = "gif")]
133    Gif,
134    #[serde(rename = "png-sequence")]
135    PngSequence,
136}
137
138impl std::str::FromStr for VideoFormat {
139    type Err = String;
140
141    fn from_str(s: &str) -> Result<Self, Self::Err> {
142        match s.to_lowercase().as_str() {
143            "mp4" => Ok(VideoFormat::Mp4),
144            "mov" => Ok(VideoFormat::Mov),
145            "webm" => Ok(VideoFormat::Webm),
146            "gif" => Ok(VideoFormat::Gif),
147            "png" | "png-sequence" => Ok(VideoFormat::PngSequence),
148            other => Err(format!("Unknown video format: {other}")),
149        }
150    }
151}
152
153/// Video codec selection.
154#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
155pub enum VideoCodec {
156    #[default]
157    #[serde(rename = "h264")]
158    H264,
159    #[serde(rename = "h265")]
160    H265,
161    #[serde(rename = "prores")]
162    ProRes,
163    #[serde(rename = "vp9")]
164    Vp9,
165}
166
167impl std::str::FromStr for VideoCodec {
168    type Err = String;
169
170    fn from_str(s: &str) -> Result<Self, Self::Err> {
171        match s.to_lowercase().as_str() {
172            "h264" | "libx264" => Ok(VideoCodec::H264),
173            "h265" | "hevc" | "libx265" => Ok(VideoCodec::H265),
174            "prores" | "prores_ks" => Ok(VideoCodec::ProRes),
175            "vp9" | "libvpx-vp9" => Ok(VideoCodec::Vp9),
176            other => Err(format!("Unknown video codec: {other}")),
177        }
178    }
179}