rivet/
settings.rs

1//! One canonical definition of the transcode "knobs", shared by every
2//! front-end — the CLI (`transcode` / `pipe`), the HTTP API, and the IPC
3//! socket. Each surface parses its own syntax (clap flags / JSON / query
4//! string / `key=value`) into a [`TranscodeSettings`], then calls
5//! [`TranscodeSettings::into_spec`]. Add a new option **once** here (a field +
6//! a line in `into_spec` + a `parse_*` arm) and every surface picks it up,
7//! instead of maintaining three copies of the spec-building logic.
8
9use anyhow::{Context, Result, bail};
10
11use crate::spec::{
12    AudioPolicy, BitDepth, ChunkSeamMode, ColorPolicy, EncodePolicy, GpuFamily, OutputSpec, Quality,
13    Rung,
14};
15
16/// Output mode.
17#[derive(Debug, Clone, Copy, PartialEq, Eq)]
18pub enum Mode {
19    Single,
20    Hls,
21}
22
23/// Every optional transcode knob, surface-agnostic. All-`None`/empty is "use the
24/// defaults" (source-resolution single file, AV1 + audio passthrough, SDR).
25#[derive(Debug, Clone, Default)]
26pub struct TranscodeSettings {
27    pub mode: Option<Mode>,
28    /// Explicit rungs as `(width, height)`. Wins over `ladder` / `width`.
29    pub rungs: Vec<(u32, u32)>,
30    /// Derive a standard ABR ladder from the source.
31    pub ladder: bool,
32    pub max_short_side: Option<u32>,
33    pub segment_seconds: Option<f32>,
34    pub crf: Option<u8>,
35    pub speed: Option<u8>,
36    pub audio: Option<AudioPolicy>,
37    pub color: Option<ColorPolicy>,
38    pub bit_depth: Option<BitDepth>,
39    pub seam: Option<ChunkSeamMode>,
40    pub max_fps: Option<f64>,
41    /// Pin encode to one GPU index.
42    pub gpu: Option<u32>,
43    /// Restrict encode to one vendor family.
44    pub gpu_family: Option<GpuFamily>,
45    /// Use a single GPU (serial), the first available.
46    pub single_gpu: bool,
47    /// Pin the decode pump to a GPU index.
48    pub decode_gpu: Option<u32>,
49    /// Single-output width/height (the `pipe`/`ipc` scaling knobs). Used only
50    /// when neither `rungs` nor `ladder` is set; defaults to the source size.
51    pub width: Option<u32>,
52    pub height: Option<u32>,
53    /// Video filter chain (crop/pad/flip/rotate/grayscale) applied before
54    /// per-rung scaling. The canonical structured form; string surfaces parse
55    /// `codec::filter::parse_chain` at the edge.
56    pub filters: Vec<codec::filter::VideoFilter>,
57}
58
59impl TranscodeSettings {
60    /// Build an [`OutputSpec`] from these settings against a source resolution.
61    /// This is the **single** spec-building implementation for all surfaces.
62    pub fn into_spec(self, src_w: u32, src_h: u32) -> Result<OutputSpec> {
63        let quality = Quality {
64            crf: self.crf,
65            speed_preset: self.speed,
66            ..Default::default()
67        };
68
69        let rungs: Vec<Rung> = if !self.rungs.is_empty() {
70            self.rungs
71                .iter()
72                .map(|&(w, h)| Rung::new(w, h).with_quality(quality.clone()))
73                .collect()
74        } else if self.ladder {
75            crate::ladder::standard_ladder(src_w, src_h, self.max_short_side)
76                .into_iter()
77                .map(|r| r.with_quality(quality.clone()))
78                .collect()
79        } else {
80            // Single rung at the requested size, else the source — even-aligned
81            // (AV1 4:2:0 needs even dimensions).
82            let w = self.width.unwrap_or(src_w) & !1;
83            let h = self.height.unwrap_or(src_h) & !1;
84            if w == 0 || h == 0 {
85                bail!("source resolution unknown ({src_w}x{src_h}); set explicit rungs or width/height");
86            }
87            vec![Rung::new(w, h).with_quality(quality.clone())]
88        };
89        if rungs.is_empty() {
90            bail!("no rungs to produce");
91        }
92
93        let mut spec = match self.mode.unwrap_or(Mode::Single) {
94            Mode::Hls => OutputSpec::hls(rungs, self.segment_seconds.unwrap_or(4.0)),
95            Mode::Single => OutputSpec::single_file(rungs),
96        };
97
98        if let Some(a) = self.audio {
99            spec.audio = a;
100        }
101        spec.max_frame_rate = self.max_fps;
102        if let Some(c) = self.color {
103            spec = spec.with_color(c);
104        }
105        if let Some(b) = self.bit_depth {
106            spec = spec.with_bit_depth(b);
107        }
108        if let Some(s) = self.seam {
109            spec = spec.chunk_seam_mode(s);
110        }
111
112        // GPU policy precedence: pinned index > vendor family > single > all.
113        spec = if let Some(idx) = self.gpu {
114            spec.encode_policy(EncodePolicy::SingleGpu(Some(idx)))
115        } else if let Some(fam) = self.gpu_family {
116            spec.encode_policy(EncodePolicy::Family(fam))
117        } else if self.single_gpu {
118            spec.encode_policy(EncodePolicy::SingleGpu(None))
119        } else {
120            spec.encode_policy(EncodePolicy::AllGpus)
121        };
122        spec = spec.decode_gpu(self.decode_gpu);
123        spec = spec.with_filters(self.filters);
124
125        spec.validate().context("invalid output spec")?;
126        Ok(spec)
127    }
128
129    /// Apply one `key=value` setting (the IPC header / generic string form).
130    /// Keys mirror the CLI flags. Unknown keys error.
131    pub fn apply_kv(&mut self, key: &str, val: &str) -> Result<()> {
132        match key {
133            "mode" => self.mode = Some(parse_mode(val)?),
134            "rung" | "rungs" => {
135                for r in val.split(',').map(str::trim).filter(|s| !s.is_empty()) {
136                    self.rungs.push(parse_rung(r)?);
137                }
138            }
139            "ladder" => self.ladder = parse_bool(val),
140            "max-short-side" => self.max_short_side = Some(val.parse().context("max-short-side")?),
141            "segment-seconds" => self.segment_seconds = Some(val.parse().context("segment-seconds")?),
142            "crf" => self.crf = Some(val.parse().context("crf")?),
143            "speed" => self.speed = Some(val.parse().context("speed")?),
144            "audio" => self.audio = Some(parse_audio(val)?),
145            "color" => self.color = Some(parse_color(val)?),
146            "bit-depth" | "pixel-format" => self.bit_depth = Some(parse_bit_depth(val)?),
147            "seam" => self.seam = Some(parse_seam(val)?),
148            "max-fps" => self.max_fps = Some(val.parse().context("max-fps")?),
149            "gpu" => self.gpu = Some(val.parse().context("gpu")?),
150            "gpu-family" => self.gpu_family = Some(parse_gpu_family(val)?),
151            "single-gpu" => self.single_gpu = parse_bool(val),
152            "decode-gpu" => self.decode_gpu = Some(val.parse().context("decode-gpu")?),
153            "width" => self.width = Some(val.parse().context("width")?),
154            "height" => self.height = Some(val.parse().context("height")?),
155            "filter" => self.filters = codec::filter::parse_chain(val)?,
156            o => bail!(
157                "unknown setting '{o}' (mode/rung/ladder/crf/speed/audio/color/bit-depth/seam/max-fps/gpu/gpu-family/single-gpu/decode-gpu/width/height/filter)"
158            ),
159        }
160        Ok(())
161    }
162
163    /// Parse a whole `key=value key=value …` line into settings.
164    pub fn parse_kv_line(line: &str) -> Result<Self> {
165        let mut s = Self::default();
166        for tok in line.split_whitespace() {
167            let (k, v) = tok
168                .split_once('=')
169                .with_context(|| format!("bad setting '{tok}' (expected key=value)"))?;
170            s.apply_kv(k, v)?;
171        }
172        Ok(s)
173    }
174
175    pub fn is_empty(&self) -> bool {
176        self.mode.is_none()
177            && self.rungs.is_empty()
178            && !self.ladder
179            && self.max_short_side.is_none()
180            && self.segment_seconds.is_none()
181            && self.crf.is_none()
182            && self.speed.is_none()
183            && self.audio.is_none()
184            && self.color.is_none()
185            && self.bit_depth.is_none()
186            && self.seam.is_none()
187            && self.max_fps.is_none()
188            && self.gpu.is_none()
189            && self.gpu_family.is_none()
190            && !self.single_gpu
191            && self.decode_gpu.is_none()
192            && self.width.is_none()
193            && self.height.is_none()
194            && self.filters.is_empty()
195    }
196}
197
198// ── central string vocabulary (the single source of truth) ──────────────
199
200pub fn parse_mode(s: &str) -> Result<Mode> {
201    match s {
202        "single" => Ok(Mode::Single),
203        "hls" => Ok(Mode::Hls),
204        o => bail!("mode must be single|hls, got '{o}'"),
205    }
206}
207
208pub fn parse_audio(s: &str) -> Result<AudioPolicy> {
209    match s {
210        "auto" => Ok(AudioPolicy::Auto),
211        "opus" => Ok(AudioPolicy::ForceOpus),
212        "drop" => Ok(AudioPolicy::Drop),
213        o => bail!("audio must be auto|opus|drop, got '{o}'"),
214    }
215}
216
217pub fn parse_color(s: &str) -> Result<ColorPolicy> {
218    match s {
219        "sdr" => Ok(ColorPolicy::TonemapToSdr),
220        "hdr10" => Ok(ColorPolicy::Hdr10),
221        "hlg" => Ok(ColorPolicy::Hlg),
222        "passthrough" => Ok(ColorPolicy::Passthrough),
223        o => bail!("color must be sdr|hdr10|hlg|passthrough, got '{o}'"),
224    }
225}
226
227pub fn parse_bit_depth(s: &str) -> Result<BitDepth> {
228    match s {
229        "auto" => Ok(BitDepth::Auto),
230        "8bit" => Ok(BitDepth::EightBit),
231        "10bit" => Ok(BitDepth::TenBit),
232        o => bail!("bit-depth must be auto|8bit|10bit, got '{o}'"),
233    }
234}
235
236pub fn parse_seam(s: &str) -> Result<ChunkSeamMode> {
237    match s {
238        "parallel" => Ok(ChunkSeamMode::Parallel),
239        "constqp" => Ok(ChunkSeamMode::ParallelConstQp),
240        "serial" => Ok(ChunkSeamMode::Serial),
241        o => bail!("seam must be parallel|constqp|serial, got '{o}'"),
242    }
243}
244
245pub fn parse_gpu_family(s: &str) -> Result<GpuFamily> {
246    match s {
247        "nvidia" => Ok(GpuFamily::Nvidia),
248        "amd" => Ok(GpuFamily::Amd),
249        "intel" => Ok(GpuFamily::Intel),
250        o => bail!("gpu-family must be nvidia|amd|intel, got '{o}'"),
251    }
252}
253
254/// Parse a `WxH` rung, e.g. `1280x720`.
255pub fn parse_rung(s: &str) -> Result<(u32, u32)> {
256    let (w, h) = s
257        .split_once(['x', 'X'])
258        .with_context(|| format!("rung must be WxH, e.g. 1280x720 (got '{s}')"))?;
259    Ok((
260        w.trim().parse().context("rung width")?,
261        h.trim().parse().context("rung height")?,
262    ))
263}
264
265fn parse_bool(s: &str) -> bool {
266    matches!(s.to_ascii_lowercase().as_str(), "1" | "true" | "yes" | "on" | "y" | "t")
267}
268
269#[cfg(test)]
270mod tests {
271    use super::*;
272
273    #[test]
274    fn defaults_to_single_source_resolution() {
275        let spec = TranscodeSettings::default().into_spec(1280, 720).unwrap();
276        assert!(matches!(spec.mode, crate::spec::OutputMode::SingleFile));
277        assert_eq!(spec.rungs.len(), 1);
278        assert_eq!((spec.rungs[0].width, spec.rungs[0].height), (1280, 720));
279    }
280
281    #[test]
282    fn explicit_rungs_and_hls() {
283        let s = TranscodeSettings {
284            mode: Some(Mode::Hls),
285            rungs: vec![(1920, 1080), (1280, 720), (640, 360)],
286            segment_seconds: Some(6.0),
287            crf: Some(28),
288            ..Default::default()
289        };
290        let spec = s.into_spec(1920, 1080).unwrap();
291        assert!(matches!(spec.mode, crate::spec::OutputMode::Hls { .. }));
292        assert_eq!(spec.rungs.len(), 3);
293        assert_eq!(spec.rungs[1].quality.crf, Some(28));
294    }
295
296    #[test]
297    fn width_height_scales_single_rung() {
298        let s = TranscodeSettings {
299            width: Some(640),
300            height: Some(360),
301            ..Default::default()
302        };
303        let spec = s.into_spec(1280, 720).unwrap();
304        assert_eq!((spec.rungs[0].width, spec.rungs[0].height), (640, 360));
305    }
306
307    #[test]
308    fn kv_line_parses_all_common_keys() {
309        let s = TranscodeSettings::parse_kv_line(
310            "mode=hls rung=1280x720,640x360 crf=30 audio=opus gpu=1 max-fps=30",
311        )
312        .unwrap();
313        assert_eq!(s.mode, Some(Mode::Hls));
314        assert_eq!(s.rungs, vec![(1280, 720), (640, 360)]);
315        assert_eq!(s.crf, Some(30));
316        assert_eq!(s.audio, Some(AudioPolicy::ForceOpus));
317        assert_eq!(s.gpu, Some(1));
318        assert_eq!(s.max_fps, Some(30.0));
319    }
320
321    #[test]
322    fn kv_rejects_unknown_key() {
323        assert!(TranscodeSettings::parse_kv_line("bogus=1").is_err());
324        assert!(TranscodeSettings::parse_kv_line("crf=notanumber").is_err());
325    }
326
327    #[test]
328    fn parsers_reject_garbage() {
329        assert!(parse_color("ultrahd").is_err());
330        assert!(parse_rung("notarung").is_err());
331        assert!(parse_rung("1280x720").is_ok());
332    }
333}
rivet/settings.rs

rivet/
settings.rs
