Audio tagging and encoding API

Release:0.8.1
flacmanager.generate_flac_dirname(library_root, metadata)[source]

Build the directory for a track’s FLAC file.

Parameters:
  • library_root (str) – the FLAC library directory
  • metadata (dict) – the finalized metadata for a single track
Returns:

an absolute directory path

Return type:

str

flacmanager.generate_flac_basename(metadata)[source]

Build the filename for a track’s FLAC file.

Parameters:metadata (dict) – the finalized metadata for a single track
Returns:a relative file name
Return type:str
flacmanager.generate_mp3_dirname(library_root, metadata)[source]

Build the directory for a track’s MP3 file.

Parameters:
  • library_root (str) – the MP3 library directory
  • metadata (dict) – the finalized metadata for a single track
Returns:

an absolute directory path

Return type:

str

flacmanager.generate_mp3_basename(metadata)[source]

Build the filename for a track’s MP3 file.

Parameters:metadata (dict) – the finalized metadata for a single track
Returns:a relative file name
Return type:str

The directory and file names are configurable via the flacmanager.ini file. Here are the relevant excerpts (default):

[Organize]
library_root =
library_subroot_trie_key = album_artist
library_subroot_compilation_trie_key = album_title
library_subroot_trie_level = 1
album_folder = {album_artist}/{album_title}
ndisc_album_folder = ${album_folder}
compilation_album_folder = {album_title}
ndisc_compilation_album_folder = ${compilation_album_folder}
track_filename = {track_number:02d} {track_title}
ndisc_track_filename = {album_discnumber:02d}-${track_filename}
compilation_track_filename = ${track_filename} ({track_artist})
ndisc_compilation_track_filename = {album_discnumber:02d}-${compilation_track_filename}
use_xplatform_safe_names = yes

[FLAC]
library_root = ${Organize:library_root}/FLAC
library_subroot_trie_key = ${Organize:library_subroot_trie_key}
library_subroot_compilation_trie_key = ${Organize:library_subroot_compilation_trie_key}
library_subroot_trie_level = ${Organize:library_subroot_trie_level}
album_folder = ${Organize:album_folder}
ndisc_album_folder = ${Organize:ndisc_album_folder}
compilation_album_folder = ${Organize:compilation_album_folder}
ndisc_compilation_album_folder = ${Organize:ndisc_compilation_album_folder}
track_filename = ${Organize:track_filename}
ndisc_track_filename = ${Organize:ndisc_track_filename}
compilation_track_filename = ${Organize:compilation_track_filename}
ndisc_compilation_track_filename = ${Organize:ndisc_compilation_track_filename}
track_fileext = .flac
use_xplatform_safe_names = ${Organize:use_xplatform_safe_names}

[MP3]
library_root = ${Organize:library_root}/MP3
library_subroot_trie_key = ${Organize:library_subroot_trie_key}
library_subroot_trie_level = ${Organize:library_subroot_trie_level}
library_subroot_compilation_trie_key = ${Organize:library_subroot_compilation_trie_key}
album_folder = ${Organize:album_folder}
ndisc_album_folder = ${Organize:ndisc_album_folder}
compilation_album_folder = ${Organize:compilation_album_folder}
ndisc_compilation_album_folder = ${Organize:ndisc_compilation_album_folder}
track_filename = ${Organize:track_filename}
ndisc_track_filename = ${Organize:ndisc_track_filename}
compilation_track_filename = ${Organize:compilation_track_filename}
ndisc_compilation_track_filename = ${Organize:ndisc_compilation_track_filename}
track_fileext = .mp3
use_xplatform_safe_names = ${Organize:use_xplatform_safe_names}
class flacmanager.TrackState(ordinal, key, text)[source]

Bases: object

Represents the state of a single track at any given time during the rip-and-tag operation.

Parameters:
  • ordinal (int) – this state’s relative value
  • key (str) – uniquely identifies this state
  • text (str) – a short description of this state
key

The unique identifier for this state.

text

The track-independent short description of this state.

flacmanager.TRACK_EXCLUDED = TrackState(-1, 'EXCLUDED', 'excluded')

Indicates that a track is excluded from the rip-and-tag operation.

flacmanager.TRACK_PENDING = TrackState(0, 'PENDING', 'pending…')

Indicates that the rip-and-tag process has not yet begun for a track.

flacmanager.TRACK_ENCODING_FLAC = TrackState(1, 'ENCODING_FLAC', 'encoding CDDA to FLAC…')

Indicates that a track is being encoded from CDDA to FLAC format.

flacmanager.TRACK_DECODING_WAV = TrackState(2, 'DECODING_WAV', 'decoding FLAC to WAV…')

Indicates that a track is being decoded from FLAC to WAV format.

flacmanager.TRACK_ENCODING_MP3 = TrackState(3, 'ENCODING_MP3', 'encoding WAV to MP3…')

Indicates that a track is being encoded from WAV to MP3 format.

flacmanager.TRACK_REENCODING_MP3 = functools.partial(<function <lambda>>)

Indicates that a track is being re-encoded from WAV to MP3 format after clipping was detected in a prior encoding operation.

flacmanager.TRACK_FAILED = TrackState(99, 'FAILED', 'failed')

Indicates that an error occurred while processing a track.

flacmanager.TRACK_COMPLETE = TrackState(99, 'COMPLETE', 'complete')

Indicates that the rip-and-tag process has finished for a track.

class flacmanager.TrackEncodingStatus(track_label, pending=True)[source]

Bases: object

A simple state machine for a single track’s encoding status.

Parameters:
  • track_label (str) – the track’s display label
  • pending (bool) – the default True initializes status as TRACK_PENDING; set to False to initialize status as TRACK_EXCLUDED
state

The current state of encoding for this track.

transition_to(to_state)[source]

Advance this track’s encoding state from its current state to to_state, if permitted.

Parameters:to_state – the target encoding state, or any Exception to transition to TRACK_FAILED
Returns:True if the transition is successful, otherwise False
describe(message=None)[source]

Return a short display string for this track and its current status.

Parameters:message (str) – short piece of text to use with the track label (instead of the default message for the current state)
class flacmanager.FLACEncoder[source]

Bases: threading.Thread

A thread that rips CD-DA tracks to FLAC.

FLACEncoder threads are daemonized so that they are killed automatically if the program exits.

add_instruction(track_index, cdda_filename, flac_filename, mp3_filename, track_metadata)[source]

Schedule a track for FLAC encoding.

Parameters:
  • track_index (int) – index (not ordinal) of the track
  • cdda_filename (str) – absolute CD-DA file name
  • flac_filename (str) – absolute .flac file name
  • mp3_filename (str) – absolute .mp3 file name
  • track_metadata (dict) – tagging fields for this track
run()[source]

Rip CD-DA tracks to FLAC.

flacmanager.make_vorbis_comments(metadata)[source]

Create Vorbis comments for tagging from metadata.

Parameters:metadata (dict) – the metadata for a single track
Returns:Vorbis comment name/value pairs
Return type:dict

See also

Ogg Vorbis I format specification: comment field and header specification
The only (?) “official recommendation” for Vorbis comments
Xiph Wiki: VorbisComment
a (very) basic metadata format
Xiph Wiki: Field_names
official (?) proposed updates to the VorbisComment recommendations
Ogg Vorbis Comment Field Recommendations
Just a proposal, but linked directly from Xiph Wiki
flacmanager.encode_flac(cdda_filename, flac_filename, track_metadata, stdout_filename=None)[source]

Rip a CDDA file to a tagged FLAC file.

Parameters:
  • cdda_filename (str) – absolute CD-DA file name
  • flac_filename (str) – absolute .flac file name
  • track_metadata (dict) – tagging fields for this track
  • stdout_filename (str) – absolute file name for redirected stdout
class flacmanager.MP3Encoder(track_index, cdda_filename, flac_filename, mp3_filename, stdout_filename, track_metadata)[source]

Bases: threading.Thread

A thread that converts WAV files to MP3 files.

Parameters:
  • track_index (int) – index (not ordinal) of the track
  • cdda_filename (str) – absolute CD-DA file name
  • flac_filename (str) – absolute .flac file name
  • stdout_filename (str) – absolute file name for redirected stdout
  • track_metadata (dict) – tagging fields for this track

MP3Encoder threads are daemonized so that they are killed automatically if the program exits.

run()[source]

Decode FLAC to WAV, then encode WAV to MP3.

flacmanager.decode_wav(flac_filename, wav_filename, stdout_filename=None)[source]

Convert a FLAC file to a WAV file.

Parameters:
  • flac_filename (str) – absolute .flac file name
  • wav_filename (str) – absolute .wav file name
  • stdout_filename (str) – absolute file name for redirected stdout
flacmanager.make_id3v2_tags(metadata)[source]

Create ID3v2 frames for tagging from metadata.

Parameters:metadata (dict) – the metadata for a single track
Returns:ID3v2 frame name/value pairs
Return type:dict

See also

ID3 tag version 2.3.0
The most compatible standard for ID3 tagging
http://id3.org/iTunes
ID3 tagging idiosyncracies in Apple iTunes
MusicBrainz Picard
FLACManager does its best to get the tagging right the first time, but Picard is a fantastic post-encoding fixer-upper.
flacmanager.encode_mp3(wav_filename, mp3_filename, track_metadata, scale=None, stdout_filename=None)[source]

Convert a WAV file to an MP3 file.

Parameters:
  • wav_filename (str) – absolute .wav file name
  • mp3_filename (str) – absolute .mp3 file name
  • track_metadata (dict) – tagging fields for this track
  • scale (float) – multiply PCM data by this factor
  • stdout_filename (str) – absolute file name for redirected stdout

Settings for the flac and lame encoders are configurable via the flacmanager.ini file. Here are the relevant excerpts (default):

[FLAC]
flac_encode_options = --force --keep-foreign-metadata --verify
flac_decode_options = --force

[MP3]
lame_encode_options = --clipdetect -q 2 -V2 -b 224
flacmanager.get_lame_genres()[source]

Return the list of genres recognized by LAME.