Skip to main content

rff/
transcode.rs

1//! Transcoding — the engine side of `ffmpeg`.
2//!
3//! The pipeline is the classic FFmpeg shape:
4//!
5//! ```text
6//!   demuxer ─▶ decoder ─▶ [filters] ─▶ encoder ─▶ muxer
7//!   (input)    (raw frames pass through the middle)      (output)
8//! ```
9//!
10//! [`TranscodeSpec`] is the declarative description of a job — inputs, an
11//! output, and the codecs to use. [`run`] resolves that spec against an
12//! [`Engine`] (finding the demuxer, decoders, encoders, and muxer) and then
13//! drives the loop to completion.
14//!
15//! Each input stream is either **transcoded** (decode → re-encode) when an
16//! output codec is requested for its media type, or **stream-copied**
17//! (remuxed packet-for-packet) when none is — the same `-c:v copy` distinction
18//! FFmpeg draws. Video runs through the `-vf` filter graph (scale/crop); audio
19//! is automatically resampled to a rate the target encoder accepts (FFmpeg's
20//! implicit `aresample`).
21
22use std::path::PathBuf;
23
24use rff_codec::{CodecParams, Decoder, Encoder};
25use rff_core::{
26    AudioFrame, CodecId, ColorRange, Dictionary, Error, Frame, MediaType, Packet, PixelFormat,
27    Result, SampleFormat, VideoFrame,
28};
29use rff_filter::{FilterChain, FilterComplex};
30
31use rff_format::{Muxer, Stream};
32use rff_resample::Resampler;
33
34use crate::Engine;
35
36/// `RFF_PHASES=1`: wall time per phase of the transcode loop, on stderr at the
37/// end of [`run`] -- the outside-the-codec view (demux, decode, the conform
38/// chain, encode, mux) that a codec's own stage profiler cannot see. A gap
39/// between a codec's core throughput and the CLI's is plumbing, and this is
40/// what locates it (codec-memory-copies step 0). Off by default: one cached
41/// flag test per call, and `Instant` is never touched unless it is set.
42mod phases {
43    use std::sync::atomic::{AtomicU64, Ordering::Relaxed};
44    use std::sync::OnceLock;
45
46    pub static OPEN: AtomicU64 = AtomicU64::new(0);
47    pub static DEMUX: AtomicU64 = AtomicU64::new(0);
48    pub static DECODE: AtomicU64 = AtomicU64::new(0);
49    pub static CONFORM: AtomicU64 = AtomicU64::new(0);
50    pub static ENCODE: AtomicU64 = AtomicU64::new(0);
51    pub static MUX: AtomicU64 = AtomicU64::new(0);
52
53    pub fn on() -> bool {
54        static ON: OnceLock<bool> = OnceLock::new();
55        *ON.get_or_init(|| std::env::var_os("RFF_PHASES").is_some())
56    }
57
58    /// Run `f`, charging its wall time to `acc` when phases are on.
59    pub fn time<T>(acc: &AtomicU64, f: impl FnOnce() -> T) -> T {
60        if !on() {
61            return f();
62        }
63        let t = std::time::Instant::now();
64        let r = f();
65        acc.fetch_add(t.elapsed().as_nanos() as u64, Relaxed);
66        r
67    }
68
69    pub fn report(total: std::time::Duration) {
70        let total_ns = total.as_nanos().max(1) as f64;
71        eprintln!("--- rff phases (total {:.1} ms) ---", total_ns / 1e6);
72        let mut sum = 0u64;
73        for (name, acc) in [
74            ("open", &OPEN),
75            ("demux", &DEMUX),
76            ("decode", &DECODE),
77            ("conform", &CONFORM),
78            ("encode", &ENCODE),
79            ("mux", &MUX),
80        ] {
81            let ns = acc.swap(0, Relaxed);
82            sum += ns;
83            eprintln!(
84                "  {name:<8} {:>9.1} ms  {:>5.1}%",
85                ns as f64 / 1e6,
86                100.0 * ns as f64 / total_ns
87            );
88        }
89        let rest = total_ns - sum as f64;
90        eprintln!(
91            "  {:<8} {:>9.1} ms  {:>5.1}%",
92            "other",
93            rest / 1e6,
94            100.0 * rest / total_ns
95        );
96    }
97}
98
99/// Codecs whose decoded output is inherently full-range (they decode to RGB, or
100/// are defined on 0-255 samples). JPEG is the canonical case: the standard has
101/// no limited-range mode, which is why FFmpeg calls its pixel formats `yuvj*`.
102fn is_full_range_codec(codec: CodecId) -> bool {
103    matches!(
104        codec,
105        CodecId::Jpeg | CodecId::Png | CodecId::Gif | CodecId::Webp
106    )
107}
108
109/// What range this stream's decoded frames are actually in.
110///
111/// An `Unspecified` stream is not "unknown, do nothing" — every consumer has to
112/// pick something, so pick it here, once, explicitly:
113/// full-range for codecs that are defined that way, limited-range otherwise
114/// (the video convention, and what an untagged y4m means).
115fn effective_color_range(stream: &Stream) -> ColorRange {
116    match stream.color_range {
117        ColorRange::Unspecified if is_full_range_codec(stream.codec_id) => ColorRange::Full,
118        ColorRange::Unspecified => ColorRange::Limited,
119        explicit => explicit,
120    }
121}
122
123/// One input file for a job.
124#[derive(Debug, Clone)]
125pub struct InputSpec {
126    pub path: PathBuf,
127    /// Force a container format instead of guessing from the extension
128    /// (`ffmpeg -f <fmt> -i ...`).
129    pub format: Option<String>,
130}
131
132/// Per-stream codec selection for the output.
133#[derive(Debug, Clone)]
134pub struct StreamCodec {
135    pub codec: CodecId,
136    /// Codec options (`-b:v 2M`, `-crf 23`, ...).
137    pub options: Dictionary,
138    /// Output sample format pinned by the codec NAME (`-c:a pcm_s16le`) or by
139    /// `-sample_fmt`. `None` = take whatever the decoder emits. Without this,
140    /// raw-PCM output silently ignored the format half of its own codec name.
141    pub sample_format: Option<SampleFormat>,
142}
143
144/// Which input stream(s) a `-map` entry selects.
145#[derive(Debug, Clone)]
146pub enum MapSelector {
147    /// All streams of the input (`-map 0`).
148    All,
149    /// All streams of a media kind (`-map 0:v` / `0:a`).
150    Kind(MediaType),
151    /// One stream by index within the input (`-map 0:2`).
152    Index(usize),
153}
154
155/// One `-map` entry: pick stream(s) from input `input`.
156#[derive(Debug, Clone)]
157pub struct MapSpec {
158    pub input: usize,
159    pub selector: MapSelector,
160}
161
162/// The output file for a job.
163#[derive(Debug, Clone, Default)]
164pub struct OutputSpec {
165    pub path: PathBuf,
166    /// Force a container format instead of guessing from the extension
167    /// (`ffmpeg -f <fmt> ...`).
168    pub format: Option<String>,
169    /// Video codec for the output, if a video stream is produced.
170    pub video_codec: Option<StreamCodec>,
171    /// Audio codec for the output, if an audio stream is produced.
172    pub audio_codec: Option<StreamCodec>,
173    /// Subtitle codec (`-c:s subrip|webvtt`). Text-subtitle packets share one
174    /// contract (plain text + ms timing), so this relabels the stream for the
175    /// muxer rather than re-encoding anything.
176    pub subtitle_codec: Option<CodecId>,
177    /// Video filter graph (`-vf`), e.g. `scale=320:240,crop=...`. Applied to
178    /// decoded video frames before re-encoding (transcode streams only).
179    pub video_filters: Option<String>,
180    /// Multi-input filter graph (`-filter_complex`). Currently models `overlay`:
181    /// the last input is composited over input #0's video.
182    pub filter_complex: Option<String>,
183    /// Explicit stream selection (`-map`). Empty = default (all video + audio,
184    /// in input/stream order).
185    pub maps: Vec<MapSpec>,
186    /// Media kinds dropped from the output whatever selected them (`-vn`,
187    /// `-an`, `-sn`, `-dn`).
188    pub disabled: Vec<MediaType>,
189    /// Overwrite the output if it exists (`-y`); otherwise fail (`-n`).
190    pub overwrite: bool,
191    /// Stop after this many VIDEO frames (`-frames:v N`). `None` = whole input.
192    ///
193    /// This is a measurement-critical option: without it a harness that thinks
194    /// it is encoding a 50-frame prefix silently encodes the whole clip, and any
195    /// rate-vs-quality pairing computed against a prefix is then wrong.
196    pub max_video_frames: Option<u64>,
197    /// Output trim window start, in seconds (`-ss`). Decoded frames (or copied
198    /// packets) before this point are dropped; timestamps are shifted so the
199    /// output starts at zero.
200    pub trim_start: Option<f64>,
201    /// Output trim window end, in seconds (`-to`, or `-ss` + `-t`). Exclusive.
202    pub trim_end: Option<f64>,
203    /// Constant output frame rate (`-r`), as `(num, den)` — e.g. `(30000, 1001)`.
204    /// Frames are duplicated/dropped to hit it (FFmpeg's `fps` filter).
205    pub frame_rate: Option<(u32, u32)>,
206    /// Target audio sample rate (`-ar`). The encoder's accepted-rate list still
207    /// wins if it cannot take this exact rate (nearest accepted is used).
208    pub audio_rate: Option<u32>,
209    /// Target audio channel count (`-ac`): 1↔2 downmix/upmix.
210    pub audio_channels: Option<u16>,
211    /// Audio filter chain (`-af` / `-filter:a`), e.g. `volume=-6dB,atrim=...`.
212    pub audio_filters: Option<String>,
213    /// Output metadata (`-metadata title=...`), handed to muxers that carry it.
214    pub metadata: Dictionary,
215    /// Muxer options (`-hls_time 6` → `{"hls_time": "6"}`), for formats that
216    /// take them (HLS/DASH segmenting).
217    pub format_options: Dictionary,
218}
219
220/// A complete, declarative transcoding job.
221#[derive(Debug, Clone, Default)]
222pub struct TranscodeSpec {
223    pub inputs: Vec<InputSpec>,
224    pub outputs: Vec<OutputSpec>,
225}
226
227/// A successful run's summary (frames/packets moved, etc.). Fields will grow as
228/// the pipeline does.
229#[derive(Debug, Clone, Default)]
230pub struct TranscodeReport {
231    pub packets_written: u64,
232    pub frames_decoded: u64,
233}
234
235/// Output trim window (`-ss` / `-t` / `-to`), in seconds.
236#[derive(Clone, Copy)]
237struct Trim {
238    start: f64,
239    end: Option<f64>,
240}
241
242impl Trim {
243    fn from_spec(o: &OutputSpec) -> Option<Trim> {
244        if o.trim_start.is_none() && o.trim_end.is_none() {
245            return None;
246        }
247        Some(Trim {
248            start: o.trim_start.unwrap_or(0.0).max(0.0),
249            end: o.trim_end,
250        })
251    }
252
253    fn keeps(&self, t: f64) -> bool {
254        t >= self.start - 1e-9 && self.end.map_or(true, |e| t < e - 1e-9)
255    }
256}
257
258/// CFR conversion state (`-r`): input frames are snapped onto a fixed
259/// `num/den` fps grid, duplicating the previous frame across gaps and dropping
260/// frames that land on an already-filled slot. Emitted frames carry their slot
261/// index as pts (time base `den/num`).
262struct FpsConv {
263    num: u32,
264    den: u32,
265    next_slot: i64,
266    last: Option<VideoFrame>,
267}
268
269impl FpsConv {
270    fn new(num: u32, den: u32) -> FpsConv {
271        FpsConv {
272            num: num.max(1),
273            den: den.max(1),
274            next_slot: 0,
275            last: None,
276        }
277    }
278
279    fn slot_time(&self, slot: i64) -> f64 {
280        slot as f64 * self.den as f64 / self.num as f64
281    }
282
283    /// Feed one input frame at time `t` (seconds); returns the frames due
284    /// strictly before `t`, each stamped with its slot pts.
285    fn push(&mut self, frame: VideoFrame, t: f64) -> Vec<VideoFrame> {
286        let mut out = Vec::new();
287        while let Some(last) = &self.last {
288            if self.slot_time(self.next_slot) < t - 1e-9 {
289                let mut f = last.clone();
290                f.pts = Some(self.next_slot);
291                out.push(f);
292                self.next_slot += 1;
293            } else {
294                break;
295            }
296        }
297        self.last = Some(frame);
298        out
299    }
300
301    /// End of stream: emit the held frame in its slot.
302    fn finish(&mut self) -> Option<VideoFrame> {
303        self.last.take().map(|mut f| {
304            f.pts = Some(self.next_slot);
305            self.next_slot += 1;
306            f
307        })
308    }
309}
310
311/// What to do with one input stream on its way to the output.
312enum StreamOp {
313    /// Not selected (or a media type we can't route): drop its packets.
314    Skip,
315    /// Remux packets unchanged into the output.
316    Copy(CopyOp),
317    /// Decode, filter, re-encode.
318    Transcode(Box<TranscodeOp>),
319}
320
321/// Stream-copy: forward packets, applying the trim window at packet level.
322/// Video cuts on the first keyframe inside the window (a copy can't split a
323/// GOP); timestamps shift so the output starts at zero.
324struct CopyOp {
325    out_index: usize,
326    is_video: bool,
327    /// Trim window in stream ticks (`None` = no trimming).
328    start_ticks: i64,
329    end_ticks: Option<i64>,
330    trimming: bool,
331    /// Video: set once the first in-window keyframe has passed.
332    started: bool,
333}
334
335impl CopyOp {
336    /// Apply trim/shift; `None` = drop the packet.
337    fn process(&mut self, mut packet: Packet) -> Option<Packet> {
338        if self.trimming {
339            let ts = packet.pts.or(packet.dts).unwrap_or(0);
340            if ts < self.start_ticks {
341                return None;
342            }
343            if let Some(end) = self.end_ticks {
344                if ts >= end {
345                    return None;
346                }
347            }
348            if self.is_video && !self.started {
349                if !packet.flags.keyframe {
350                    return None; // wait for a clean random-access point
351                }
352                self.started = true;
353            }
354            packet.pts = packet.pts.map(|p| p - self.start_ticks);
355            packet.dts = packet.dts.map(|d| d - self.start_ticks);
356        }
357        packet.stream_index = self.out_index;
358        Some(packet)
359    }
360}
361
362/// Decode → trim → fps → filters/overlay → audio conform → encode → mux.
363struct TranscodeOp {
364    decoder: Box<dyn Decoder>,
365    encoder: Box<dyn Encoder>,
366    filters: FilterChain,
367    /// `-filter_complex` overlay: a pre-decoded frame composited onto each
368    /// of this stream's frames at `(x, y)` (after `filters`). Video only.
369    overlay: Option<(VideoFrame, u32, u32)>,
370    /// The input stream's time base (frame pts are in these ticks).
371    in_time_base: rff_core::Rational,
372    is_video: bool,
373    /// Output trim window; pts are shifted by `shift_ticks` after it.
374    trim: Option<Trim>,
375    shift_ticks: i64,
376    /// Fallback clock for trimming audio whose frames carry no pts.
377    audio_clock_samples: u64,
378    /// `-r`: CFR duplicate/drop stage.
379    fps: Option<FpsConv>,
380    /// `-af`: the audio filter chain (volume/atrim/...).
381    audio_chain: rff_filter::AudioFilterChain,
382    /// `-ac`: mix to this many channels before everything else (0 = keep).
383    target_channels: u16,
384    /// Sample rate the encoder needs (0 = no audio resampling required).
385    target_rate: u32,
386    /// Sample format the output pins (`-c:a pcm_s16le`), if any.
387    target_sample_format: Option<SampleFormat>,
388    /// Lazily built once the first audio frame reveals the input rate.
389    resampler: Option<Resampler>,
390    /// Pixel formats the encoder accepts (`None` = anything).
391    accepted_formats: Option<Vec<PixelFormat>>,
392    /// Lazily built conversion into an accepted format.
393    pixel_converter: Option<FilterChain>,
394    /// Range of the frames reaching the encoder, for that conversion.
395    source_range: ColorRange,
396    out_index: usize,
397    /// `-frames:v` limit for this output, and how many we have sent.
398    max_video_frames: Option<u64>,
399    video_frames_sent: u64,
400    /// pts of video frames handed to the encoder, FIFO. Video encoders that
401    /// don't timestamp their packets (VP9, H.264) get these stamped on in
402    /// [`TranscodeOp::drain`] — without it every Matroska block lands at t=0.
403    pending_pts: std::collections::VecDeque<Option<i64>>,
404}
405
406/// Composite the `-filter_complex` overlay onto a video frame, if one is set.
407/// Audio frames and the no-overlay case pass through untouched.
408fn apply_overlay(overlay: &Option<(VideoFrame, u32, u32)>, frame: Frame) -> Result<Frame> {
409    match (overlay, frame) {
410        (Some((over, x, y)), Frame::Video(v)) => {
411            Ok(Frame::Video(rff_filter::overlay(v, over, *x, *y)?))
412        }
413        (_, frame) => Ok(frame),
414    }
415}
416
417/// Apply a video filter chain to a frame. Filters are video-only; audio passes
418/// through untouched, and an empty chain is a no-op.
419fn apply_filters(filters: &mut FilterChain, frame: Frame) -> Result<Frame> {
420    if filters.is_empty() {
421        return Ok(frame);
422    }
423    match frame {
424        Frame::Video(v) => Ok(Frame::Video(filters.apply(v)?)),
425        other => Ok(other),
426    }
427}
428
429/// Pick the accepted rate closest to `target`.
430fn nearest_rate(rates: &[u32], target: u32) -> u32 {
431    rates
432        .iter()
433        .copied()
434        .min_by_key(|r| (*r as i64 - target as i64).abs())
435        .unwrap_or(target)
436}
437
438/// Read interleaved `s16`/`f32` plane 0 of an audio frame into `f32` samples.
439fn audio_to_f32(af: &AudioFrame) -> Result<Vec<f32>> {
440    match af.format {
441        SampleFormat::F32 => Ok(af.planes[0]
442            .chunks_exact(4)
443            .map(|b| f32::from_le_bytes([b[0], b[1], b[2], b[3]]))
444            .collect()),
445        SampleFormat::S16 => Ok(af.planes[0]
446            .chunks_exact(2)
447            .map(|b| i16::from_le_bytes([b[0], b[1]]) as f32 / 32768.0)
448            .collect()),
449        other => Err(Error::unsupported(format!(
450            "resample: sample format `{}` (need interleaved s16/f32)",
451            other.name()
452        ))),
453    }
454}
455
456/// `f32` samples as little-endian bytes, in one sized pass. The
457/// `iter().flat_map(to_le_bytes).collect()` this replaces is the pattern LLVM
458/// handles worst -- an iterator of tiny arrays flattened into a growing `Vec`.
459fn f32_le_bytes(samples: &[f32]) -> Vec<u8> {
460    let mut bytes = vec![0u8; samples.len() * 4];
461    for (d, s) in bytes.chunks_exact_mut(4).zip(samples) {
462        d.copy_from_slice(&s.to_le_bytes());
463    }
464    bytes
465}
466
467/// The usual f32 -> s16 rule: round to nearest, then clamp. Truncation would
468/// bias every sample toward zero.
469fn f32_to_s16(s: f32) -> i16 {
470    (s * 32768.0).round().clamp(-32768.0, 32767.0) as i16
471}
472
473/// Wrap interleaved `f32` samples as an `f32` [`AudioFrame`].
474fn f32_frame(samples: Vec<f32>, rate: u32, channels: u16, pts: Option<i64>) -> Frame {
475    let bytes = f32_le_bytes(&samples);
476    Frame::Audio(AudioFrame {
477        sample_rate: rate,
478        channels,
479        format: SampleFormat::F32,
480        samples: samples.len() / channels.max(1) as usize,
481        planes: vec![bytes],
482        pts,
483    })
484}
485
486/// Convert an audio frame to `target` sample format, if one is pinned and the
487/// frame is not already in it. The audio analogue of `conform_video`: raw PCM
488/// output declares its format in the container header, so the frames handed to
489/// the muxer must actually BE that format, not merely be labelled it.
490fn conform_sample_format(target: Option<SampleFormat>, frame: Frame) -> Result<Frame> {
491    let Some(target) = target else {
492        return Ok(frame);
493    };
494    let Frame::Audio(af) = frame else {
495        return Ok(frame);
496    };
497    if af.format == target {
498        return Ok(Frame::Audio(af));
499    }
500    // Bytes to bytes in ONE pass. This used to decode the whole plane into a
501    // `Vec<f32>` and then re-encode it through `flat_map(..).collect()` -- an
502    // extra full-frame copy (a WAV's worth, when the frame is a whole file) and
503    // the iterator shape LLVM vectorises worst. The arithmetic per sample is
504    // the same expression, so the output is byte-identical.
505    let src = &af.planes[0];
506    let plane = match (af.format, target) {
507        (SampleFormat::F32, SampleFormat::S16) => {
508            let mut out = vec![0u8; src.len() / 4 * 2];
509            for (d, b) in out.chunks_exact_mut(2).zip(src.chunks_exact(4)) {
510                let s = f32::from_le_bytes([b[0], b[1], b[2], b[3]]);
511                d.copy_from_slice(&f32_to_s16(s).to_le_bytes());
512            }
513            out
514        }
515        (SampleFormat::S16, SampleFormat::F32) => {
516            let mut out = vec![0u8; src.len() / 2 * 4];
517            for (d, b) in out.chunks_exact_mut(4).zip(src.chunks_exact(2)) {
518                let s = i16::from_le_bytes([b[0], b[1]]) as f32 / 32768.0;
519                d.copy_from_slice(&s.to_le_bytes());
520            }
521            out
522        }
523        _ => {
524            // Not a supported pair: report the source format first, as before.
525            audio_to_f32(&af)?;
526            return Err(Error::unsupported(format!(
527                "sample format conversion to `{}` (only interleaved s16/f32)",
528                target.name()
529            )));
530        }
531    };
532    let planes = vec![plane];
533    Ok(Frame::Audio(AudioFrame {
534        sample_rate: af.sample_rate,
535        channels: af.channels,
536        format: target,
537        samples: af.samples,
538        planes,
539        pts: af.pts,
540    }))
541}
542
543/// Resample an audio frame to `target_rate` if needed (the resampler is built
544/// lazily from the first frame's rate/channels). `target_rate == 0` is a no-op.
545fn conform_audio(
546    resampler: &mut Option<Resampler>,
547    target_rate: u32,
548    frame: Frame,
549) -> Result<Frame> {
550    if target_rate == 0 {
551        return Ok(frame);
552    }
553    let Frame::Audio(af) = frame else {
554        return Ok(frame);
555    };
556    if af.sample_rate == target_rate {
557        return Ok(Frame::Audio(af));
558    }
559    let rs =
560        resampler.get_or_insert_with(|| Resampler::new(af.sample_rate, target_rate, af.channels));
561    let out = rs.process(&audio_to_f32(&af)?);
562    let pts = af
563        .pts
564        .map(|p| p * target_rate as i64 / af.sample_rate.max(1) as i64);
565    Ok(f32_frame(out, target_rate, af.channels, pts))
566}
567
568/// Convert a video frame into a pixel format the encoder accepts, if it isn't
569/// already in one. The converting chain is built lazily from the first frame
570/// that needs it, mirroring the audio resampler above.
571///
572/// This is what lets a decoder emit its cheapest native layout: the JPEG decoder
573/// hands out planar Y'CbCr, and a PNG encoder downstream still gets the RGB it
574/// requires because this inserts the conversion.
575fn conform_video(
576    converter: &mut Option<FilterChain>,
577    accepted: &Option<Vec<PixelFormat>>,
578    source_range: ColorRange,
579    frame: Frame,
580) -> Result<Frame> {
581    let Some(accepted) = accepted else {
582        return Ok(frame);
583    };
584    let Frame::Video(vf) = frame else {
585        return Ok(frame);
586    };
587    if accepted.is_empty() || accepted.contains(&vf.format) {
588        return Ok(Frame::Video(vf));
589    }
590    if converter.is_none() {
591        // First choice the encoder listed that we can actually convert to.
592        let target = accepted
593            .iter()
594            .find(|f| matches!(f, PixelFormat::Rgb24 | PixelFormat::Yuv420p))
595            .ok_or_else(|| {
596                Error::unsupported(format!(
597                    "no conversion from `{}` to any format this encoder accepts",
598                    vf.format.name()
599                ))
600            })?;
601        // Pin the range: `spec.limited` describes the Y'CbCr side either way,
602        // and guessing it wrong is a silent several-dB error.
603        let range = match source_range {
604            ColorRange::Limited => "limited",
605            _ => "full",
606        };
607        *converter = Some(FilterChain::parse(&format!(
608            "format={}:bt601:{}",
609            target.name(),
610            range
611        ))?);
612    }
613    let chain = converter.as_mut().expect("just built");
614    Ok(Frame::Video(chain.apply(vf)?))
615}
616
617/// Mix an audio frame to `target` channels (0 = keep). Stereo↔mono only: a
618/// downmix averages pairs, an upmix duplicates the channel.
619fn conform_channels(target: u16, frame: Frame) -> Result<Frame> {
620    if target == 0 {
621        return Ok(frame);
622    }
623    let Frame::Audio(af) = frame else {
624        return Ok(frame);
625    };
626    if af.channels == target {
627        return Ok(Frame::Audio(af));
628    }
629    let samples = audio_to_f32(&af)?;
630    let mixed: Vec<f32> = match (af.channels, target) {
631        (2, 1) => samples
632            .chunks_exact(2)
633            .map(|p| 0.5 * (p[0] + p[1]))
634            .collect(),
635        (1, 2) => samples.iter().flat_map(|s| [*s, *s]).collect(),
636        (from, to) => {
637            return Err(Error::unsupported(format!(
638                "-ac: only 1<->2 channel mixing supported (input {from} ch, requested {to})"
639            )))
640        }
641    };
642    Ok(f32_frame(mixed, af.sample_rate, target, af.pts))
643}
644
645impl TranscodeOp {
646    /// A frame's start time in seconds (input timeline). Audio without pts
647    /// falls back to a running sample clock; video without pts cannot be
648    /// placed and errors — only called when trim/fps actually need the time.
649    fn frame_time(&self, frame: &Frame) -> Result<f64> {
650        let tb = self.in_time_base;
651        let tick = if tb.num > 0 && tb.den > 0 {
652            tb.num as f64 / tb.den as f64
653        } else {
654            0.001
655        };
656        match frame.pts() {
657            Some(p) => Ok(p as f64 * tick),
658            None => match frame {
659                Frame::Audio(af) => {
660                    Ok(self.audio_clock_samples as f64 / af.sample_rate.max(1) as f64)
661                }
662                Frame::Video(_) => Err(Error::unsupported(
663                    "-ss/-t/-to/-r need timestamps and this video stream has none",
664                )),
665            },
666        }
667    }
668
669    /// Decoded-frame entry point: trim window, timestamp shift, CFR stage,
670    /// then the per-frame pipeline in [`TranscodeOp::emit`].
671    fn handle_frame(
672        &mut self,
673        frame: Frame,
674        muxer: &mut dyn Muxer,
675        report: &mut TranscodeReport,
676    ) -> Result<()> {
677        report.frames_decoded += 1;
678        let needs_time = self.trim.is_some() || (self.is_video && self.fps.is_some());
679        let t = if needs_time {
680            Some(self.frame_time(&frame)?)
681        } else {
682            None
683        };
684        // The sample clock tracks ALL input audio, kept or dropped.
685        if let Frame::Audio(af) = &frame {
686            self.audio_clock_samples += af.samples as u64;
687        }
688        let mut frame = frame;
689        if let (Some(trim), Some(t)) = (self.trim, t) {
690            match frame {
691                // Audio frames can be arbitrarily long (a WAV decodes as one
692                // frame), so the window slices samples instead of keep/drop.
693                Frame::Audio(af) => {
694                    match rff_filter::trim_audio_frame(af, Some(t), Some(trim.start), trim.end)? {
695                        Some(af) => frame = Frame::Audio(af),
696                        None => return Ok(()),
697                    }
698                }
699                Frame::Video(_) => {
700                    if !trim.keeps(t) {
701                        return Ok(());
702                    }
703                }
704            }
705        }
706        // Shift timestamps so the output timeline starts at zero.
707        if self.shift_ticks != 0 {
708            match &mut frame {
709                Frame::Video(v) => v.pts = v.pts.map(|p| p - self.shift_ticks),
710                Frame::Audio(a) => a.pts = a.pts.map(|p| p - self.shift_ticks),
711            }
712        }
713        match frame {
714            Frame::Video(v) if self.fps.is_some() => {
715                let t_out = t.expect("fps requires time") - self.trim.map_or(0.0, |w| w.start);
716                let mut fps = self.fps.take().expect("checked");
717                let due = fps.push(v, t_out);
718                self.fps = Some(fps);
719                for f in due {
720                    self.emit(Frame::Video(f), muxer, report)?;
721                }
722                Ok(())
723            }
724            other => self.emit(other, muxer, report),
725        }
726    }
727
728    /// Post-fps pipeline: `-frames:v` gate, filters, overlay, audio conforms,
729    /// encode, drain.
730    fn emit(
731        &mut self,
732        frame: Frame,
733        muxer: &mut dyn Muxer,
734        report: &mut TranscodeReport,
735    ) -> Result<()> {
736        if let Some(limit) = self.max_video_frames {
737            if matches!(frame, Frame::Video(_)) {
738                if self.video_frames_sent >= limit {
739                    return Ok(());
740                }
741                self.video_frames_sent += 1;
742            }
743        }
744        let Some(frame) = phases::time(&phases::CONFORM, || self.conform(frame))? else {
745            return Ok(()); // atrim consumed the whole frame
746        };
747        if self.is_video {
748            self.pending_pts.push_back(frame.pts());
749        }
750        phases::time(&phases::ENCODE, || self.encoder.send_frame(&frame))?;
751        self.drain(muxer, report)
752    }
753
754    /// The per-frame conform chain between decode and encode: filters, overlay,
755    /// channel/rate/sample-format/pixel conforms. `None` = atrim dropped it.
756    fn conform(&mut self, frame: Frame) -> Result<Option<Frame>> {
757        let frame = apply_filters(&mut self.filters, frame)?;
758        let frame = apply_overlay(&self.overlay, frame)?;
759        let frame = conform_channels(self.target_channels, frame)?;
760        let frame = match frame {
761            Frame::Audio(af) if !self.audio_chain.is_empty() => {
762                let tb = self.in_time_base;
763                let t = af
764                    .pts
765                    .map(|p| p as f64 * tb.num as f64 / tb.den.max(1) as f64);
766                match self.audio_chain.apply(af, t)? {
767                    Some(af) => Frame::Audio(af),
768                    None => return Ok(None),
769                }
770            }
771            other => other,
772        };
773        let frame = conform_audio(&mut self.resampler, self.target_rate, frame)?;
774        let frame = conform_sample_format(self.target_sample_format, frame)?;
775        let frame = conform_video(
776            &mut self.pixel_converter,
777            &self.accepted_formats,
778            self.source_range,
779            frame,
780        )?;
781        Ok(Some(frame))
782    }
783
784    /// Pull every ready packet out of the encoder and mux it. Video encoders
785    /// that don't timestamp their packets (VP9, H.264 emit `pts: None`) get the
786    /// corresponding source frame's pts stamped on, FIFO — without this every
787    /// Matroska block would land at t=0.
788    fn drain(&mut self, muxer: &mut dyn Muxer, report: &mut TranscodeReport) -> Result<()> {
789        loop {
790            match phases::time(&phases::ENCODE, || self.encoder.receive_packet()) {
791                Ok(mut packet) => {
792                    if self.is_video {
793                        let queued = self.pending_pts.pop_front().flatten();
794                        if packet.pts.is_none() {
795                            packet.pts = queued;
796                        }
797                    }
798                    packet.stream_index = self.out_index;
799                    phases::time(&phases::MUX, || muxer.write_packet(&packet))?;
800                    report.packets_written += 1;
801                }
802                Err(Error::Again) | Err(Error::Eof) => break,
803                Err(e) => return Err(e),
804            }
805        }
806        Ok(())
807    }
808
809    /// End of input: flush the decoder, the CFR stage's held frame, the
810    /// resampler's FIR tail, then the encoder.
811    fn finish(&mut self, muxer: &mut dyn Muxer, report: &mut TranscodeReport) -> Result<()> {
812        self.decoder.flush();
813        loop {
814            match phases::time(&phases::DECODE, || self.decoder.receive_frame()) {
815                Ok(frame) => self.handle_frame(frame, muxer, report)?,
816                Err(Error::Again) | Err(Error::Eof) => break,
817                Err(e) => return Err(e),
818            }
819        }
820        if let Some(mut fps) = self.fps.take() {
821            let held = fps.finish();
822            self.fps = Some(fps);
823            if let Some(f) = held {
824                self.emit(Frame::Video(f), muxer, report)?;
825            }
826        }
827        if let Some(rs) = &mut self.resampler {
828            let tail = rs.finish();
829            if !tail.is_empty() {
830                let frame = f32_frame(tail, rs.out_rate(), rs.channels(), None);
831                let frame = conform_sample_format(self.target_sample_format, frame)?;
832                self.encoder.send_frame(&frame)?;
833                self.drain(muxer, report)?;
834            }
835        }
836        phases::time(&phases::ENCODE, || self.encoder.flush());
837        self.drain(muxer, report)
838    }
839}
840
841/// Resolve and run a transcode job against `engine`.
842///
843/// Resolution (formats, decoders, encoders) happens up front so failures are
844/// reported before any output file is touched; then the demux→decode→encode→mux
845/// loop runs to completion.
846pub fn run(engine: &Engine, spec: &TranscodeSpec) -> Result<TranscodeReport> {
847    if spec.inputs.is_empty() {
848        return Err(Error::Option("no input files specified".into()));
849    }
850    if spec.outputs.is_empty() {
851        return Err(Error::Option("no output file specified".into()));
852    }
853    if spec.outputs.len() > 1 {
854        return Err(Error::unsupported("multiple outputs are not supported yet"));
855    }
856    let output = &spec.outputs[0];
857
858    // -filter_complex overlay: the last input is composited over input #0's
859    // video. Resolve it up front so stream selection can exclude that input.
860    let overlay_xy = output
861        .filter_complex
862        .as_deref()
863        .map(FilterComplex::parse)
864        .transpose()?
865        .and_then(|fc| fc.overlay);
866    let overlay_input = match overlay_xy {
867        Some(_) if spec.inputs.len() >= 2 => Some(spec.inputs.len() - 1),
868        Some(_) => {
869            return Err(Error::Option(
870                "filter_complex overlay needs a second input (the overlay image/video)".into(),
871            ))
872        }
873        None => None,
874    };
875
876    // --- open every input demuxer and read its streams ---
877    // (`open` is a phase of its own: demuxers read only their headers here and
878    // stream packets after; MP4 from a pipe, which must buffer to reach a
879    // trailing `moov`, is the one that still does all of its I/O at open.)
880    let t_start = phases::on().then(std::time::Instant::now);
881    let mut demuxers: Vec<Box<dyn rff_format::Demuxer>> = Vec::new();
882    let mut input_streams: Vec<Vec<Stream>> = Vec::new();
883    for input in &spec.inputs {
884        let (demuxer, streams) = phases::time(&phases::OPEN, || -> Result<_> {
885            let (in_format, source) = open_input(engine, input)?;
886            let mut demuxer = source.open_demuxer(engine, &in_format)?;
887            let streams = demuxer.read_header()?;
888            Ok((demuxer, streams))
889        })?;
890        input_streams.push(streams);
891        demuxers.push(demuxer);
892    }
893
894    // --- select which (input, stream) pairs go to the output, in order ---
895    let mut selection = select_streams(&input_streams, output)?;
896    // The overlay input is consumed by the filter, not muxed as its own stream.
897    if let Some(oin) = overlay_input {
898        selection.retain(|(inp, _)| *inp != oin);
899    }
900    if selection.is_empty() {
901        return Err(Error::unsupported("no streams selected for the output"));
902    }
903
904    // Single-codec containers can't stream-copy a foreign codec, so an unset
905    // `-c:v` must mean TRANSCODE to the container's one codec, not copy (which
906    // the muxer would reject). y4m additionally can't carry anything compressed.
907    // Mirrors ffmpeg picking the muxer's default codec (`out.webp` → webp).
908    // When the source already IS that codec, `None` stays: stream-copy wins.
909    let mut output_owned;
910    let output = if output.video_codec.is_none() {
911        let format_name = resolve_output_format(engine, output).ok();
912        // y4m keeps its unconditional default: it can't carry anything
913        // compressed, so even rawvideo input goes through the decode path.
914        let required = match format_name.as_deref() {
915            Some("yuv4mpegpipe") => Some((CodecId::RawVideo, true)),
916            Some("webp") => Some((CodecId::Webp, false)),
917            Some("png") => Some((CodecId::Png, false)),
918            Some("jpeg") => Some((CodecId::Jpeg, false)),
919            Some("gif") => Some((CodecId::Gif, false)),
920            Some("avif") => Some((CodecId::Avif, false)),
921            Some("jpegxl") => Some((CodecId::Jxl, false)),
922            _ => None,
923        };
924        let apply = match required {
925            Some((_, true)) => true,
926            // Image containers: only when the source codec differs — a matching
927            // source keeps `None` and takes the stream-copy fast path.
928            Some((codec, false)) => !selection.iter().any(|&(inp, local)| {
929                let s = &input_streams[inp][local];
930                s.media_type == MediaType::Video && s.codec_id == codec
931            }),
932            None => false,
933        };
934        if apply {
935            output_owned = output.clone();
936            output_owned.video_codec = Some(StreamCodec {
937                codec: required.expect("apply implies required").0,
938                options: Dictionary::default(),
939                sample_format: None, // video: no audio sample format to pin
940            });
941            &output_owned
942        } else {
943            output
944        }
945    } else {
946        output
947    };
948
949    // Per-input op tables (Skip for unselected streams) + ordered output streams.
950    let mut per_input_ops: Vec<Vec<StreamOp>> = input_streams
951        .iter()
952        .map(|s| (0..s.len()).map(|_| StreamOp::Skip).collect())
953        .collect();
954    let mut out_streams: Vec<Stream> = Vec::new();
955    for (out_index, &(inp, local)) in selection.iter().enumerate() {
956        let (op, os) = build_op(engine, &input_streams[inp][local], output, out_index)?;
957        per_input_ops[inp][local] = op;
958        out_streams.push(os);
959    }
960
961    // --- filter_complex overlay: pre-decode the overlay frame and hand it to
962    // input #0's video transcode op (which composites it onto every frame) ---
963    if let (Some((x, y)), Some(oin)) = (overlay_xy, overlay_input) {
964        let over = decode_overlay_frame(engine, &mut *demuxers[oin], &input_streams[oin])?;
965        let vidx = input_streams[0]
966            .iter()
967            .position(|s| s.media_type == MediaType::Video)
968            .ok_or_else(|| Error::Option("filter_complex overlay: input #0 has no video".into()))?;
969        match &mut per_input_ops[0][vidx] {
970            StreamOp::Transcode(op) => op.overlay = Some((over, x, y)),
971            _ => {
972                return Err(Error::unsupported(
973                    "filter_complex overlay needs input #0's video re-encoded — pass -c:v",
974                ))
975            }
976        }
977    }
978
979    // --- pick the muxer from the registry. Path-based formats (HLS/DASH: a
980    // playlist plus many segment files) are built with the output path; every
981    // other format writes one byte sink through rff-io (file, pipe, udp).
982    let out_format = resolve_output_format(engine, output)?;
983    let muxer_path_factory = engine
984        .formats
985        .by_name(&out_format)
986        .filter(|fmt| fmt.can_mux())
987        .ok_or_else(|| Error::MuxerNotFound(out_format.clone()))?
988        .muxer_path;
989
990    // --- refuse to clobber an existing file unless -y was given (pipes and
991    // sockets have nothing to clobber) ---
992    let out_path_str = output.path.to_str().unwrap_or_default();
993    let is_sink_stream = rff_io::is_pipe(out_path_str)
994        || rff_io::is_udp(out_path_str)
995        || rff_io::is_rtmp(out_path_str);
996    if !is_sink_stream && !output.overwrite && output.path.exists() {
997        return Err(Error::Option(format!(
998            "{} already exists (pass -y to overwrite)",
999            output.path.display()
1000        )));
1001    }
1002    let mut muxer: Box<dyn Muxer> = match muxer_path_factory {
1003        Some(factory) => factory(&output.path, &output.format_options)?,
1004        // A local file is seekable: muxers that can stream and patch their
1005        // header afterwards take that path (#28); pipes and network sinks
1006        // keep the plain one.
1007        None => match rff_io::create_seekable(out_path_str)? {
1008            Some(file) => engine
1009                .formats
1010                .open_muxer_seekable(&out_format, Box::new(file))?,
1011            None => engine
1012                .formats
1013                .open_muxer(&out_format, rff_io::create(out_path_str)?)?,
1014        },
1015    };
1016    if !output.metadata.is_empty() {
1017        muxer.set_metadata(&output.metadata);
1018    }
1019    muxer.write_header(&out_streams)?;
1020
1021    let mut report = TranscodeReport::default();
1022
1023    // Streams every op skips (unmapped, -vn/-an, the overlay input once its
1024    // frame is decoded) are never needed: let each demuxer drop them at the
1025    // source instead of reading and converting packets only to discard them.
1026    for (demuxer, ops) in demuxers.iter_mut().zip(&per_input_ops) {
1027        let discard: Vec<bool> = ops.iter().map(|op| matches!(op, StreamOp::Skip)).collect();
1028        if discard.contains(&true) {
1029            demuxer.set_discard(&discard);
1030        }
1031    }
1032
1033    // --- drive each input through its plan into the shared muxer ---
1034    for (demuxer, ops) in demuxers.iter_mut().zip(per_input_ops.iter_mut()) {
1035        loop {
1036            match phases::time(&phases::DEMUX, || demuxer.read_packet()) {
1037                Ok(packet) => process_packet(packet, ops, &mut *muxer, &mut report)?,
1038                Err(Error::Eof) => break,
1039                Err(e) => return Err(e),
1040            }
1041        }
1042        flush_streams(ops, &mut *muxer, &mut report)?;
1043    }
1044    phases::time(&phases::MUX, || muxer.write_trailer())?;
1045    if let Some(t) = t_start {
1046        phases::report(t.elapsed());
1047    }
1048
1049    Ok(report)
1050}
1051
1052/// Resolve which `(input_index, stream_index)` pairs go to the output, in
1053/// output order. With no `-map`, defaults to every video + audio stream across
1054/// all inputs (input order, then stream order). Kinds in
1055/// [`OutputSpec::disabled`] are then dropped, mapped or not.
1056fn select_streams(inputs: &[Vec<Stream>], output: &OutputSpec) -> Result<Vec<(usize, usize)>> {
1057    let mut selection = mapped_streams(inputs, output)?;
1058    selection.retain(|&(ii, i)| !output.disabled.contains(&inputs[ii][i].media_type));
1059    Ok(selection)
1060}
1061
1062fn mapped_streams(inputs: &[Vec<Stream>], output: &OutputSpec) -> Result<Vec<(usize, usize)>> {
1063    let mut selection = Vec::new();
1064    if output.maps.is_empty() {
1065        for (ii, streams) in inputs.iter().enumerate() {
1066            for (i, s) in streams.iter().enumerate() {
1067                if matches!(
1068                    s.media_type,
1069                    MediaType::Video | MediaType::Audio | MediaType::Subtitle
1070                ) {
1071                    selection.push((ii, i));
1072                }
1073            }
1074        }
1075    } else {
1076        for map in &output.maps {
1077            let streams = inputs
1078                .get(map.input)
1079                .ok_or_else(|| Error::Option(format!("-map: no input #{}", map.input)))?;
1080            for (i, s) in streams.iter().enumerate() {
1081                let hit = match &map.selector {
1082                    MapSelector::All => true,
1083                    MapSelector::Kind(k) => s.media_type == *k,
1084                    MapSelector::Index(idx) => i == *idx,
1085                };
1086                if hit {
1087                    selection.push((map.input, i));
1088                }
1089            }
1090        }
1091    }
1092    Ok(selection)
1093}
1094
1095/// Build the [`StreamOp`] (transcode or copy) and matching output [`Stream`] for
1096/// one selected input stream at output position `out_index`.
1097fn build_op(
1098    engine: &Engine,
1099    stream: &Stream,
1100    output: &OutputSpec,
1101    out_index: usize,
1102) -> Result<(StreamOp, Stream)> {
1103    let requested = match stream.media_type {
1104        MediaType::Video => output.video_codec.as_ref(),
1105        MediaType::Audio => output.audio_codec.as_ref(),
1106        _ => None,
1107    };
1108    match requested {
1109        // Transcode: decode the input codec, re-encode to the requested one.
1110        Some(target) => {
1111            let mut decoder = engine.codecs.find_decoder(stream.codec_id)?;
1112            decoder.configure(&codec_params(stream))?;
1113            let mut encoder = engine.codecs.find_encoder(target.codec)?;
1114            encoder.configure(&target.options)?; // rate control: -crf / -preset / -b
1115                                                 // Video filter graph (`-vf`); applies to video streams only.
1116            let mut filters = if stream.media_type == MediaType::Video {
1117                FilterChain::parse(output.video_filters.as_deref().unwrap_or(""))?
1118            } else {
1119                FilterChain::default()
1120            };
1121            // Colour range has to be reconciled before any filter runs. JPEG (and
1122            // the other image codecs) are defined on full-range samples, so
1123            // handing them limited-range video encodes the wrong signal — it
1124            // measured 28.35 dB where it should have been 36.15 dB, a deficit
1125            // that looked exactly like poor encoder quality. Convert once, up
1126            // front, then tell the rest of the chain what it is now looking at.
1127            let mut source_range = ColorRange::Unspecified;
1128            if stream.media_type == MediaType::Video {
1129                source_range = effective_color_range(stream);
1130                if is_full_range_codec(target.codec) && source_range == ColorRange::Limited {
1131                    filters.prepend_range_conversion(true);
1132                    source_range = ColorRange::Full;
1133                }
1134                filters.set_source_color_range(source_range);
1135            }
1136            let (out_w, out_h) = filters.output_dims(stream.width, stream.height);
1137            let is_video = stream.media_type == MediaType::Video;
1138            let is_audio = stream.media_type == MediaType::Audio;
1139
1140            // Audio filter chain (`-af`); audio streams only.
1141            let audio_chain = if is_audio {
1142                rff_filter::AudioFilterChain::parse(output.audio_filters.as_deref().unwrap_or(""))?
1143            } else {
1144                rff_filter::AudioFilterChain::default()
1145            };
1146
1147            // `-ac`: validate up front — only mono/stereo mixing exists.
1148            let target_channels = match output.audio_channels {
1149                Some(c) if is_audio => {
1150                    if !(1..=2).contains(&c) {
1151                        return Err(Error::unsupported(format!(
1152                            "-ac {c}: only 1 or 2 channels supported"
1153                        )));
1154                    }
1155                    c
1156                }
1157                _ => 0,
1158            };
1159
1160            // Output sample rate: `-ar` / `aresample=` wins, else the input
1161            // rate; either way the encoder's accepted-rate list has the last
1162            // word (nearest accepted).
1163            let mut target_rate = 0;
1164            let mut out_rate = stream.sample_rate;
1165            if is_audio && stream.sample_rate > 0 {
1166                let desired = output
1167                    .audio_rate
1168                    .or(audio_chain.resample_target())
1169                    .unwrap_or(stream.sample_rate);
1170                let desired = match encoder.accepted_sample_rates() {
1171                    Some(rates) if !rates.contains(&desired) => nearest_rate(&rates, desired),
1172                    _ => desired,
1173                };
1174                if desired != stream.sample_rate {
1175                    target_rate = desired;
1176                }
1177                out_rate = desired;
1178            }
1179
1180            // Trim window and the tick shift that re-zeroes the output timeline.
1181            let trim = Trim::from_spec(output);
1182            let tb = stream.time_base;
1183            let shift_ticks = trim
1184                .map(|t| (t.start * tb.den as f64 / tb.num.max(1) as f64).round() as i64)
1185                .unwrap_or(0);
1186
1187            // `-r`: CFR stage; the output stream ticks in 1/fps units.
1188            let fps = match output.frame_rate {
1189                Some((num, den)) if is_video => Some(FpsConv::new(num, den)),
1190                _ => None,
1191            };
1192
1193            let mut accepted_formats = encoder.accepted_pixel_formats();
1194
1195            let mut os = Stream::new(out_index, target.codec);
1196            os.media_type = stream.media_type;
1197            os.time_base = stream.time_base;
1198            os.width = out_w;
1199            os.height = out_h;
1200            os.pixel_format = stream.pixel_format;
1201            // Raw output declares its pixel format in the container header,
1202            // which the muxer writes before a single frame has been seen. So the
1203            // format cannot be discovered later — pin it now and force frames to
1204            // match, or the header ends up describing data it does not have.
1205            // (A 4:4:4 JPEG decoded straight to planes under a `C420mpeg2`
1206            // header is silent corruption, not a mislabel.)
1207            if target.codec == CodecId::RawVideo && stream.media_type == MediaType::Video {
1208                let pinned = os.pixel_format.unwrap_or(PixelFormat::Yuv420p);
1209                os.pixel_format = Some(pinned);
1210                accepted_formats = Some(vec![pinned]);
1211            }
1212            // Colour range: a `format=` filter that converts to Y'CbCr decides
1213            // it; otherwise it rides through from the input. Decoders whose
1214            // native output is RGB (JPEG, PNG, GIF, WebP) are full-range by
1215            // definition, so an untagged input from one of those is Full, not
1216            // "unknown" — leaving it unspecified makes the muxer label the
1217            // samples limited-range and every reader then rescales them.
1218            // A colour conversion in the chain decides the output range;
1219            // otherwise it is whatever we reconciled the source to above.
1220            os.color_range = filters.output_color_range().unwrap_or(source_range);
1221            os.sample_rate = out_rate;
1222            os.channels = if target_channels > 0 {
1223                target_channels
1224            } else {
1225                stream.channels
1226            };
1227            // A CFR conversion re-times the stream: pts become slot indices.
1228            if let Some((num, den)) = output.frame_rate {
1229                if is_video {
1230                    os.time_base = rff_core::Rational::new(den as i32, num as i32);
1231                }
1232            }
1233            // A format pinned by the output codec NAME (`-c:a pcm_s16le`) wins:
1234            // it is an explicit request, and the muxer writes it into the
1235            // container header before any frame is seen. Otherwise compressed
1236            // decoders (AAC/Opus/Vorbis/FLAC/MP3) emit f32, so default to that
1237            // when the input doesn't declare a format.
1238            let target_sample_format = target.sample_format;
1239            os.sample_format = target_sample_format
1240                .or(stream.sample_format)
1241                .or(Some(SampleFormat::F32));
1242            // The muxer writes os.sample_format into the container header
1243            // BEFORE any frame is seen, so every frame must be conformed to
1244            // that committed format — decoders may legitimately emit either
1245            // layout (the FLAC decoder emits native s16 for 16-bit streams).
1246            let target_sample_format = target_sample_format.or(os.sample_format);
1247            // Audio encoders timestamp packets in per-channel samples, so the
1248            // output stream's time base is 1/sample_rate.
1249            if stream.media_type == MediaType::Audio && out_rate > 0 {
1250                os.time_base = rff_core::Rational::new(1, out_rate as i32);
1251            }
1252            Ok((
1253                StreamOp::Transcode(Box::new(TranscodeOp {
1254                    decoder,
1255                    encoder,
1256                    filters,
1257                    overlay: None,
1258                    in_time_base: stream.time_base,
1259                    is_video,
1260                    trim,
1261                    shift_ticks,
1262                    audio_clock_samples: 0,
1263                    fps,
1264                    audio_chain,
1265                    target_channels,
1266                    target_rate,
1267                    target_sample_format,
1268                    resampler: None,
1269                    accepted_formats,
1270                    pixel_converter: None,
1271                    source_range,
1272                    out_index,
1273                    max_video_frames: output.max_video_frames,
1274                    video_frames_sent: 0,
1275                    pending_pts: std::collections::VecDeque::new(),
1276                })),
1277                os,
1278            ))
1279        }
1280        // Stream copy: carry the same codec/packets through unchanged (the trim
1281        // window still applies, cutting video on keyframes).
1282        None => {
1283            let mut os = stream.clone();
1284            os.index = out_index;
1285            // `-c:s`: text subtitles share one packet contract, so choosing a
1286            // subtitle codec relabels the stream (SubRip ↔ WebVTT) in place.
1287            if stream.media_type == MediaType::Subtitle {
1288                if let Some(target) = output.subtitle_codec {
1289                    if target.media_type() != MediaType::Subtitle {
1290                        return Err(Error::unsupported(format!(
1291                            "-c:s: `{}` is not a subtitle codec",
1292                            target.name()
1293                        )));
1294                    }
1295                    os.codec_id = target;
1296                }
1297            }
1298            let trim = Trim::from_spec(output);
1299            let tb = stream.time_base;
1300            let to_ticks = |s: f64| (s * tb.den as f64 / tb.num.max(1) as f64).round() as i64;
1301            Ok((
1302                StreamOp::Copy(CopyOp {
1303                    out_index,
1304                    is_video: stream.media_type == MediaType::Video,
1305                    start_ticks: trim.map(|t| to_ticks(t.start)).unwrap_or(0),
1306                    end_ticks: trim.and_then(|t| t.end).map(to_ticks),
1307                    trimming: trim.is_some(),
1308                    started: false,
1309                }),
1310                os,
1311            ))
1312        }
1313    }
1314}
1315
1316/// Decode the first video frame of the overlay input and convert it to 4:2:0,
1317/// ready to composite onto the base's YUV frames.
1318fn decode_overlay_frame(
1319    engine: &Engine,
1320    demuxer: &mut dyn rff_format::Demuxer,
1321    streams: &[Stream],
1322) -> Result<VideoFrame> {
1323    let vidx = streams
1324        .iter()
1325        .position(|s| s.media_type == MediaType::Video)
1326        .ok_or_else(|| {
1327            Error::Option("filter_complex overlay: overlay input has no video".into())
1328        })?;
1329    let mut decoder = engine.codecs.find_decoder(streams[vidx].codec_id)?;
1330    decoder.configure(&codec_params(&streams[vidx]))?;
1331    let mut to_yuv = FilterChain::parse("format=yuv420p")?;
1332    let mut got_eof = false;
1333    loop {
1334        let frame = match demuxer.read_packet() {
1335            Ok(pkt) if pkt.stream_index as usize != vidx => continue,
1336            Ok(pkt) => {
1337                decoder.send_packet(&pkt)?;
1338                decoder.receive_frame()
1339            }
1340            Err(Error::Eof) if !got_eof => {
1341                got_eof = true;
1342                decoder.flush();
1343                decoder.receive_frame()
1344            }
1345            Err(e) => return Err(e),
1346        };
1347        match frame {
1348            Ok(Frame::Video(v)) => return to_yuv.apply(v),
1349            Ok(_) => continue,
1350            Err(Error::Again) if !got_eof => continue,
1351            Err(Error::Again) | Err(Error::Eof) => {
1352                return Err(Error::Option(
1353                    "filter_complex overlay: no decodable frame in the overlay input".into(),
1354                ))
1355            }
1356            Err(e) => return Err(e),
1357        }
1358    }
1359}
1360
1361/// Build the decoder configuration from a demuxed input stream.
1362fn codec_params(s: &Stream) -> CodecParams {
1363    CodecParams {
1364        codec_id: s.codec_id,
1365        width: s.width,
1366        height: s.height,
1367        pixel_format: s.pixel_format,
1368        sample_rate: s.sample_rate,
1369        channels: s.channels,
1370        sample_format: s.sample_format,
1371        extradata: s.extradata.clone(),
1372    }
1373}
1374
1375/// Route one demuxed packet through its stream's plan.
1376fn process_packet(
1377    packet: Packet,
1378    ops: &mut [StreamOp],
1379    muxer: &mut dyn Muxer,
1380    report: &mut TranscodeReport,
1381) -> Result<()> {
1382    let Some(op) = ops.get_mut(packet.stream_index) else {
1383        return Ok(()); // packet for a stream we didn't plan — drop it
1384    };
1385    match op {
1386        StreamOp::Skip => Ok(()),
1387        StreamOp::Copy(copy) => {
1388            if let Some(packet) = copy.process(packet) {
1389                muxer.write_packet(&packet)?;
1390                report.packets_written += 1;
1391            }
1392            Ok(())
1393        }
1394        StreamOp::Transcode(op) => {
1395            phases::time(&phases::DECODE, || op.decoder.send_packet(&packet))?;
1396            loop {
1397                match phases::time(&phases::DECODE, || op.decoder.receive_frame()) {
1398                    Ok(frame) => op.handle_frame(frame, muxer, report)?,
1399                    Err(Error::Again) | Err(Error::Eof) => break,
1400                    Err(e) => return Err(e),
1401                }
1402            }
1403            Ok(())
1404        }
1405    }
1406}
1407
1408/// At end of input, flush each transcoded stream's decoder, filter state, and
1409/// encoder, writing out anything still buffered.
1410fn flush_streams(
1411    ops: &mut [StreamOp],
1412    muxer: &mut dyn Muxer,
1413    report: &mut TranscodeReport,
1414) -> Result<()> {
1415    for op in ops.iter_mut() {
1416        if let StreamOp::Transcode(op) = op {
1417            op.finish(muxer, report)?;
1418        }
1419    }
1420    Ok(())
1421}
1422
1423/// Open an input and decide its container format — local file (seekable) or
1424/// `http://` URL. Delegates to the shared [`crate::probe`] opener so ffmpeg and
1425/// ffprobe resolve inputs identically.
1426fn open_input(engine: &Engine, input: &InputSpec) -> Result<(String, crate::probe::Source)> {
1427    let path = input
1428        .path
1429        .to_str()
1430        .ok_or_else(|| Error::Option("input path is not valid UTF-8".into()))?;
1431    crate::probe::open_source(engine, path, input.format.as_deref())
1432}
1433
1434/// Decide which container to mux an output as: explicit `-f`, else by
1435/// extension. An `rtmp://` target implies FLV — that is the payload RTMP
1436/// carries (matching FFmpeg's default for rtmp outputs).
1437fn resolve_output_format(engine: &Engine, output: &OutputSpec) -> Result<String> {
1438    if let Some(forced) = &output.format {
1439        return Ok(forced.clone());
1440    }
1441    if output.path.to_str().is_some_and(rff_io::is_rtmp) {
1442        return Ok("flv".to_string());
1443    }
1444    let ext = output
1445        .path
1446        .extension()
1447        .and_then(|e| e.to_str())
1448        .unwrap_or_default();
1449    engine
1450        .formats
1451        .by_extension(ext)
1452        .map(|f| f.name.to_string())
1453        .ok_or_else(|| {
1454            Error::MuxerNotFound(format!(
1455                "{} (no format for this extension — pass -f)",
1456                output.path.display()
1457            ))
1458        })
1459}
1460
1461#[cfg(test)]
1462mod sample_format_tests {
1463    use super::*;
1464
1465    fn f32_af(samples: &[f32]) -> Frame {
1466        f32_frame(samples.to_vec(), 44_100, 1, Some(0))
1467    }
1468
1469    /// `-c:a pcm_s16le` used to be silently ignored on decode: the codec NAME
1470    /// carries the format but `CodecId` does not, so raw output kept whatever
1471    /// the decoder emitted (f32), writing double the bytes under an s16 request.
1472    #[test]
1473    fn pinned_format_converts_f32_to_s16() {
1474        let src = [0.0f32, 0.5, -0.5, 1.0, -1.0];
1475        let out = conform_sample_format(Some(SampleFormat::S16), f32_af(&src)).unwrap();
1476        let Frame::Audio(af) = out else {
1477            unreachable!()
1478        };
1479        assert_eq!(af.format, SampleFormat::S16);
1480        assert_eq!(af.planes[0].len(), src.len() * 2, "s16 is 2 bytes/sample");
1481        let got: Vec<i16> = af.planes[0]
1482            .chunks_exact(2)
1483            .map(|b| i16::from_le_bytes([b[0], b[1]]))
1484            .collect();
1485        // Round-to-nearest, and full scale must CLAMP rather than wrap: 1.0 maps
1486        // to 32767, not to -32768 via overflow.
1487        assert_eq!(got, vec![0, 16384, -16384, 32767, -32768]);
1488    }
1489
1490    /// No pin, or a frame already in the target format, must pass through
1491    /// untouched — the conversion is not allowed to cost anything when idle.
1492    #[test]
1493    fn unpinned_or_matching_format_is_a_passthrough() {
1494        let src = [0.25f32, -0.25];
1495        let Frame::Audio(a) = conform_sample_format(None, f32_af(&src)).unwrap() else {
1496            unreachable!()
1497        };
1498        assert_eq!(a.format, SampleFormat::F32);
1499        let Frame::Audio(b) = conform_sample_format(Some(SampleFormat::F32), f32_af(&src)).unwrap()
1500        else {
1501            unreachable!()
1502        };
1503        assert_eq!(b.format, SampleFormat::F32);
1504        assert_eq!(b.planes[0], a.planes[0]);
1505    }
1506
1507    /// The codec name is the only place the format lives for raw PCM.
1508    #[test]
1509    fn codec_name_pins_the_sample_format() {
1510        assert_eq!(
1511            CodecId::sample_format_from_name("pcm_s16le"),
1512            Some(SampleFormat::S16)
1513        );
1514        assert_eq!(
1515            CodecId::sample_format_from_name("pcm_f32le"),
1516            Some(SampleFormat::F32)
1517        );
1518        // Bare `pcm` pins nothing, and compressed codecs never do.
1519        assert_eq!(CodecId::sample_format_from_name("pcm"), None);
1520        assert_eq!(CodecId::sample_format_from_name("mp3"), None);
1521    }
1522}