Overview
The Probe struct scans a MediaSourceStream for metadata and container formats, providing methods to automatically detect and instantiate appropriate format readers.
Probe
Definition
pub struct Probe {
filter: BloomFilter,
registered: Vec<Descriptor>,
}
Probe uses a bloom filter for efficient format marker detection and maintains a list of registered format descriptors.
Methods
register_all
pub fn register_all<Q: QueryDescriptor>(&mut self)
Type implementing QueryDescriptor trait
use symphonia::core::probe::Probe;
use symphonia::format_ogg::OggReader;
let mut probe = Probe::default();
probe.register_all::<OggReader>();
register
pub fn register(&mut self, descriptor: &Descriptor)
The descriptor to register
pub fn format(
&self,
hint: &Hint,
mss: MediaSourceStream,
format_opts: &FormatOptions,
metadata_opts: &MetadataOptions,
) -> Result<ProbeResult>
MediaSourceStream for a container format. Metadata read during the search is queued and attached to the format reader.
Optional hints about the format (file extension, MIME type)
The media source stream to probe
Options for the format reader
Options for metadata parsing
Contains the instantiated FormatReader and any metadata discovered during probing
use symphonia::core::probe::Hint;
use symphonia::core::formats::FormatOptions;
use symphonia::core::meta::MetadataOptions;
use symphonia::core::io::MediaSourceStream;
use std::fs::File;
let file = File::open("audio.ogg")?;
let mss = MediaSourceStream::new(Box::new(file), Default::default());
let mut hint = Hint::new();
hint.with_extension("ogg");
let probe = symphonia::default::get_probe();
let probed = probe.format(
&hint,
mss,
&FormatOptions::default(),
&MetadataOptions::default()
)?;
let mut format = probed.format;
let metadata = probed.metadata;
next
pub fn next(&self, mss: &mut MediaSourceStream) -> Result<Instantiate>
MediaSourceStream for the next metadata or container format marker.
The media source stream to search
An instantiation function for either a FormatReader or MetadataReader
Hint
Definition
pub struct Hint {
extension: Option<String>,
mime_type: Option<String>,
}
Methods
new
Instantiate an empty Hint.
with_extension
pub fn with_extension(&mut self, extension: &str) -> &mut Self
The file extension (without the dot)
let mut hint = Hint::new();
hint.with_extension("mp3");
mime_type
pub fn mime_type(&mut self, mime_type: &str) -> &mut Self
The MIME type (e.g., “audio/mpeg”)
let mut hint = Hint::new();
hint.mime_type("audio/ogg");
ProbeResult
Definition
pub struct ProbeResult {
pub format: Box<dyn FormatReader>,
pub metadata: ProbedMetadata,
}
An instance of a format reader for the probed format
Metadata read during the probe operation before the format reader was instantiated. Container metadata is available through the format reader itself.
Definition
pub struct ProbedMetadata {
metadata: Option<MetadataLog>,
}
Methods
get
pub fn get(&mut self) -> Option<Metadata<'_>>
Metadata if any was present outside the container, None otherwise
into_inner
pub fn into_inner(self) -> Option<MetadataLog>
The metadata log if present
Descriptor
Definition
pub struct Descriptor {
pub short_name: &'static str,
pub long_name: &'static str,
pub extensions: &'static [&'static str],
pub mime_types: &'static [&'static str],
pub markers: &'static [&'static [u8]],
pub score: fn(&[u8]) -> u8,
pub inst: Instantiate,
}
A short ASCII-only string identifying the format
A longer, more descriptive string identifying the format
List of case-insensitive file extensions generally used by the format
List of case-insensitive MIME types generally used by the format
Byte-string start-of-stream markers searched for within the stream
Function to score a context buffer (0-255)
Instantiation function for the format
Instantiate
Definition
pub enum Instantiate {
Format(fn(MediaSourceStream, &FormatOptions) -> Result<Box<dyn FormatReader>>),
Metadata(fn(&MetadataOptions) -> Box<dyn MetadataReader>),
}
Format
fn(MediaSourceStream, &FormatOptions) -> Result<Box<dyn FormatReader>>
Instantiation function for a FormatReader
Metadata
fn(&MetadataOptions) -> Box<dyn MetadataReader>
Instantiation function for a MetadataReader
QueryDescriptor
Definition
pub trait QueryDescriptor {
fn query() -> &'static [Descriptor];
fn score(context: &[u8]) -> u8;
}
query
fn query() -> &'static [Descriptor]
List of format descriptors
score
fn score(context: &[u8]) -> u8
Confidence score from 0 (no confidence) to 255 (certain)
Complete Example
use symphonia::core::probe::{Hint, Probe};
use symphonia::core::formats::FormatOptions;
use symphonia::core::meta::MetadataOptions;
use symphonia::core::io::MediaSourceStream;
use std::fs::File;
fn probe_file(path: &str) -> Result<(), Box<dyn std::error::Error>> {
// Open the file
let file = File::open(path)?;
let mss = MediaSourceStream::new(Box::new(file), Default::default());
// Create hint from file path
let mut hint = Hint::new();
if let Some(ext) = std::path::Path::new(path).extension() {
hint.with_extension(ext.to_str().unwrap());
}
// Get the default probe with all enabled formats
let probe = symphonia::default::get_probe();
// Probe the format
let probed = probe.format(
&hint,
mss,
&FormatOptions::default(),
&MetadataOptions::default()
)?;
// Access the format reader
let mut format = probed.format;
// Print track information
for track in format.tracks() {
println!("Track {}: {:?}", track.id, track.codec_params.codec);
}
Ok(())
}
See Also
