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    AudioCodecPolicy, 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<AudioCodecPolicy>,
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    /// Output video codec: `av1` (default), `h264`, or `h265`. `None` = av1.
58    pub video_codec: Option<crate::spec::VideoCodecPolicy>,
59}
60
61impl TranscodeSettings {
62    /// Build an [`OutputSpec`] from these settings against a source resolution.
63    /// This is the **single** spec-building implementation for all surfaces.
64    pub fn into_spec(self, src_w: u32, src_h: u32) -> Result<OutputSpec> {
65        let quality = Quality {
66            crf: self.crf,
67            speed_preset: self.speed,
68            ..Default::default()
69        };
70
71        let rungs: Vec<Rung> = if !self.rungs.is_empty() {
72            self.rungs
73                .iter()
74                .map(|&(w, h)| Rung::new(w, h).with_quality(quality.clone()))
75                .collect()
76        } else if self.ladder {
77            crate::ladder::standard_ladder(src_w, src_h, self.max_short_side)
78                .into_iter()
79                .map(|r| r.with_quality(quality.clone()))
80                .collect()
81        } else {
82            // Single rung at the requested size, else the source — even-aligned
83            // (AV1 4:2:0 needs even dimensions).
84            let w = self.width.unwrap_or(src_w) & !1;
85            let h = self.height.unwrap_or(src_h) & !1;
86            if w == 0 || h == 0 {
87                bail!("source resolution unknown ({src_w}x{src_h}); set explicit rungs or width/height");
88            }
89            vec![Rung::new(w, h).with_quality(quality.clone())]
90        };
91        if rungs.is_empty() {
92            bail!("no rungs to produce");
93        }
94
95        let mut spec = match self.mode.unwrap_or(Mode::Single) {
96            Mode::Hls => OutputSpec::hls(rungs, self.segment_seconds.unwrap_or(4.0)),
97            Mode::Single => OutputSpec::single_file(rungs),
98        };
99
100        if let Some(a) = self.audio {
101            spec.audio = a;
102        }
103        spec.max_frame_rate = self.max_fps;
104        if let Some(c) = self.color {
105            spec = spec.with_color(c);
106        }
107        if let Some(b) = self.bit_depth {
108            spec = spec.with_bit_depth(b);
109        }
110        if let Some(s) = self.seam {
111            spec = spec.chunk_seam_mode(s);
112        }
113
114        // GPU policy precedence: pinned index > vendor family > single > all.
115        spec = if let Some(idx) = self.gpu {
116            spec.encode_policy(EncodePolicy::SingleGpu(Some(idx)))
117        } else if let Some(fam) = self.gpu_family {
118            spec.encode_policy(EncodePolicy::Family(fam))
119        } else if self.single_gpu {
120            spec.encode_policy(EncodePolicy::SingleGpu(None))
121        } else {
122            spec.encode_policy(EncodePolicy::AllGpus)
123        };
124        spec = spec.decode_gpu(self.decode_gpu);
125        spec = spec.with_filters(self.filters);
126        if let Some(c) = self.video_codec {
127            spec = spec.with_video_codec(c);
128        }
129
130        spec.validate().context("invalid output spec")?;
131        Ok(spec)
132    }
133
134    /// Apply one `key=value` setting (the IPC header / generic string form).
135    /// Keys mirror the CLI flags. Unknown keys error.
136    pub fn apply_kv(&mut self, key: &str, val: &str) -> Result<()> {
137        match key {
138            "mode" => self.mode = Some(parse_mode(val)?),
139            "rung" | "rungs" => {
140                for r in val.split(',').map(str::trim).filter(|s| !s.is_empty()) {
141                    self.rungs.push(parse_rung(r)?);
142                }
143            }
144            "ladder" => self.ladder = parse_bool(val),
145            "max-short-side" => self.max_short_side = Some(val.parse().context("max-short-side")?),
146            "segment-seconds" => self.segment_seconds = Some(val.parse().context("segment-seconds")?),
147            "crf" => self.crf = Some(val.parse().context("crf")?),
148            "speed" => self.speed = Some(val.parse().context("speed")?),
149            "audio" => self.audio = Some(parse_audio(val)?),
150            "color" => self.color = Some(parse_color(val)?),
151            "bit-depth" | "pixel-format" => self.bit_depth = Some(parse_bit_depth(val)?),
152            "seam" => self.seam = Some(parse_seam(val)?),
153            "max-fps" => self.max_fps = Some(val.parse().context("max-fps")?),
154            "gpu" => self.gpu = Some(val.parse().context("gpu")?),
155            "gpu-family" => self.gpu_family = Some(parse_gpu_family(val)?),
156            "single-gpu" => self.single_gpu = parse_bool(val),
157            "decode-gpu" => self.decode_gpu = Some(val.parse().context("decode-gpu")?),
158            "width" => self.width = Some(val.parse().context("width")?),
159            "height" => self.height = Some(val.parse().context("height")?),
160            "filter" => self.filters = codec::filter::parse_chain(val)?,
161            "codec" => self.video_codec = Some(parse_video_codec(val)?),
162            o => bail!(
163                "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/codec)"
164            ),
165        }
166        Ok(())
167    }
168
169    /// Parse a whole `key=value key=value …` line into settings.
170    pub fn parse_kv_line(line: &str) -> Result<Self> {
171        let mut s = Self::default();
172        for tok in line.split_whitespace() {
173            let (k, v) = tok
174                .split_once('=')
175                .with_context(|| format!("bad setting '{tok}' (expected key=value)"))?;
176            s.apply_kv(k, v)?;
177        }
178        Ok(s)
179    }
180
181    pub fn is_empty(&self) -> bool {
182        self.mode.is_none()
183            && self.rungs.is_empty()
184            && !self.ladder
185            && self.max_short_side.is_none()
186            && self.segment_seconds.is_none()
187            && self.crf.is_none()
188            && self.speed.is_none()
189            && self.audio.is_none()
190            && self.color.is_none()
191            && self.bit_depth.is_none()
192            && self.seam.is_none()
193            && self.max_fps.is_none()
194            && self.gpu.is_none()
195            && self.gpu_family.is_none()
196            && !self.single_gpu
197            && self.decode_gpu.is_none()
198            && self.width.is_none()
199            && self.height.is_none()
200            && self.filters.is_empty()
201            && self.video_codec.is_none()
202    }
203}
204
205// ── central string vocabulary (the single source of truth) ──────────────
206
207pub fn parse_mode(s: &str) -> Result<Mode> {
208    match s {
209        "single" => Ok(Mode::Single),
210        "hls" => Ok(Mode::Hls),
211        o => bail!("mode must be single|hls, got '{o}'"),
212    }
213}
214
215pub fn parse_audio(s: &str) -> Result<AudioCodecPolicy> {
216    match s {
217        "auto" => Ok(AudioCodecPolicy::Auto),
218        "opus" => Ok(AudioCodecPolicy::ForceOpus),
219        "drop" => Ok(AudioCodecPolicy::Drop),
220        o => bail!("audio must be auto|opus|drop, got '{o}'"),
221    }
222}
223
224pub fn parse_color(s: &str) -> Result<ColorPolicy> {
225    match s {
226        "sdr" => Ok(ColorPolicy::TonemapToSdr),
227        "hdr10" => Ok(ColorPolicy::Hdr10),
228        "hlg" => Ok(ColorPolicy::Hlg),
229        "passthrough" => Ok(ColorPolicy::Passthrough),
230        o => bail!("color must be sdr|hdr10|hlg|passthrough, got '{o}'"),
231    }
232}
233
234pub fn parse_bit_depth(s: &str) -> Result<BitDepth> {
235    match s {
236        "auto" => Ok(BitDepth::Auto),
237        "8bit" => Ok(BitDepth::EightBit),
238        "10bit" => Ok(BitDepth::TenBit),
239        o => bail!("bit-depth must be auto|8bit|10bit, got '{o}'"),
240    }
241}
242
243pub fn parse_seam(s: &str) -> Result<ChunkSeamMode> {
244    match s {
245        "parallel" => Ok(ChunkSeamMode::Parallel),
246        "constqp" => Ok(ChunkSeamMode::ParallelConstQp),
247        "serial" => Ok(ChunkSeamMode::Serial),
248        o => bail!("seam must be parallel|constqp|serial, got '{o}'"),
249    }
250}
251
252pub fn parse_video_codec(s: &str) -> Result<crate::spec::VideoCodecPolicy> {
253    use crate::spec::VideoCodecPolicy;
254    match s.to_ascii_lowercase().as_str() {
255        "av1" | "av01" => Ok(VideoCodecPolicy::Av1),
256        "h264" | "avc" | "avc1" | "x264" => Ok(VideoCodecPolicy::H264),
257        "h265" | "hevc" | "hvc1" | "x265" => Ok(VideoCodecPolicy::H265),
258        o => bail!("codec must be av1|h264|h265, got '{o}'"),
259    }
260}
261
262pub fn parse_gpu_family(s: &str) -> Result<GpuFamily> {
263    match s {
264        "nvidia" => Ok(GpuFamily::Nvidia),
265        "amd" => Ok(GpuFamily::Amd),
266        "intel" => Ok(GpuFamily::Intel),
267        o => bail!("gpu-family must be nvidia|amd|intel, got '{o}'"),
268    }
269}
270
271/// Parse a `WxH` rung, e.g. `1280x720`.
272pub fn parse_rung(s: &str) -> Result<(u32, u32)> {
273    let (w, h) = s
274        .split_once(['x', 'X'])
275        .with_context(|| format!("rung must be WxH, e.g. 1280x720 (got '{s}')"))?;
276    Ok((
277        w.trim().parse().context("rung width")?,
278        h.trim().parse().context("rung height")?,
279    ))
280}
281
282fn parse_bool(s: &str) -> bool {
283    matches!(s.to_ascii_lowercase().as_str(), "1" | "true" | "yes" | "on" | "y" | "t")
284}
285
286#[cfg(test)]
287mod tests {
288    use super::*;
289
290    #[test]
291    fn defaults_to_single_source_resolution() {
292        let spec = TranscodeSettings::default().into_spec(1280, 720).unwrap();
293        assert!(matches!(spec.mode, crate::spec::OutputMode::SingleFile));
294        assert_eq!(spec.rungs.len(), 1);
295        assert_eq!((spec.rungs[0].width, spec.rungs[0].height), (1280, 720));
296    }
297
298    #[test]
299    fn explicit_rungs_and_hls() {
300        let s = TranscodeSettings {
301            mode: Some(Mode::Hls),
302            rungs: vec![(1920, 1080), (1280, 720), (640, 360)],
303            segment_seconds: Some(6.0),
304            crf: Some(28),
305            ..Default::default()
306        };
307        let spec = s.into_spec(1920, 1080).unwrap();
308        assert!(matches!(spec.mode, crate::spec::OutputMode::Hls { .. }));
309        assert_eq!(spec.rungs.len(), 3);
310        assert_eq!(spec.rungs[1].quality.crf, Some(28));
311    }
312
313    #[test]
314    fn width_height_scales_single_rung() {
315        let s = TranscodeSettings {
316            width: Some(640),
317            height: Some(360),
318            ..Default::default()
319        };
320        let spec = s.into_spec(1280, 720).unwrap();
321        assert_eq!((spec.rungs[0].width, spec.rungs[0].height), (640, 360));
322    }
323
324    #[test]
325    fn kv_line_parses_all_common_keys() {
326        let s = TranscodeSettings::parse_kv_line(
327            "mode=hls rung=1280x720,640x360 crf=30 audio=opus gpu=1 max-fps=30",
328        )
329        .unwrap();
330        assert_eq!(s.mode, Some(Mode::Hls));
331        assert_eq!(s.rungs, vec![(1280, 720), (640, 360)]);
332        assert_eq!(s.crf, Some(30));
333        assert_eq!(s.audio, Some(AudioCodecPolicy::ForceOpus));
334        assert_eq!(s.gpu, Some(1));
335        assert_eq!(s.max_fps, Some(30.0));
336    }
337
338    #[test]
339    fn kv_rejects_unknown_key() {
340        assert!(TranscodeSettings::parse_kv_line("bogus=1").is_err());
341        assert!(TranscodeSettings::parse_kv_line("crf=notanumber").is_err());
342    }
343
344    #[test]
345    fn parsers_reject_garbage() {
346        assert!(parse_color("ultrahd").is_err());
347        assert!(parse_rung("notarung").is_err());
348        assert!(parse_rung("1280x720").is_ok());
349    }
350}
rivet/settings.rs

rivet/
settings.rs
