discid
discid allows you to calculate MusicBrainz or FreeDB disc IDs for audio CDs.
discid provides bindings to the MusicBrainz libdiscid library. In addition to calculating the disc IDs you can also get advanced data from the audio CD such as MCN (media catalogue number) and per-track ISRCs.
Here is a basic example on how to use this library:
use fmt;
use discid;
export fn main() void = {
// Create a new DiscId instance. Make sure to call close after
// the instance is no longer needed to free the memory.
const disc = discid::new();
defer discid::close(disc);
// Specifying the device is optional. If set to void
// a platform specific default will be used.
const device = "/dev/cdrom";
// In addition to the TOC libdiscid can also read MCN and
// ISRC info. Here we request both the TOC and the MCN.
const features = discid::features::READ | discid::features::MCN;
// Actually access the drive and read the requested data.
match (discid::read_features(disc, device, features)) {
case let err: discid::error => fmt::fatal(err);
case =>
// Print the disc ID (as calculated from the TOC) and
// the read MCN (which might be empty).
fmt::printfln("DiscID: {}", discid::get_id(disc))!;
fmt::printfln("MCN : {}", discid::get_mcn(disc))!;
};
};
Index
Types
type DiscId = *opaque;
type features = enum {
READ = 1,
MCN = 2,
ISRC = 4,
};
Errors
type error = !str;
Functions
@symbol("discid_free") fn close(disc: DiscId) void;
fn get_default_device() const str;
fn get_disc_duration(disc: DiscId) time::duration;
@symbol("discid_get_first_track_num") fn get_first_track_num(disc: DiscId) int;
fn get_freedb_id(disc: DiscId) const str;
fn get_id(disc: DiscId) const str;
@symbol("discid_get_last_track_num") fn get_last_track_num(disc: DiscId) int;
fn get_mcn(disc: DiscId) const str;
@symbol("discid_get_sectors") fn get_sectors(disc: DiscId) int;
fn get_submission_url(disc: DiscId) const str;
fn get_toc_string(disc: DiscId) const str;
fn get_track_duration(disc: DiscId, track_num: int) (time::duration | error);
fn get_track_isrc(disc: DiscId, track_num: int) (const str | error);
fn get_track_length(disc: DiscId, track_num: int) (int | error);
fn get_track_offset(disc: DiscId, track_num: int) (int | error);
fn get_version_string() const str;
@symbol("discid_has_feature") fn has_feature(feature: features) bool;
@symbol("discid_new") fn new() DiscId;
fn parse(disc: DiscId, toc: str) (void | error | nomem);
fn put(disc: DiscId, first: int, offsets: []int) (void | error);
fn read(disc: DiscId, device: (str | void) = void, features: features = features::READ) (void | error | nomem);
Types
type DiscId
type DiscId = *opaque;
A transparent handle for an Audio CD.
This is returned by new and has to be passed as the first parameter to all functions.
Use read, put or parse to initialize an instance of DiscId.
type features
type features = enum {
READ = 1,
MCN = 2,
ISRC = 4,
};
Enum representing the platform dependent features supported by libdiscid.
For an overview which feature is supported on which platform see https://musicbrainz.org/doc/libdiscid#Feature_Matrix
Errors
type error
type error = !str;
This is returned on errors reading the disc or setting the TOC.
Functions
fn close
@symbol("discid_free") fn close(disc: DiscId) void;
Release the memory allocated for the DiscId object.
fn get_default_device
fn get_default_device() const str;
Return the name of the default disc drive for this operating system.
The default device is system dependent, e.g. "/dev/cdrom" on Linux and "D:" on Windows.
fn get_disc_duration
fn get_disc_duration(disc: DiscId) time::duration;
Return the total duration of the disc as time::duration.
fn get_first_track_num
@symbol("discid_get_first_track_num") fn get_first_track_num(disc: DiscId) int;
Return the number of the first track on this disc.
fn get_freedb_id
fn get_freedb_id(disc: DiscId) const str;
Return the FreeDB disc ID.
fn get_id
fn get_id(disc: DiscId) const str;
Return the MusicBrainz disc ID.
fn get_last_track_num
@symbol("discid_get_last_track_num") fn get_last_track_num(disc: DiscId) int;
Return the number of the last track on this disc.
fn get_mcn
fn get_mcn(disc: DiscId) const str;
Return the media catalogue number on the disc, if present.
This is essentially an EAN (= UPC with 0 prefix).
fn get_sectors
@symbol("discid_get_sectors") fn get_sectors(disc: DiscId) int;
Return the length of the disc in sectors.
fn get_submission_url
fn get_submission_url(disc: DiscId) const str;
Return an URL for submitting the DiscID to MusicBrainz.
The URL leads to an interactive disc submission wizard that guides the user through the process of associating this disc's DiscID with a release in the MusicBrainz database.
fn get_toc_string
fn get_toc_string(disc: DiscId) const str;
Return a string representing CD Table Of Contents (TOC).
The TOC string is a list of integers separated by a single space character. The integers represent (in order):
- First track number (normally one)
- Last track number
- Lead-out track offset
- Up to 99 frame offsets
fn get_track_isrc
fn get_track_isrc(disc: DiscId, track_num: int) (const str | error);
Return the ISRC for a track.
Only track numbers between (and including) get_first_track_num and get_last_track_num may be used.
fn get_track_length
fn get_track_length(disc: DiscId, track_num: int) (int | error);
Return the length of a track in sectors.
Only track numbers between (and including) get_first_track_num and get_last_track_num may be used.
fn get_track_offset
fn get_track_offset(disc: DiscId, track_num: int) (int | error);
Return the sector offset of a track.
Only track numbers between (and including) get_first_track_num and get_last_track_num may be used.
fn get_version_string
fn get_version_string() const str;
Return version information about libdiscid.
The returned string will be e.g. "libdiscid 0.6.2".
fn has_feature
@symbol("discid_has_feature") fn has_feature(feature: features) bool;
Check if a certain feature is implemented on the current platform.
This only works for single features, not bit masks with multiple features.
fn new
@symbol("discid_new") fn new() DiscId;
Return a handle for a new DiscId object.
fn parse
fn parse(disc: DiscId, toc: str) (void | error | nomem);
Parses a TOC string.
The TOC string provided here must have the same format as returned by get_toc_string.
This function can be used if you already have a TOC string like e.g. "1 11 242457 150 44942 61305 72755 96360 130485 147315 164275 190702 205412 220437".
fn put
fn put(disc: DiscId, first: int, offsets: []int) (void | error);
Provides the TOC of a known CD.
This function may be used if the TOC has been read earlier and you want to calculate the disc ID afterwards, without accessing the disc drive.
first is the track number of the first track (1-99). The offsets parameter points to an array which contains the track offsets for each track. The first element, offsets[0], is the lead-out track. It must contain the total number of sectors on the disc. offsets must not be longer than 100 elements (lead-out + 99 tracks).
fn read
fn read(disc: DiscId, device: (str | void) = void, features: features = features::READ) (void | error | nomem);
Read the disc in the given CD-ROM/DVD-ROM drive, optionally with additional features.
This function reads the disc in the drive specified by the given device name. The device name is system dependent, e.g. it might be "/dev/cdrom" on Linux or "D:" on Windows. If device is set to void, the default device, as returned by get_default_device, is used.
By default this function will only read the TOC, hence only the disc ID itself will be available. Use the features parameter if you want to read also MCN and ISRCs.
The parameter "features" accepts a bitwise combination of values defined with the features enum. features::READ is always implied, so it is no necessary to specify it.
Reading MCN and ISRCs is not available on all platforms. You can use the has_feature method to check if a specific feature is available. Passing unsupported features here will just be ignored.
Note that reading MCN and ISRC data is significantly slower than just reading the TOC, so only request the features you actually need.