1:mod:`audiotools.toc` --- the TOC File Parsing Module
2=====================================================
3
4.. module:: audiotools.toc
5   :synopsis: a Module for Parsing and Building CD TOC Files.
6
7
8
9The :mod:`audiotools.toc` module contains the TOCFile class
10used for parsing and building TOC files representing CD images.
11
12.. function:: read_tocfile(filename)
13
14   Takes a filename string and returns a new :class:`TOCFile` object.
15   Raises :exc:`TOCException` if some error occurs when reading
16   the file.
17
18.. exception:: TOCException
19
20   A subclass of :exc:`audiotools.SheetException` raised
21   when some parsing or reading error occurs when reading a TOC file.
22
23TOCFile Objects
24----------------
25
26.. class:: TOCFile()
27
28   This class is used to represent a .toc file.
29   It is not meant to be instantiated directly but returned from
30   the :func:`read_tocfile` function.
31
32.. method:: TOCFile.catalog()
33
34   Returns the TOC file's catalog number as a plain string,
35   or ``None`` if the TOC file contains no catalog number.
36
37.. method:: TOCFile.indexes()
38
39   Returns an iterator of index lists.
40   Each index is a tuple of CD sectors corresponding to a
41   track's offset on disk.
42
43.. method:: TOCFile.pcm_lengths(total_length, sample_rate)
44
45   Takes the total length of the entire CD, in PCM frames,
46   and the sample rate of the stream, in Hz.
47   Returns a list of PCM frame lengths for all audio tracks within
48   the TOC file.
49   This list of lengths can be used to split a single CD image
50   file into several individual tracks.
51
52.. method:: TOCFile.ISRCs()
53
54   Returns a dictionary of track_number -> ISRC values
55   for all tracks whose ISRC value is not empty.
56
57.. classmethod:: TOCFile.file(sheet, filename)
58
59   Takes a :class:`cue.Cuesheet`-compatible object with
60   :meth:`catalog`, :meth:`indexes`, :meth:`ISRCs` methods
61   along with a filename string.
62   Returns a new :class:`TOCFile` object.
63   This is used to convert other sort of Cuesheet-like objects
64   into actual TOC files.
65