audiotools.accuraterip — AccurateRip Lookup Service Module

The audiotools.accuraterip module contains classes and functions for performing lookups to the AccurateRip service.

ChecksumV1 Objects

class audiotools.accuraterip.ChecksumV1(total_pcm_frames [, sample_rate=44100][, is_first=False][, is_last=False][, pcm_frame_range=1])

A class for calculating AccurateRip’s version 1 checksum. total_pcm_frames is the length of the track to be checksummed. sample_rate, is_first and is_last are used to calculate the checksum properly at the beginning, middle and end of the disc. pcm_frame_range is used to calculate the checksum over a window’s worth of values.


The total number of PCM frames expected by ChecksumV1 equals total_pcm_frames + pcm_frame_range - 1. For example, given total_pcm_frames of 100 and a pcm_frame_range of 3, one will populate the ChecksumV1 object with 102 PCM frames and receive 3 checksum values. The first checksum is for frames[0:100], the second for frames[1:101] and the third for frames[2:102].

The purpose of this is to determine whether a track has been ripped accurately, but its samples are simply shifted by some positive or negative number of samples.


Updates the checksum in progress with the given audiotools.pcm.FrameList object. May raise ValueError if too many PCM frames are given to process.


Returns a list of 32-bit AccurateRip checksums, 1 per pcm_frame_range. May raise ValueError if not enough PCM frames have been processed.

Disc ID Objects

class audiotools.accuraterip.DiscID(track_numbers, track_offsets, lead_out_offset, freedb_disc_id)

An AccurateRip disc ID object used to perform lookups. track_numbers is a list of track numbers, starting from 1. track_offsets is a list of track offsets in CD sectors, not including the 2 second lead-in. lead_out_offset is the lead-out sector of the CD, not including the 2 second lead-in. freedb_disc_id is a string or audiotools.freedb.DiscID object of the disc’s FreeDB disc ID.


Returns the disc ID as a 39 character string that AccurateRip expects when performing lookups.

classmethod DiscID.from_cddareader(cddareader)

Given a audiotools.cdio.CDDAReader object, returns the DiscID of that disc.

classmethod DiscID.from_tracks(tracks)

Given a sorted list of audiotools.AudioFile objects, returns the DiscID as if those tracks were a CD.


This assumes all the tracks from the disc are present and are laid out in a conventional fashion with no “hidden” tracks or other oddities. The disc ID may not be accurate if that’s not the case.

classmethod DiscID.from_sheet(sheet, total_pcm_frames, sample_rate)

Given a audiotools.Sheet object along with the total length of the disc in PCM frames and the disc’s sample rate (typically 44100), returns the DiscID.

Performing Lookup

audiotools.accuraterip.perform_lookup(disc_id[, accuraterip_server][, accuraterip_port])

Given a DiscID object and optional AccurateRip hostname string and port, returns a dict of

{track_number:[(confidence, crc, crc2), ...], ...}

where track_number starts from 1, crc is an AccurateRip checksum integer and confidence is an integer of the match’s confidence level.

May return a dict of empty lists if no AccurateRip entry is found.

May raise urllib2.HTTPError if an error occurs querying the server.

Determining Match Offset

audiotools.accuraterip.match_offset(ar_matches, checksums, initial_offset)

ar_matches is a dict of

{track_number:[(confidence, crc, crc2), ...], ...}

values returned by perform_lookup().

checksums is a list of checksum integers returned by ChecksumV1.checksums().

initial_offset is the initial PCM frames offset of the checksums (which may be negative).

Returns a (checksum, confidence, offset) tuple of the best match found. If no matches are found, the checksum at offset 0 is returned and confidence is None.