rff/
probe.rs

1//! Media inspection — the engine side of `ffprobe`.
2//!
3//! [`probe`] opens an input, identifies its container, reads the stream
4//! headers, and returns a structured [`MediaInfo`]. The CLI's `ffprobe` and the
5//! server's `POST /v1/probe` both call straight into this.
6
7use std::io::Read;
8use std::path::Path;
9
10use rff_core::{CodecId, Error, MediaType, Rational, Result};
11
12use crate::Engine;
13
14/// Everything we learned about an input.
15#[derive(Debug, Clone)]
16pub struct MediaInfo {
17    /// Short name of the detected container format (e.g. `avi`).
18    pub format_name: String,
19    /// One entry per elementary stream.
20    pub streams: Vec<StreamInfo>,
21}
22
23/// Summary of one elementary stream.
24#[derive(Debug, Clone)]
25pub struct StreamInfo {
26    pub index: usize,
27    pub media_type: MediaType,
28    pub codec_id: CodecId,
29    pub time_base: Rational,
30    pub width: u32,
31    pub height: u32,
32    pub sample_rate: u32,
33    pub channels: u16,
34}
35
36/// Probe a media file at `path`.
37///
38/// The container is currently chosen by file extension; content-sniffing
39/// (reading magic bytes) is a planned upgrade. Reading the header itself relies
40/// on the corresponding demuxer, which is still scaffolded — so today this
41/// resolves the format and then surfaces the demuxer's
42/// [`Unimplemented`](rff_core::Error::Unimplemented) state. The plumbing is
43/// real; only the per-format parsing is pending.
44pub fn probe(engine: &Engine, path: impl AsRef<Path>) -> Result<MediaInfo> {
45    let path = path.as_ref();
46    let path_str = path
47        .to_str()
48        .ok_or_else(|| Error::Option("input path is not valid UTF-8".into()))?;
49    let (format_name, source) = open_source(engine, path_str, None)?;
50    let mut demuxer = source.open_demuxer(engine, &format_name)?;
51
52    let streams = demuxer.read_header()?;
53    let streams = streams
54        .into_iter()
55        .map(|s| StreamInfo {
56            index: s.index,
57            media_type: s.media_type,
58            codec_id: s.codec_id,
59            time_base: s.time_base,
60            width: s.width,
61            height: s.height,
62            sample_rate: s.sample_rate,
63            channels: s.channels,
64        })
65        .collect();
66
67    Ok(MediaInfo {
68        format_name,
69        streams,
70    })
71}
72
73/// Decide which container a path should be read as: an explicit `-f` override
74/// wins; otherwise sniff the file's leading bytes (content beats filename);
75/// otherwise fall back to the extension. Shared by [`probe`] and the transcode
76/// input path so both detect formats the same way.
77pub(crate) fn detect_input_format(
78    engine: &Engine,
79    path: &Path,
80    forced: Option<&str>,
81) -> Result<String> {
82    if let Some(name) = forced {
83        return Ok(name.to_string());
84    }
85    // Content sniff (best effort — an unreadable head just falls through).
86    if let Ok(head) = read_head(path, 4096) {
87        if let Some(format) = engine.formats.probe(&head) {
88            return Ok(format.name.to_string());
89        }
90    }
91    // Filename fallback.
92    let ext = path
93        .extension()
94        .and_then(|e| e.to_str())
95        .unwrap_or_default();
96    engine
97        .formats
98        .by_extension(ext)
99        .map(|f| f.name.to_string())
100        .ok_or_else(|| Error::DemuxerNotFound(path.display().to_string()))
101}
102
103/// Read up to `max` leading bytes of a file for content sniffing.
104fn read_head(path: &Path, max: usize) -> std::io::Result<Vec<u8>> {
105    let file = std::fs::File::open(path)?;
106    let mut buf = Vec::new();
107    file.take(max as u64).read_to_end(&mut buf)?;
108    Ok(buf)
109}
110
111/// An opened input. A local file stays seekable, so demuxers that can (MP4)
112/// read only their index and fetch payload on demand; everything else is a
113/// one-way byte stream.
114pub(crate) enum Source {
115    File(rff_format::SeekInput),
116    Stream(Box<dyn Read + Send>),
117}
118
119impl Source {
120    /// Open the demuxer for `format` over this source — the seek-aware one for
121    /// a file, when the format registered one.
122    pub(crate) fn open_demuxer(
123        self,
124        engine: &Engine,
125        format: &str,
126    ) -> Result<Box<dyn rff_format::Demuxer>> {
127        match self {
128            Source::File(file) => engine.formats.open_demuxer_seekable(format, file),
129            Source::Stream(stream) => engine.formats.open_demuxer(format, stream),
130        }
131    }
132}
133
134/// Open a path-or-URL as a [`Source`] and decide its container format.
135///
136/// Local files keep the read-twice (sniff then open) path and are opened
137/// buffered and seekable. Streams (URLs,
138/// pipes, UDP) are opened once, their head peeked for content sniffing, then
139/// chained back in front so the demuxer sees the whole stream from byte 0.
140/// HLS playlists (`-f hls`, an `.m3u8` name, or `#EXTM3U` content) expand to
141/// one chained stream over their TS segments first. Shared by [`probe`]
142/// (ffprobe) and the transcode input path (ffmpeg).
143pub(crate) fn open_source(
144    engine: &Engine,
145    path: &str,
146    forced: Option<&str>,
147) -> Result<(String, Source)> {
148    let stem = path.split(['?', '#']).next().unwrap_or(path);
149    if forced == Some("hls") || stem.to_ascii_lowercase().ends_with(".m3u8") {
150        let reader = rff_format_hls::open_input(path)?;
151        return sniff_stream(engine, reader, None, path);
152    }
153    if !rff_io::is_stream(path) {
154        let format = detect_input_format(engine, Path::new(path), forced)?;
155        let file = std::io::BufReader::new(std::fs::File::open(path)?);
156        return Ok((format, Source::File(Box::new(file))));
157    }
158    // RTP has no container to sniff: the reader classifies the stream by its
159    // payload type on the first packet and names the format itself.
160    if rff_io::is_rtp(path) {
161        let reader = rff_io::RtpReader::bind(path)?;
162        let format = forced
163            .map(str::to_string)
164            .unwrap_or_else(|| reader.format_name().to_string());
165        return Ok((format, Source::Stream(Box::new(reader))));
166    }
167    let reader = rff_io::open(path)?;
168    sniff_stream(engine, reader, forced, path)
169}
170
171/// Peek a stream's head, pick its format (forced > content sniff > URL
172/// extension), and hand back head+rest chained. An `#EXTM3U` head re-opens the
173/// source as HLS input (possible for URLs/files; a pipe can't be re-read).
174fn sniff_stream(
175    engine: &Engine,
176    mut reader: Box<dyn Read + Send>,
177    forced: Option<&str>,
178    path: &str,
179) -> Result<(String, Source)> {
180    let mut head = vec![0u8; 4096];
181    let n = read_some(&mut reader, &mut head)?;
182    head.truncate(n);
183    if forced.is_none() && head.starts_with(b"#EXTM3U") {
184        if rff_io::is_pipe(path) {
185            return Err(Error::unsupported(
186                "hls input from a pipe (the playlist's segments cannot be fetched relative to stdin)",
187            ));
188        }
189        let reader = rff_format_hls::open_input(path)?;
190        return sniff_stream(engine, reader, None, path);
191    }
192    let format = match forced {
193        Some(f) => f.to_string(),
194        None => engine
195            .formats
196            .probe(&head)
197            .map(|f| f.name.to_string())
198            .or_else(|| url_extension_format(engine, path))
199            .ok_or_else(|| Error::DemuxerNotFound(format!("{path} (pass -f)")))?,
200    };
201    let chained: Box<dyn Read + Send> = Box::new(std::io::Cursor::new(head).chain(reader));
202    Ok((format, Source::Stream(chained)))
203}
204
205/// Read up to `buf.len()` bytes, tolerating short reads (network streams arrive
206/// in pieces); stops at EOF.
207fn read_some(reader: &mut dyn Read, buf: &mut [u8]) -> Result<usize> {
208    let mut filled = 0;
209    while filled < buf.len() {
210        match reader.read(&mut buf[filled..]) {
211            Ok(0) => break,
212            Ok(n) => filled += n,
213            Err(ref e) if e.kind() == std::io::ErrorKind::Interrupted => continue,
214            Err(e) => return Err(e.into()),
215        }
216    }
217    Ok(filled)
218}
219
220/// Guess a container from a URL's extension (after the last `.`, ignoring any
221/// `?query`/`#fragment`).
222fn url_extension_format(engine: &Engine, url: &str) -> Option<String> {
223    let stem = url.split(['?', '#']).next().unwrap_or(url);
224    let ext = stem.rsplit('.').next().unwrap_or("");
225    engine.formats.by_extension(ext).map(|f| f.name.to_string())
226}
rff/probe.rs

rff/
probe.rs
