API Reference¶

The main methods of interacting with audio metadata are :func:load and :func:loads.

Core¶

audio_metadata.determine_format(data)[source]¶

Determine the format of a filepath, file-like object, or bytes-like object.

Parameters: data (bytes-like object, str, os.PathLike, or file-like object) – A bytes-like object, filepath, path-like object or file-like object of an audio file.
Returns: An appropriate audio format class if supported, else None.
Return type: Format

audio_metadata.load(f)[source]¶

Load audio metadata from a filepath or file-like object.

Parameters

f (str, os.PathLike, or file-like object) – A filepath, path-like object or file-like object of an audio file.

Returns

An audio format object of the appropriate type.

Return type

Format

Raises

FormatError – If the audio file is not valid.
UnsupportedFormat – If the audio file is not of a supported format.
ValueError – If f is not a valid str, path-like object, file-like object, or is unreadable.

audio_metadata.loads(b)[source]¶

Load audio metadata from a bytes-like object.

Parameters

b (bytes-like object) – A bytes-like object of an audio file.

Returns

An audio format object of the appropriate type.

Return type

Format

Raises

FormatError – If the audio file is not valid.
UnsupportedFormat – If the audio file is not of a supported format.
ValueError – If b is not a valid bytes-like object.

Exceptions¶

exception audio_metadata.AudioMetadataException[source]¶: Base exception for audio-metadata.

exception audio_metadata.FormatError[source]¶: The binary format of a data input is invalid.

exception audio_metadata.TagError[source]¶: A tag is not compliant with a specification.

exception audio_metadata.UnsupportedFormat[source]¶: An unsupported format, version, or profile was encountered.

Base Classes¶

class audio_metadata.Format[source]¶

Base class for audio format objects.

filepath¶

Path to audio file, if applicable.

Type: str

filesize¶

Size of audio file.

Type: int

pictures¶

A list of Picture objects.

Type: list

tags¶

A Tags object.

Type: Tags

class audio_metadata.Picture(mapping=None, **kwargs)[source]¶: Base class for picture objects.

class audio_metadata.StreamInfo(mapping=None, **kwargs)[source]¶: Base class for stream information objects.

class audio_metadata.Tags(mapping=None, **kwargs)[source]¶

Base class for tags objects.

FIELD_MAP¶

A mapping of format-specific field names to common aliases.

Type: frozenbidict

FLAC¶

class audio_metadata.FLAC[source]¶

FLAC file format object.

Extends Format.

cuesheet¶

The cuesheet metadata block.

Type: FLACCueSheet

pictures¶

A list of FLACPicture objects.

Type: list

seektable¶

The seektable metadata block.

Type: FLACSeekTable

streaminfo¶

The audio stream information.

Type: FLACStreamInfo

tags¶

The Vorbis comment metadata block.

Type: VorbisComments

class audio_metadata.FLACApplication(*, id, data)[source]¶

A FLAC application metadata block.

id¶

The 32-bit application identifier.

Type: str

data¶

The data defined by the application.

Type: bytes

class audio_metadata.FLACCueSheet(tracks, catalog_number, lead_in_samples, compact_disc)[source]¶

A FLAC cue sheet metadata block.

A list-like structure of FLACCueSheetTrack objects along with some information used in the cue sheet.

catalog_number¶

The media catalog number.

Type: str

lead_in_samples¶

The number of lead-in samples. This is only meaningful for CD-DA cuesheets. For others, it should be 0.

Type: int

compact_disc¶

True if the cue sheet corresponds to a compact disc, else False.

Type: bool

class audio_metadata.FLACCueSheetIndex(*, number, offset)[source]¶

A FLAC cue sheet track index point.

number¶

The index point number.

The first index in a track must have a number of 0 or 1.

Index numbers must increase by 1 and be unique within a track.

For CD-DA, an index number of 0 corresponds to the track pre-gab.

Type: int

offset¶

Offset in samples relative to the track offset.

Type: int

class audio_metadata.FLACCueSheetTrack(*, track_number, offset, isrc, type, pre_emphasis, indexes=NOTHING)[source]¶

A FLAC cue sheet track.

track_number¶

The track number of the track.

0 is not allowed to avoid conflicting with the CD-DA spec lead-in track.

For CD-DA, the track number must be 1-99 or 170 for the lead-out track.

For non-CD-DA, the track number must be 255 for the lead-out track.

Track numbers must be unique within a cue sheet.

Type: int

offset¶

Offset in samples relative to the beginning of the FLAC audio stream.

Type: int

isrc¶

The ISRC (International Standard Recording Code) of the track.

Type: str

type¶

0 for audio, 1 for non-audio.

Type: int

pre_emphasis¶

True if contains pre-emphasis, False if not.

Type: bool

indexes¶

The index points for the track as FLACCueSheetIndex objects.

Type: list

class audio_metadata.FLACMetadataBlock(*, type, data)[source]¶

Generic FLAC metadata block.

type¶

Metadata block type index.

Type: int

data¶

The binary metadata block data.

Type: bytes

class audio_metadata.FLACPadding(*, size)[source]¶

A FLAC padding metadata block.

size¶

The size of the padding.

Type: int

class audio_metadata.FLACPicture(mapping=None, **kwargs)[source]¶

A FLAC picture object.

type¶

The picture type according to the ID3v2 APIC frame format.

Type: ID3PictureType

mime_type¶

The mime type of the picture. May indicate that the picture data is an URL of the picture instead of picture data.

Type: str

description¶

The description of the picture.

Type: str

width¶

The width of the picture in pixels.

Type: int

height¶

The height of the picture in pixels.

Type: int

bit_depth¶

The color depth of the picture in bits-per-pixel.

Type: int

colors¶

For indexed-color pictures (e.g. GIF), the number of colors used. Should be 0 for non-indexed-color pictures.

Type: int

data¶

The binary picture data.

Type: bytes

class audio_metadata.FLACSeekPoint(*, first_sample, offset, num_samples)[source]¶

class audio_metadata.FLACSeekTable(initlist=None)[source]¶

class audio_metadata.FLACStreamInfo(*, start, size, min_block_size, max_block_size, min_frame_size, max_frame_size, bit_depth, bitrate, channels, duration, md5, sample_rate)[source]¶

class audio_metadata.FLACVorbisComments(*args, **kwargs)[source]¶

ID3v1¶

class audio_metadata.ID3v1(mapping=None, **kwargs)[source]¶

class audio_metadata.ID3v1Fields(mapping=None, **kwargs)[source]¶

ID3v2¶

class audio_metadata.ID3v2(mapping=None, **kwargs)[source]¶

class audio_metadata.ID3v2Flags(*, unsync=False, compressed=False, extended=False, experimental=False, footer=False)[source]¶

class audio_metadata.ID3v2Frames(mapping=None, *, id3_version=<ID3Version.v24>, **kwargs)[source]¶

class audio_metadata.ID3v2Header(*, size, version, flags)[source]¶

MP3¶

class audio_metadata.MP3[source]¶

MP3 file format object.

Extends Format.

pictures¶

A list of ID3v2Picture objects.

Type: list

streaminfo¶

The audio stream information.

Type: MP3StreamInfo

tags¶

The ID3v2 tag frames, if present.

Type: ID3v2Frames

class audio_metadata.LAMEEncodingFlags(*, nogap_continuation, nogap_continued, nssafejoint, nspsytune)[source]¶

class audio_metadata.LAMEHeader(*, crc, version, revision, ath_type, audio_crc, audio_size, bitrate, bitrate_mode, channel_mode, delay, encoding_flags, lowpass_filter, mp3_gain, noise_shaping, padding, preset, replay_gain, source_sample_rate, surround_info, unwise_settings_used)[source]¶

class audio_metadata.LAMEReplayGain(*, peak, track_type, track_origin, track_adjustment, album_type, album_origin, album_adjustment)[source]¶

class audio_metadata.MP3StreamInfo(*, start, end, size, vbri, xing, version, layer, protected, bitrate, bitrate_mode, channel_mode, channels, duration, sample_rate)[source]¶

class audio_metadata.MPEGFrameHeader(*, start, size, vbri, xing, version, layer, protected, padded, bitrate, channel_mode, channels, sample_rate)[source]¶

class audio_metadata.VBRIHeader(*, version, delay, quality, num_bytes, num_frames, num_toc_entries, toc_scale_factor, toc_entry_num_bytes, toc_entry_num_frames, toc)[source]¶

class audio_metadata.VBRIToC(initlist=None)[source]¶

class audio_metadata.XingHeader(*, lame, num_frames, num_bytes, toc, quality)[source]¶

class audio_metadata.XingToC(initlist=None)[source]¶

Ogg¶

class audio_metadata.Ogg[source]¶

Ogg file format object.

Extends Format.

Base class for various formats using an Ogg container.

class audio_metadata.OggPage(*, header, is_complete, is_continued, is_first, is_last, position, serial_number, sequence_number, crc, num_segments, segments)[source]¶

class audio_metadata.OggPageHeader(*, start, version, is_continued, is_first, is_last, position, serial_number, sequence_number, crc, num_segments)[source]¶

class audio_metadata.OggPageSegments(initlist=None)[source]¶

Ogg Opus¶

class audio_metadata.OggOpus[source]¶

Ogg Opus file format object.

Extends Format.

pictures¶

A list of FLACPicture objects.

Type: list

streaminfo¶

The audio stream information.

Type: OggOpusStreamInfo

tags¶

The Vorbis comment metadata block.

Type: OggOpusVorbisComments

class audio_metadata.OggOpusStreamInfo(*, start, size, version, bitrate, channel_map, channels, duration, output_gain, pre_skip, sample_rate=48000, source_sample_rate)[source]¶

class audio_metadata.OggOpusVorbisComments(*args, **kwargs)[source]¶

Ogg Vorbis¶

class audio_metadata.OggVorbis[source]¶

Ogg Vorbis file format object.

Extends Format.

pictures¶

A list of FLACPicture objects.

Type: list

streaminfo¶

The audio stream information.

Type: OggVorbisStreamInfo

tags¶

The Vorbis comment metadata block.

Type: OggVorbisComments

class audio_metadata.OggVorbisStreamInfo(*, start, size, version, bitrate, channels, duration, max_bitrate, min_bitrate, nominal_bitrate, sample_rate)[source]¶

class audio_metadata.OggVorbisComments(*args, **kwargs)[source]¶

Vorbis¶

class audio_metadata.VorbisComment(*, value, name)[source]¶

class audio_metadata.VorbisComments(*args, **kwargs)[source]¶

WAV¶

class audio_metadata.WAVE[source]¶

WAVE file format object.

Extends Format.

pictures¶

A list of ID3v2Picture objects.

Type: list

streaminfo¶

The audio stream information.

Type: WAVStreamInfo

tags¶

The ID3v2 or RIFF tags, if present.

Type: ID3v2Frames or RIFFTags

class audio_metadata.RIFFTag(*, name, value)[source]¶

class audio_metadata.RIFFTags(mapping=None, **kwargs)[source]¶

class audio_metadata.WAVEStreamInfo(*, start, size, extension_data, audio_format, bit_depth, bitrate, channels, duration, sample_rate)[source]¶

class audio_metadata.WAVESubchunk(*, id, data)[source]¶