Struct lofty::Probe

pub struct Probe<R: Read> { /* private fields */ }

A format agnostic reader

This provides a way to determine the FileType of a reader, for when a concrete type is not known.

Usage

When reading from a path, the FileType will be inferred from the path, rather than the open file.

use lofty::FileType;

let probe = Probe::open("path/to/my.mp3")?;

// Inferred from the `mp3` extension
assert_eq!(probe.file_type(), Some(FileType::Mpeg));

When a path isn’t available, or is unreliable, content-based detection is also possible.

use lofty::FileType;

// Our same path probe with a guessed file type
let probe = Probe::open("path/to/my.mp3")?.guess_file_type()?;

// Inferred from the file's content
assert_eq!(probe.file_type(), Some(FileType::Mpeg));

Or with another reader

use lofty::FileType;
use std::io::Cursor;

static MAC_HEADER: &[u8; 3] = b"MAC";

let probe = Probe::new(Cursor::new(MAC_HEADER)).guess_file_type()?;

// Inferred from the MAC header
assert_eq!(probe.file_type(), Some(FileType::Ape));

Implementations

impl<R: Read> Probe<R>

pub const fn new(reader: R) -> Self

Create a new Probe

Before creating a Probe, consider wrapping it in a BufReader for better performance.

Examples

use lofty::Probe;
use std::fs::File;
use std::io::BufReader;

let file = File::open(path)?;
let reader = BufReader::new(file);

let probe = Probe::new(reader);

pub fn with_file_type(reader: R, file_type: FileType) -> Self

Create a new Probe with a specified FileType

Before creating a Probe, consider wrapping it in a BufReader for better performance.

Examples

use lofty::{FileType, Probe};
use std::fs::File;
use std::io::BufReader;

// We know the file is going to be an MP3,
// so we can skip the format detection
let file = File::open(my_mp3_path)?;
let reader = BufReader::new(file);

let probe = Probe::with_file_type(reader, FileType::Mpeg);

pub fn file_type(&self) -> Option<FileType>

Returns the current FileType

Examples

use lofty::{FileType, Probe};

let probe = Probe::new(reader);

let file_type = probe.file_type();

pub fn set_file_type(self, file_type: FileType) -> Self

Set the FileType with which to read the file

Examples

use lofty::{FileType, Probe};

let mut probe = Probe::new(reader);
assert_eq!(probe.file_type(), None);

let probe = probe.set_file_type(FileType::Mpeg);

assert_eq!(probe.file_type(), Some(FileType::Mpeg));

pub fn options(self, options: ParseOptions) -> Self

Set the ParseOptions for the Probe

Examples

use lofty::{ParseOptions, Probe};

// By default, properties will be read.
// In this example, we want to turn this off.
let options = ParseOptions::new().read_properties(false);

let probe = Probe::new(reader).options(options);

pub fn into_inner(self) -> R

Extract the reader

Examples

use lofty::{FileType, Probe};

let probe = Probe::new(reader);

let reader = probe.into_inner();

impl Probe<BufReader<File>>

pub fn open<P>(path: P) -> Result<Self>

where P: AsRef<Path>,

Opens a file for reading

This will initially guess the FileType from the path, but this can be overwritten with Probe::guess_file_type or Probe::set_file_type

Errors

• path does not exist

Examples

use lofty::{FileType, Probe};

let probe = Probe::open("path/to/my.mp3")?;

// Guessed from the "mp3" extension, see `FileType::from_ext`
assert_eq!(probe.file_type(), Some(FileType::Mpeg));

impl<R: Read + Seek> Probe<R>

pub fn guess_file_type(self) -> Result<Self>

Attempts to get the FileType based on the data in the reader

On success, the file type will be replaced

NOTE: The chance for succeeding is influenced by ParseOptions. Be sure to set it with Probe::options() prior to calling this method. Some files may require more than the default ParseOptions::DEFAULT_MAX_JUNK_BYTES to be detected successfully.

Errors

All errors that occur within this function are std::io::Error. If an error does occur, there is likely an issue with the provided reader, and the entire Probe should be discarded.

Examples

use lofty::{FileType, Probe};

let probe = Probe::new(reader).guess_file_type()?;

// Determined the file is MP3 from the content
assert_eq!(probe.file_type(), Some(FileType::Mpeg));

pub fn read(self) -> Result<TaggedFile>

Attempts to extract a TaggedFile from the reader

If read_properties is false, the properties will be zeroed out.

Errors

• No file type
  • This expects the file type to have been set already, either with Probe::guess_file_type or Probe::set_file_type. When reading from paths, this is not necessary.
• The reader contains invalid data

Panics

If an unregistered FileType (FileType::Custom) is encountered. See register_custom_resolver.

Examples

use lofty::{FileType, Probe};

let probe = Probe::new(reader).guess_file_type()?;

let parsed_file = probe.read()?;