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 old versions 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.

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=[])

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

That string can be either of: str, unicode 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.

A DiscError exception is raised when the reading fails, and NotImplementedError when libdiscid doesn’t support reading discs on the current platform.

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

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

Takes the first track and last audio track as int. disc_sectors is the end of the last audio track, normally the total sector count of the disc. track_offsets is a list of all audio track offsets.

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

A TOCError exception is raised when illegal parameters are provided.

You can get the device that is used as a default with

discid.get_default_device()

The default device to use for read() on this platform given as a unicode or str object.

Disc object

class discid.Disc

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

id

This is the MusicBrainz Disc ID, a unicode or str object.

freedb_id

This is the FreeDB Disc ID (without category), a unicode or str object.

submission_url

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 unicode or str object.

toc_string

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

This is a unicode or 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.

New in version 1.1.

first_track_num

Number of the first track

last_track_num

Number of the last audio track

sectors

Total length in sectors

length

This is an alias for sectors

seconds

Total length in seconds

mcn

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 unicode or str object.

tracks

A list of Track objects for this Disc.

Track object

class discid.Track(disc, number)

Track objects are part of the Disc class.

number

The track number

offset

The track offset

sectors

The track length in sectors

length

This is an alias for sectors

seconds

Track length in seconds

isrc

The International Standard Recording Code

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

Exceptions

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

exception discid.DiscError

Bases: exceptions.IOError

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

exception discid.TOCError

Bases: exceptions.Exception

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