Crate moosicbox_lofty

Parse, convert, and write metadata to audio formats.

Supported Formats

File Format	Metadata Format(s)
AAC (ADTS)	ID3v2, ID3v1
Ape	APE, ID3v2*, ID3v1
AIFF	ID3v2, Text Chunks
FLAC	Vorbis Comments, ID3v2*
MP3	ID3v2, ID3v1, APE
MP4	iTunes-style ilst
MPC	APE, ID3v2*, ID3v1*
Opus	Vorbis Comments
Ogg Vorbis	Vorbis Comments
Speex	Vorbis Comments
WAV	ID3v2, RIFF INFO
WavPack	APE, ID3v1

* The tag will be read only, due to lack of official support

Examples

Reading a generic file

It isn’t always convenient to use concrete file types, which is where TaggedFile comes in.

Using a path

use moosicbox_lofty::{read_from_path, Probe};

// This will guess the format from the extension
// ("mp3" in this case), but we can guess from the content if we want to.
let path = "test.mp3";
let tagged_file = read_from_path(path)?;

// Let's guess the format from the content just in case.
// This is not necessary in this case!
let tagged_file2 = Probe::open(path)?.guess_file_type()?.read()?;

Using an existing reader

use moosicbox_lofty::{read_from, ParseOptions};
use std::fs::File;

// Let's read from an open file
let path = "test.mp3";
let mut file = File::open(path)?;

// Here, we have to guess the file type prior to reading
let tagged_file = read_from(&mut file)?;

Accessing tags

use moosicbox_lofty::{read_from_path, ParseOptions, TaggedFileExt};

let path = "test.mp3";
let tagged_file = read_from_path(path)?;

// Get the primary tag (ID3v2 in this case)
let id3v2 = tagged_file.primary_tag();

// If the primary tag doesn't exist, or the tag types
// don't matter, the first tag can be retrieved
let unknown_first_tag = tagged_file.first_tag();

Using concrete file types

use moosicbox_lofty::mpeg::MpegFile;
use moosicbox_lofty::{AudioFile, ParseOptions, TagType};
use std::fs::File;

let mut file_content = File::open(path)?;

// We are expecting an MP3 file
let mp3_file = MpegFile::read_from(&mut file_content, ParseOptions::new())?;

assert_eq!(mp3_file.properties().channels(), 2);

// Here we have a file with multiple tags
assert!(mp3_file.contains_tag_type(TagType::Id3v2));
assert!(mp3_file.contains_tag_type(TagType::Ape));

Important format-specific notes

All formats have their own quirks that may produce unexpected results between conversions. Be sure to read the module documentation of each format to see important notes and warnings.

Re-exports

pub use crate::error::LoftyError;

pub use crate::error::Result;

Modules

aac

AAC (ADTS) specific items

ape

APE specific items

error

Contains the errors that can arise within Lofty

flac

Items for FLAC

id3

ID3 specific items

iff

WAV/AIFF specific items

mp4

MP4 specific items

mpeg

MP3 specific items

musepack

Musepack specific items

ogg

Items for OGG container formats

resolve

Tools to create custom file resolvers

wavpack

WavPack specific items

Structs

BoundTaggedFile

A variant of TaggedFile that holds a File handle, and reflects changes such as tag removals.

ChannelMask

Channel mask

FileProperties

Various immutable audio properties

ParseOptions

Options to control how Lofty parses a file

Picture

Represents a picture.

PictureInformation

Information about a Picture

Probe

A format agnostic reader

Tag

Represents a parsed tag

TagItem

Represents a tag item (key/value)

TaggedFile

A generic representation of a file

Enums

FileType

The type of file read

ItemKey

A generic representation of a tag’s key

ItemValue

Represents a tag item’s value

MimeType

Mime types for pictures.

ParsingMode

The parsing strictness mode

PictureType

The picture type, according to ID3v2 APIC

TagType

The tag’s format

TextEncoding

The text encoding for use in ID3v2 frames

Traits

Accessor

Provides accessors for common items

AudioFile

Provides various methods for interaction with a file

MergeTag

The counterpart of SplitTag.

SplitTag

Split (and merge) tags.

TagExt

A set of common methods between tags

TaggedFileExt

Provides a common interface between TaggedFile and BoundTaggedFile

Functions

read_from

Read a TaggedFile from a File

read_from_path

Read a TaggedFile from a path

Derive Macros

LoftyFile

Creates a file usable by Lofty