Audio#

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

Bases: object

Generic audio file handler.

Subclasses for specific audio containers or formats include

  • FLACAudio for audio encoded using the Free Lossless Audio Codec (FLAC),

  • MP3Audio for audio encoded and stored in the MPEG Audio Layer III (MP3) format,

  • MP4Audio for audio encoded in the Advanced Audio Coding (AAC) format, encoded using the Apple Lossless Audio Codec (ALAC), or stored in a MPEG-4 Part 14 (MP4, M4A) container,

  • OggAudio for Opus or Vorbis audio stored in an Ogg file, and

  • WAVEAudio for audio encoded using linear pulse-code modulation (LPCM) and in the Waveform Audio File Format (WAVE).

Note

This class can instantiate a specific file handler from the list above for an audio file by examining its file extension. However, there may be instances when this detection fails, especially when the audio codec and format combination is rarely seen. As such, it is always best to directly use one of the subclasses above to create a file handler for your audio file when its audio codec and format are known.

Parameters:
filestr or pathlib.Path

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 - Cruel Summer.flac”.

  • ("(\d*) - (.*)", ("track_number", "title")) matches filenames like “04 - The Man.m4a”.

  • ("(\d*) (.*)", ("track_number", "title")) matches filenames like “13 You Need to Calm Down.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.

Attributes:
albumstr

Album title.

album_artiststr or list

Album artist(s).

artiststr or list

Artist(s).

artworkbytes or str

Byte-representation of, URL leading to, or filename of file containing the cover artwork.

bit_depthint

Bits per sample.

bitrateint

Bitrate in bytes per second (B/s).

channel_countint

Number of audio channels.

codecstr

Audio codec.

commentstr

Comment(s).

compilationbool

Whether the album is a compilation of songs by various artists.

composerstr or list

Composers, lyrics, and/or writers.

copyrightstr

Copyright information.

datestr

Release date.

disc_numberint

Disc number.

disc_countint

Total number of discs.

genrestr or list

Genre.

isrcstr

International Standard Recording Code (ISRC).

lyricsstr

Lyrics.

sample_rateint

Sample rate in Hz.

tempoint

Tempo in beats per minute (bpm).

titlestr

Track title.

track_numberint

Track number.

track_countint

Total number of tracks.

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.
convert(codec: str, container: str = None, options: str = None, *, filename: str = None, preserve: bool = True) → None[source]#

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[source]#

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[source]#

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[source]#

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[source]#

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.