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, reader) = open_source(engine, path_str, None)?;
50    let mut demuxer = engine.formats.open_demuxer(&format_name, reader)?;
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/// Open a path-or-URL as a streaming reader and decide its container format.
112///
113/// Local files keep the read-twice (sniff then open) path. Streams (URLs,
114/// pipes, UDP) are opened once, their head peeked for content sniffing, then
115/// chained back in front so the demuxer sees the whole stream from byte 0.
116/// HLS playlists (`-f hls`, an `.m3u8` name, or `#EXTM3U` content) expand to
117/// one chained stream over their TS segments first. Shared by [`probe`]
118/// (ffprobe) and the transcode input path (ffmpeg).
119pub(crate) fn open_source(
120    engine: &Engine,
121    path: &str,
122    forced: Option<&str>,
123) -> Result<(String, Box<dyn Read + Send>)> {
124    let stem = path.split(['?', '#']).next().unwrap_or(path);
125    if forced == Some("hls") || stem.to_ascii_lowercase().ends_with(".m3u8") {
126        let reader = rff_format_hls::open_input(path)?;
127        return sniff_stream(engine, reader, None, path);
128    }
129    if !rff_io::is_stream(path) {
130        let format = detect_input_format(engine, Path::new(path), forced)?;
131        return Ok((format, Box::new(std::fs::File::open(path)?)));
132    }
133    let reader = rff_io::open(path)?;
134    sniff_stream(engine, reader, forced, path)
135}
136
137/// Peek a stream's head, pick its format (forced > content sniff > URL
138/// extension), and hand back head+rest chained. An `#EXTM3U` head re-opens the
139/// source as HLS input (possible for URLs/files; a pipe can't be re-read).
140fn sniff_stream(
141    engine: &Engine,
142    mut reader: Box<dyn Read + Send>,
143    forced: Option<&str>,
144    path: &str,
145) -> Result<(String, Box<dyn Read + Send>)> {
146    let mut head = vec![0u8; 4096];
147    let n = read_some(&mut reader, &mut head)?;
148    head.truncate(n);
149    if forced.is_none() && head.starts_with(b"#EXTM3U") {
150        if rff_io::is_pipe(path) {
151            return Err(Error::unsupported(
152                "hls input from a pipe (the playlist's segments cannot be fetched relative to stdin)",
153            ));
154        }
155        let reader = rff_format_hls::open_input(path)?;
156        return sniff_stream(engine, reader, None, path);
157    }
158    let format = match forced {
159        Some(f) => f.to_string(),
160        None => engine
161            .formats
162            .probe(&head)
163            .map(|f| f.name.to_string())
164            .or_else(|| url_extension_format(engine, path))
165            .ok_or_else(|| Error::DemuxerNotFound(format!("{path} (pass -f)")))?,
166    };
167    let chained: Box<dyn Read + Send> = Box::new(std::io::Cursor::new(head).chain(reader));
168    Ok((format, chained))
169}
170
171/// Read up to `buf.len()` bytes, tolerating short reads (network streams arrive
172/// in pieces); stops at EOF.
173fn read_some(reader: &mut dyn Read, buf: &mut [u8]) -> Result<usize> {
174    let mut filled = 0;
175    while filled < buf.len() {
176        match reader.read(&mut buf[filled..]) {
177            Ok(0) => break,
178            Ok(n) => filled += n,
179            Err(ref e) if e.kind() == std::io::ErrorKind::Interrupted => continue,
180            Err(e) => return Err(e.into()),
181        }
182    }
183    Ok(filled)
184}
185
186/// Guess a container from a URL's extension (after the last `.`, ignoring any
187/// `?query`/`#fragment`).
188fn url_extension_format(engine: &Engine, url: &str) -> Option<String> {
189    let stem = url.split(['?', '#']).next().unwrap_or(url);
190    let ext = stem.rsplit('.').next().unwrap_or("");
191    engine.formats.by_extension(ext).map(|f| f.name.to_string())
192}
rff/probe.rs

rff/
probe.rs
