Per second of playing time, a CD contains 75 CD frames, each containing 588 stereo audio frames (that is, pairs of left and right channel audio samples). A CD frame has both audio and nonaudio information. The sum of the nonaudio information in a frame composes a single complete chunk of subcode. When in audio mode and reading from a CD, you need complete subcodes. Thus, in audio mode, a CD frame is the smallest parcel of information you can read from a CD.

To give you controlled access to either the audio data or the subcode in a CD frame, libcdaudio hands you a CDFRAME structure:

typedef struct cdframe {
char audio[CDDA_DATASIZE];
struct subcodeQ ;subcode;
} ;CDFRAME;

An audio sample is linearly encoded in a 16-bit two's-complement format. Because a complete stereo audio sample contains two interleaved channels, it takes four bytes of audio[] to contain a complete stereo audio sample.

Figure 8-1 shows the structure of a CD audio sample.

Figure 8-1. CD Audio Sample Structure

The byte ordering of the samples in audio[] is the raw data from the CD; its byte ordering is reversed from that on the Indigo workstation. The sampling rate at which CD audio data is originally recorded is 44.1 kHz; therefore, CDDA_DATASIZE (the size of audio[]) is defined as 2352. This allows for 588 stereo audio samples per CD frame, which, at 75 frames per second, allows for a sample rate of 44.1 kHz.

The subcode member has three information modes:

Thus, the subcodeQ structure in the CDFRAME structure contains a union of three structures: mode1, mode2, and mode3. Which mode is used depends on the information from the CD.

For more information on the CDFRAME structure and the subcodeQ structure, see the CDFRAME(4) man page.

As many as 99 audio program tracks are allowed on a CD. These tracks are numbered 01 through 99. Two nonaudio tracks of general interest are also available: the lead-in track (numbered 00) and the lead-out track (numbered AA). Track 00, the lead-in track, contains a table of contents in its subcodes.

A track can have up to 99 subdivisions containing audio information. These subdivisions use the index numbers 01 through 99. Index number 00 is used for the pause between the tracks. The time code gives the current minute, second, and CD frame for the current track. The subcodeQ structure with mode1 uses a cdtimecode structure to contain time codes.

Accessing information from a CD-ROM drive is analogous to accessing information from a standard disk drive. To read a particular piece of information from the CD, you must move to that location. The process of moving to a location on the CD is known as seeking.

Reading from a CD-ROM drive is analogous to reading from a disk drive—you copy information from the device to a memory-resident buffer for further processing.

Playing the CD is a variation on reading it. But instead of transferring the information to a buffer for processing, the information is dumped out the audio jacks on the back of the CD-ROM drive, with a minimum of buffering and with no real chance to process it. For information on processing audio from a CD through the workstation's audio hardware, see “Reading Audio Data from the CD-ROM Drive”.

The parser lets your application change state in response to changes in the subcode data on a CD. This lets you deal with the audio data in a way that is based on its content. To use the parser, you must give it callback routines that can deal the subcode changes that interest you. Then you set up a loop that reads CD frames from the CD and calls the parser for each CD frame.

The parser checks the subcode in every submitted CD frame. If the parts of the subcode you care about have changed from the previous CD frame, the parser executes one of your callbacks and hands it the new subcode information. Within your callback, you can examine the subcode information and change the state of your application as needed.

The CD-ROM device does not use a standard IRIX device driver. So, a session with the CD-ROM device starts by calling CDclose(). For detailed information on these routines, see the man pages CDopen(3) and CDclose(3).

To give your application control over the caddy-eject feature on the CD-ROM drive, libcdaudio defines the following routines:

For more information on these routines, see the appropriate man pages.

If your application wants to give end users the option of seeking to a CD location defined in terms of time, your application can prompt the user for the time and then call CDatomsf() to convert the ASCII string to a <minute, second, CD frame> triple that you can use for seeking. You can also let the user specify a track number, convert that track number to an integer and seek to that track.

Generally, the pure CD frame count is the most convenient format to use when comparing two locations.

To convert to pure CD frame counts, call:

You can then make your calculations and determine the destination to which you want to seek. Despite the convenience of pure CD frame counts for calculation, they are not suitable for seeking. To seek, you must call CDframetomsf() to convert the pure CD frame count to a <minute, second, CD frame> triple.

It is also possible to make comparisons between locations expressed in terms of minutes, seconds, and CD frames. In that case, you can convert locations into <minute, second, CD frame> triples by calling:

After making these calculations, the location is in terms suitable for seeking.

To get your current location within a CD, call CDgetstatus(). This routine takes a CDSTATUS structure and fills it with information on current track, minute, second, CD frame, and additional data. To make it easier to compare your current location to another location, you should express the locations in terms of pure CD frame counts. But depending on how you got a location, it could be expressed as three separate integers giving the minute, second, and CD frame, or as an ASCII string, or as a cdtimecode structure. For more information on this routine, see the appropriate man pages.

Seeking sets up the read pointer to retrieve data from a particular location on the CD. You can define the seek location in terms of:

To do a series of consecutive seeks, your first seek can be defined in any of the formats mentioned above. But, because all seek routines return the logical block number of the next logical block, it is often more convenient to define the subsequent seeks in terms of logical blocks.

If you want to do all seeks using CDseekblock(), but your first seek is defined in terms of time, call CDmsftoblock() to convert time to logical block number.

---

Note: Although logical blocks and CD frames are the same size, you cannot use CD frame counts as if they were logical block counts. The CD frame counts are relative to the start of the CD. A logical block count is offset from the start of the CD. In addition, the size of the offset varies from device to device.

---

This section explains how to use these libcdaudio routines to play audio from the CD-ROM as if it were a standard CD player:

When these routines play a CD, they direct the sound to the drive's headphones and to the audio jacks.

Once you have set the read pointer with a call to one of the seek routines, you are ready to read data from the CD. But how much data should you read at a time in order to create a continuous flow of data from the CD? To determine this, call CDbestreadsize(). The returned value of this function is the number of CD frames to request in your read call. To actually read data from the CD, call CDreadda().

Because libcdaudio already includes routines for playing audio data from the CD, you might think that you would never need to read from the CD; however, the libcdaudio play routines allow for only a very simple CD-player application—one that cannot even display the current program time while the CD is playing.

Thus, if you are writing a real-world application, you probably want to read samples from the CD into the workstation's memory through the CD-ROM's SCSI interface, play the audio samples from the audio hardware using the Audio Library, parse the CD frames for the current program time, and display the program time in a continuously updated field of the control panel for your application.

To do this, you can write your own play routine that executes as a cd_audio callback. You should also write a cd_ptime callback to get the current program time and to update your “program time” display.

After you have read data from the CD into a buffer, you can start to process it. Typically, how you process the audio data depends on what its associated subcodes tell you about the data. To make it possible for your application to avoid dealing with the complex CDFRAME structure directly, libcdaudio includes a parser.

If you write a loop that passes all read CD frames through the parser, the parser can examine all CD frames for changes in the subcode. When the parser finds a change (seeing a subcode for the first time counts as a change), it executes the appropriate callback routine—depending on what sort of subcode change occurred—and passes the new subcode data into your callback routine.

The CD parser distinguishes among eight categories of subcode information. Thus, if you are interested in subcode changes for only one category of subcode data, the parser does not bother your application with subcode changes that you consider irrelevant.

MyCDSomethingCallBack( void* arg, CDDATATYPES type,
void* data) {
/* your code here */
}

In addition to playing a CD or processing the information read from a CD, your application probably needs to tell the user something about the CD (even if it is only the number of the current track). Also, sometimes your application must take data from the end user and convert it to a form that the CD-ROM device can understand.

To get information for the end user, call:

The CD frames, however, sometimes contain information that is not accessible to the routines mentioned above. For example, the subcodes of track 00 on a CD contain a table of contents. To access this information, you can inspect the subcodes in the CDFRAME structures, or, better still, you can submit that track to the parser. If you have added callbacks for the categories of subcode information that you want, the parser passes that information into your callbacks.

To help you present the information the parser hands to your callbacks (or that you read directly from a CDFRAME structure), libcdaudio contains the routines:

For more information on the CDFRAME structure and the format of its data, set the CDFRAME(4) man page.

Other libcdaudio routines that you might find useful are: