MP3Audio#

class minim.audio.MP3Audio(*args, **kwargs)[source]#

Bases: Audio, _ID3

MP3 audio file handler.

See also

For a full list of attributes and their descriptions, see Audio.

Parameters:

filestr or pathlib.Path

MP3 audio filename or path.

patterntuple, keyword-only, optional

Regular expression search pattern and the corresponding metadata field(s).

Valid values:

The supported metadata fields are

"artist" for the track artist,
"title" for the track title, and
"track_number" for the track number.

Examples:

("(.*) - (.*)", ("artist", "title")) matches filenames like “Taylor Swift - Red.mp3”.
("(\d*) - (.*)", ("track_number", "title")) matches filenames like “04 - I Knew You Were Trouble.mp3”.
("(\d*) (.*)", ("track_number", "title")) matches filenames like “06 22.mp3”.

multivaluebool

Determines whether multivalue tags are supported. If False, the items in value are concatenated using the separator(s) specified in sep.

sepstr or tuple, keyword-only, default: (", ", " & ")

Separator(s) to use to concatenate multivalue tags. If a str is provided, it is used to concatenate all values. If a tuple is provided, the first str is used to concatenate the first \(n - 1\) values, and the second str is used to append the final value.

Methods

`convert`	Convert the current audio file to another format.
`set_metadata_using_itunes`	Populate tags using data retrieved from the iTunes Search API.
`set_metadata_using_qobuz`	Populate tags using data retrieved from the Qobuz API.
`set_metadata_using_spotify`	Populate tags using data retrieved from the Spotify Web API and Spotify Lyrics service.
`set_metadata_using_tidal`	Populate tags using data retrieved from the TIDAL API.
`write_metadata`	Write metadata to file.

convert(codec: str, container: str = None, options: str = None, *, filename: str = None, preserve: bool = True) → None#

Convert the current audio file to another format.

Software dependency

Requires FFmpeg.

Note

The audio file handler is automatically updated to reflect the new audio file format. For example, converting a FLAC audio file to an ALAC audio file will change the file handler from a FLACAudio object to an MP4Audio object.

Parameters:

codecstr

New audio codec or coding format.

Valid values:

"aac", "m4a", "mp4", or "mp4a" for lossy AAC audio.
"alac" for lossless ALAC audio.
"flac" for lossless FLAC audio.
"mp3" for lossy MP3 audio.
"ogg" or "opus" for lossy Opus audio
"vorbis" for lossy Vorbis audio.
"lpcm", "wav", or "wave" for lossless LPCM audio.

containerstr, optional

New audio file container. If not specified, the best container is determined based on codec.

Valid values:

"flac" for a FLAC audio container, which only supports FLAC audio.
"m4a", "mp4", or "mp4a" for a MP4 audio container, which supports AAC and ALAC audio.
"mp3" for a MP3 audio container, which only supports MP3 audio.
"ogg" for an Ogg audio container, which supports FLAC, Opus, and Vorbis audio.
"wav" or "wave" for an WAVE audio container, which only supports LPCM audio.

optionsstr, optional

FFmpeg command-line options, excluding the input and output files, the -y flag (to overwrite files), and the -c:v copy argument (to preserve cover art for containers that support it).

Defaults:

AAC audio: "-c:a aac -b:a 256k" (or "-c:a libfdk_aac -b:a 256k" if FFmpeg was compiled with --enable-libfdk-aac)
ALAC audio: "-c:a alac"
FLAC audio: "-c:a flac"
MP3 audio: "-c:a libmp3lame -q:a 0"
Opus audio: "-c:a libopus -b:a 256k -vn"
Vorbis audio: "-c:a vorbis -strict experimental -vn" (or "-c:a libvorbis -vn" if FFmpeg was compiled with --enable-libvorbis)
WAVE audio: "-c:a pcm_s16le" or "-c:a pcm_s24le", depending on the bit depth of the original audio file.

filenamestr, keyword-only, optional

Filename of the converted audio file. If not provided, the filename of the original audio file, but with the appropriate new extension appended, is used.

preservebool, keyword-only, default: True

Determines whether the original audio file is kept.

set_metadata_using_itunes(data: dict[str, Any], *, album_data: dict[str, Any] = None, artwork_size: int | str = 1400, artwork_format: str = 'jpg', overwrite: bool = False) → None#

Populate tags using data retrieved from the iTunes Search API.

Parameters:

datadict: Information about the track in JSON format obtained using the iTunes Search API via minim.itunes.SearchAPI.search() or minim.itunes.SearchAPI.lookup().
album_datadict, keyword-only, optional: Information about the track’s album in JSON format obtained using the iTunes Search API via minim.itunes.SearchAPI.search() or minim.itunes.SearchAPI.lookup(). If not provided, album artist and copyright information is unavailable.
artwork_sizeint or str, keyword-only, default: 1400: Resized artwork size in pixels. If artwork_size="raw", the uncompressed high-resolution image is retrieved, regardless of size.
artwork_formatstr, keyword-only, {"jpg", "png"}: Artwork file format. If artwork_size="raw", the file format of the uncompressed high-resolution image takes precedence.
overwritebool, keyword-only, default: False: Determines whether existing metadata should be overwritten.

set_metadata_using_qobuz(data: dict[str, Any], *, artwork_size: str = 'large', comment: str = None, overwrite: bool = False) → None#

Populate tags using data retrieved from the Qobuz API.

Parameters:

datadict

Information about the track in JSON format obtained using the Qobuz API via minim.qobuz.PrivateAPI.get_track() or minim.qobuz.PrivateAPI.search().

artwork_sizestr, keyword-only, default: "large"

Artwork size.

Valid values: "large", "small", or "thumbnail".

commentstr, keyword-only, optional

Comment or description.

overwritebool, keyword-only, default: False

Determines whether existing metadata should be overwritten.

set_metadata_using_spotify(data: dict[str, Any], *, audio_features: dict[str, Any] = None, lyrics: str | dict[str, Any] = None, overwrite: bool = False) → None#

Populate tags using data retrieved from the Spotify Web API and Spotify Lyrics service.

Parameters:

datadict: Information about the track in JSON format obtained using the Spotify Web API via minim.spotify.WebAPI.get_track().
audio_featuresdict, keyword-only, optional: Information about the track’s audio features obtained using the Spotify Web API via minim.spotify.WebAPI.get_track_audio_features(). If not provided, tempo information is unavailable.
lyricsstr or dict, keyword-only: Information about the track’s formatted or time-synced lyrics obtained using the Spotify Lyrics service via minim.spotify.PrivateLyricsService.get_lyrics(). If not provided, lyrics are unavailable.
overwritebool, keyword-only, default: False: Determines whether existing metadata should be overwritten.

set_metadata_using_tidal(data: dict[str, Any], *, album_data: dict[str, Any] = None, artwork_size: int = 1280, composers: str | list[str] | dict[str, Any] = None, lyrics: dict[str, Any] = None, comment: str = None, overwrite: bool = False) → None#

Populate tags using data retrieved from the TIDAL API.

Parameters:

datadict

Information about the track in JSON format obtained using the TIDAL API via minim.tidal.API.get_track(), minim.tidal.API.search(), minim.tidal.PrivateAPI.get_track(), or minim.tidal.PrivateAPI.search().

album_datadict, keyword-only, optional

Information about the track’s album in JSON format obtained using the TIDAL API via minim.tidal.API.get_album(), minim.tidal.API.search(), minim.tidal.PrivateAPI.get_album(), or minim.tidal.PrivateAPI.search(). If not provided, album artist and disc and track numbering information is unavailable.

artwork_sizeint, keyword-only, default: 1280

Maximum artwork size in pixels.

Valid values: artwork_size should be between 80 and 1280.

composersstr, list, or dict, keyword-only, optional

Information about the track’s composers in a formatted str, a list, or a dict obtained using the TIDAL API via minim.tidal.PrivateAPI.get_track_composers(), minim.tidal.PrivateAPI.get_track_contributors(), or minim.tidal.PrivateAPI.get_track_credits(). If not provided, songwriting credits are unavailable.

lyricsstr or dict, keyword-only, optional

The track’s lyrics obtained using the TIDAL API via minim.tidal.PrivateAPI.get_track_lyrics().

commentstr, keyword-only, optional

Comment or description.

overwritebool, keyword-only, default: False

Determines whether existing metadata should be overwritten.

write_metadata() → None#: Write metadata to file.