discid API

Python binding of Libdiscid

Libdiscid is a library to calculate MusicBrainz Disc IDs. This module provides a Python-like API for that functionality.

The user is expected to create a Disc object using read() or put() and extract the generated information.

Importing this module will open libdiscid at the same time and will raise OSError when libdiscid is not found.

Constants

At the module level there are these constants available:

discid.LIBDISCID_VERSION_STRING: The version string of the loaded libdiscid in the form "libdiscid x.y.z". For versions older than 0.4.0 the string is "libdiscid < 0.4.0".

discid.FEATURES

The features libdiscid supports for the platform as a list of strings. Some functions can raise NotImplementedError when a feature is not available. Some features might not be implemented in this Python module, see FEATURES_IMPLEMENTED.

See the libdiscid feature matrix for a list of supported features per platform.

discid.FEATURES_IMPLEMENTED = ['read', 'mcn', 'isrc']: The features implemented in this Python module as a list of strings. Some might not be available for your platform, see FEATURES.

Functions

These functions are used to create a Disc object.

discid.read(device=None, features=None)

Reads the TOC from the device given as string and returns a Disc object.

The device string can be either of str or bytes. However, it should in no case contain non-ASCII characters. If no device is given, a default, also given by get_default_device() is used.

You can optionally add a subset of the features in FEATURES or the whole list to read more than just the TOC. In contrast to libdiscid, read() won’t read any of the additional features by default.

Parameters:

device (str | bytes | None) – the device name to use or None for using the default device
features (Iterable[str] | None) – list of features to enable (“read” will always be assumed)

Raises:

DiscError – raised when reading the device fails
NotImplementedError – raised when libdiscid does not support reading discs on the current platform

Return type:

Disc

discid.put(first, last, disc_sectors, track_offsets)

Creates a TOC based on the information given and returns a Disc object.

Depending on how you get the total sector count, you might have to subtract 11400 (2:32 min.) for discs with data tracks.

Parameters:

first (int) – number of the first audio track
last (int) – number of the last audio track
disc_sectors (int) – the end of the last audio track, normally the total sector count of the disc
track_offsets (Sequence[int]) – list of all audio track offsets

Raises:

TOCError – raised when illegal parameters are provided

Disc object

class discid.Disc

The class of the object returned by read() or put().

property id: str: This is the MusicBrainz Disc ID, a str object.

property freedb_id: str: This is the FreeDB Disc ID (without category), a str object.

property first_track_num: int: Number of the first track

property last_track_num: int: Number of the last audio track

property pregap: int

Pregap of the first track in sectors.

This corresponds to the offset of the first track. A pregap of 150 sectors is typical for a CD and does not indicate any intentional gap before the first track.

Added in version 1.4.

property sectors: int: Total length in sectors

property length: int: This is an alias for sectors

property seconds: int: Total length in seconds

property mcn: str | None

This is the Media Catalogue Number (MCN/UPC/EAN)

It is set after the "mcn" feature was requested on a read and supported by the platform or None. If set, this is a str object.

property tracks: list[Track]: A list of Track objects for this Disc.

property submission_url: str | None

Disc ID / TOC submission URL for MusicBrainz

With this URL you can submit the current TOC as a new MusicBrainz Disc ID. This is a str object.

property toc_string: str | None

The TOC suitable as value of the toc parameter when accessing the MusicBrainz Web Service.

This is a str object and enables fuzzy searching when the actual Disc ID is not found.

Note that this is the unencoded value, which still contains spaces.

Track object

class discid.Track(disc, number)

Track objects are part of the Disc class.

Parameters:

disc (Disc) – the Disc object
number (int) – the track number

property number: int: The track number

property offset: int: The track offset

property sectors: int: The track length in sectors

property length: int: This is an alias for sectors

property seconds: int: Track length in seconds

property isrc: str | None

The International Standard Recording Code

This will be None when the "isrc" feature was not requested or not supported, otherwise this is a str object.

Exceptions

The discid module includes a custom exception to handle specific problems:

exception discid.DiscError

Bases: OSError

read() will raise this exception when an error occurred.

exception discid.TOCError

Bases: Exception

put() will raise this exception when illegal parameters are provided.