TABLE OF CONTENTS cdda.library/--background-- cdda.library/CDDA_FindNextDrive cdda.library/CDDA_NumDrives cdda.library/CDDA_MSFToFrames cdda.library/CDDA_FramesToMSF cdda.library/CDDA_ObtainDrive cdda.library/CDDA_ReleaseDrive cdda.library/CDDA_GetAttr cdda.library/CDDA_GetTrackInfo cdda.library/CDDA_Play cdda.library/CDDA_Pause cdda.library/CDDA_Resume cdda.library/CDDA_Stop cdda.library/CDDA_Search cdda.library/CDDA_LoadTray cdda.library/CDDA_EjectTray cdda.library/--background-- cdda.library/--background-- PURPOSE The purpose of cdda.library is to provide a library for high level cd audio playback. Major design criteria are: - EASY FOR THE DEVELOPER: Allow developers to play back cd audio with as little fuss as possible. For example, cdda.library handles all device-level stuff for you. - EASY FOR THE USER: cdda.library recognizes all mounted SCSI-II CD-ROM drives automatically. No need to know which drive is assigned to which unit on which device. Furthermore, cdda.library acts as some sort of "resource manager". It knows which program uses which drive and manages playback. For example, it will disallow actions that would interrupt another program's playback. Note that play can still be easily interrupted, e.g. reading data from the CD has higher priority on some drives than the audio. LIBRARY OPENING Please do *always* open the library with version at least CDDA_VMIN, or CDDA_VCURRENT. Version 1 was an alpha distributed with a ScummVM CVS snapshot. It is outdated and broken. TRACK ADDRESSING Please remember that as an CD audio library, cdda.library does not bother with data tracks. All track indices you give to cdda.library should treat data tracks as non-existant. Thus, the first audio track is always track 1, the second audio track is track 2, even if they are preceeded by some data tracks. The exception is the contents of the track info structure. Here, the track returned is always the "true" track number. CDID INFORMATION cdda.library is capable of providing you with CDID information where available. Names of disc title and artist can be obtained through CDDA_GetAttr(), track titles can be found in the CDS_TrackInfo structure that is filled by CDDA_GetTrackInfo(). If no information is available, the pointers will be NULL. The pointers remain valid until you query CDID information attributes with CDDA_GetAttr() or call CDDA_GetTrackInfo() the next time on a different disc. If you want to be on the safe side, copy them into a local buffer. The memory area at the pointers is strictly read only. cdda.library/CDDA_FindNextDrive cdda.library/CDDA_FindNextDrive NAME CDDA_FindNextDrive -- Find next drive matching certain criteria. CDDA_FindNextDriveTags -- Varargs stub for CDDA_FindNextDrive. SYNOPSIS result = CDDA_FindNextDrive( CDrive, TagItems ) D0 A0 A1 CDRIVEPTR CDDA_FindNextDrive( CDRIVEPTR, struct TagItem * ); result = CDDA_FindNextDriveTags( CDrive, Tag1, ... ) CDRIVEPTR CDDA_FindNextDriveTags( CDRIVEPTR CDrive, Tag Tag1, ... ); FUNCTION Find the next drive in cdda.library's CD-ROM drive list which matches all of the criteria specified in the taglist. INPUTS CDrive - drive in list after which to start the search. NULL to start searching from the beginning of the list. TagItems - pointer to an optional tag list which may be used to specify criteria that the drive must match. If omitted, the next drive is returned. TAGS Tags available are: CDFA_Device (STRPTR) - Name of the device on which the drive must be mounted. CDFA_Unit (ULONG) - Unit number of the drive on the controller. CDFA_Vendor (STRPTR) - Match only drives manufactured by the given vendor. For a list of vendor names, see the SCSI-II specification. CDFA_VolumeName (STRPTR) - A CD with the given volume name must be inserted in the drive. CDFA_CDID (STRPTR) - Matches the drive which contains a disc that is described by the given standard CDID string. This tag enables you to find audio-only discs which have no volume name. RESULT result - NULL if no further drive matches, otherwise a the next suitable CDRIVEPTR. You can pass this result to the next call to CDDA_FindNextDrive() to see if more drives match your criteria. BUGS At the moment, cdda.library recognizes only drives that were mounted when the library was loaded into memory. To find all currently mounted CD drives, the library must be flushed from memory. cdda.library/CDDA_NumDrives cdda.library/CDDA_NumDrives NAME CDDA_NumDrives -- return the number of mounted CD-ROM drives SYNOPSIS num = CDDA_NumDrives() D0 ULONG CDDA_NumDrives(); FUNCTION Returns the number of CD-ROM drives cdda.library found in the system. RESULT num - number of drives in the system. cdda.library/CDDA_MSFToFrames cdda.library/CDDA_MSFToFrames NAME CDDA_MSFToFrames -- Convert a MSF value into frames SYNOPSIS frames = CDDA_MSFToFrames( Minutes, Seconds, Frames ) D0 D0 D1 D2 ULONG CDDA_MSFToFrames( ULONG, ULONG, ULONG ); FUNCTION Convert a time value given in minute-second-frames format to frames. INPUTS Minutes - Minute part of the time value to be converted Seconds - Second part of the time value to be converted Frames - Frame part of the time value to be converted RESULT frames - converted frames value. NOTES There is no need to normalize the values, i.e. it is allowed to specify 80 seconds instead of 1 minute and 20 seconds. SEE ALSO CDDA_FramesToMSF() cdda.library/CDDA_FramesToMSF cdda.library/CDDA_FramesToMSF NAME CDDA_FramesToMSF -- Convert frames to MSF value. SYNOPSIS CDDA_FramesToMSF( Frames, MSF ) D0 A0 void CDDA_FramesToMSF( ULONG, struct CDS_Time * ); FUNCTION Convert a time value given in frames format to minute-second- frames. INPUTS Frames - Frames value to be converted. MSF - pointer to a structure receiving the converted MSF value. SEE ALSO CDDA_MSFToFrames() cdda.library/CDDA_ObtainDrive cdda.library/CDDA_ObtainDrive NAME CDDA_ObtainDrive -- Do the given hook for the supplied rastport CDDA_ObtainDriveTags -- Varargs stub for CDDA_ObtainDrive SYNOPSIS success = CDDA_ObtainDrive( CDrive, Access, TagItems ) D0 A0 D0 A1 BOOL CDDA_ObtainDrive( CDRIVEPTR, ULONG, struct TagItem * ) CDDA_ObtainDriveTags( CDrive, Access, Tag1, ... ) BOOL CDDA_ObtainDriveTags( CDRIVEPTR, ULONG, Tag1, ... ) FUNCTION In order to play CD audio (and query some attributes), you must call this function to obtain access to the drive. When you're done playing, the drive must be released with a call to CDDA_ReleaseDrive(). INPUTS CDrive - Drive handle to obtain. You can get a handle through CDDA_FindNextDrive() Access - Access mode, must be CDDA_SHARED_ACCESS for now. TagItems - pointer to an optional taglist. TAGS No tags are currently defined. RESULT success - TRUE if the drive could be obtained, FALSE otherwise. NOTES When you obtain a drive, the access permission is attached to your process. Accessing the drive from a subtask is not possible. SEE ALSO CDDA_FindNextDrive(), CDDA_ReleaseDrive() cdda.library/CDDA_ReleaseDrive cdda.library/CDDA_ReleaseDrive NAME CDDA_ReleaseDrive -- Releases a drive obtained with CDDA_ObtainDrive() SYNOPSIS CDDA_ReleaseDrive( CDrive ); A0 void CDDA_ReleaseDrive( CDRIVEPTR ); FUNCTION Releases a previously obtained drive. INPUTS CDrive - The drive to be released. SEE ALSO CDDA_ObtainDrive() cdda.library/CDDA_GetAttr cdda.library/CDDA_GetAttr NAME CDDA_GetAttr -- Returns information about a drive or disk in the drive SYNOPSIS success = CDDA_GetAttr( AttrID, CDrive, Result ); D0 D0 A0 A1 BOOL CDDA_GetAttr( ULONG, CDRIVEPTR, ULONG * ); FUNCTION Gets information about a drive, or the disk currently inserted into the drive. INPUTS AttrID - Attribute which is to be queried: CDDA_Vendor (STRPTR) - Drive vendor. CDDA_Model (STRPTR) - Drive model. CDDA_Revision (STRPTR) - Revision of the drive. CDDA_Device (STRPTR) - Device this drive is mounted on. CDDA_Unit (ULONG) - Unit number of the drive. CDDA_Status (ULONG) - Current status of the drive. Possible states are: CDDA_Status_Unknown - Drive is in unknown state. CDDA_Status_Busy - Drive is currently playing audio. CDDA_Status_Paused - Drive is playing, but in pause mode. CDDA_Status_Ready - Drive is not playing, but ready to play. CDDA_DiscTitle (STRPTR) - If CDID information is available, returns the name of the disc. CDDA_Artist (STRPTR) - If CDID information is available, returns the name of the artist. CDDA_DiscAvail (BOOL) - TRUE if a disc is inserted in the drive, FALSE otherwise. CDDA_TrackCount (ULONG) - Number of tracks on the inserted disc. CDDA_TrackPos (CDS_TrackPosition *) - Fills a CDS_TrackPosition structure with information about the current playing position, including track, absolute and relative time. This is only meaningful while the drive is playing. CDDA_TrackPosMSF (CDS_TrackPosition *) - same as CDDA_TrackPos, except that the time values are filled in minute-second-frames format. CDrive - Drive to be queried. Result - Pointer to a memory area which receives the query result if the query was successful. RESULT success - TRUE if the attribute was received, FALSE otherwise. NOTES Queries for CDDA_TrackPos and CDDA_TrackPosMSF receive their data in a CDS_TrackPosition structure. You must set the tp_StructSize member of the result structure to sizeof (struct CDS_TrackPosition), otherwise the query will fail. CDDA_DiscAvail, CDDA_TrackCount, CDDA_TrackPos and CDDA_TrackPosMSF currently require you to have obtained the drive previously, otherwise the query will fail. cdda.library/CDDA_GetTrackInfo cdda.library/CDDA_GetTrackInfo NAME CDDA_GetTrackInfo -- Returns information on a certain track SYNOPSIS success = CDDA_GetTrackInfo( CDrive, Track, Flags, Result ) D0 A0 D0 D1 A1 BOOL CDDA_GetTrackInfo( CDRIVEPTR, ULONG, ULONG, struct CDS_TrackInfo * ); FUNCTION Returns information on the specified track. INPUTS CDrive - Drive with the disc from which track info is requested. Track - Track number of which info is requested. Flags - Currently, only one flag is defined: CDDA_GTI_MSFTimes - Retrieve times in MSF format (otherwise time is returned in frames). Result - Pointer to a CDS_TrackInfo structure which receives the track information if the function is successful. The ti_StructSize member must be set to sizeof(struct CDS_TrackInfo) before calling, otherwise the call will fail with an IoErr() code of CDDA_Err_WrongParam. RESULT success - TRUE if info was retrieved, FALSE otherwise. In case of failure, call IoErr() to receive the error code. SEE ALSO dos.library/IoErr() cdda.library/CDDA_Play cdda.library/CDDA_Play NAME CDDA_Play -- Plays a section of an audio CD CDDA_PlayTags -- Varargs stub for CDDA_Play SYNOPSIS success = CDDA_Play( TagList ) D0 A0 BOOL CDDA_Play( struct TagItem * ); CDDA_PlayTags( Tag1, ... ) BOOL CDDA_PlayTags( Tag1, ... ) FUNCTION Plays part of an audio CD. INPUTS TagList -- Taglist specifying which part of the CD to play. TAGS Tags available are: CDPA_StartTrack (ULONG) - Specifies the track to start playback with. Default is track 1. CDPA_StartMinute (ULONG) - Specifies the start minute of playback. Default is 0. CDPA_StartSecond (ULONG) - Specifies the start second of playback. Default is 0. CDPA_StartFrame (ULONG) - Specifies the start frame of playback. Default is 0. CDPA_EndTrack (ULONG) - Specifies the track where the playback ends. If CDPA_EndMinute, CDPA_EndSecond and CDPA_EndFrame are not specified, this defaults to the track following the start track so that only the start track is played, otherwise it defaults to the start track. CDPA_EndMinute (ULONG) - Specifies the end minute of playback. Default is 0. CDPA_EndSecond (ULONG) - Specifies the end second of playback. Default is 0. CDPA_EndFrame (ULONG) - Specifies the end frame of playback. Default is 0. CDPA_Loops (LONG) - The number of times the section of the disc should be played. 0 is a valid value but it will result in no audio played. Negative values mean the playing section is repeated endlessly until CDDA_Stop() is called. Default is 1. CDPA_EventHook (struct Hook *) - Installs an event hook which is called on certain events. For possible events, see CDPA_EventMask below. Default is NULL. CDPA_EventMask (ULONG) - Or-ed bitmask of events you would like to receive if an event hook is specified. The hook is called with the event structure in A1 and the CDRIVEPTR of the drive in A2. To see which event caused the hook to be called, check the ce_Code field of the event structure. Currently defined events are (applying event structure in brackets): CDDA_EVENT_TIMEUPDATE (struct CDS_TimeEvent *) - This causes the hook function to be called once a second with the current track position information. The cte_TrackPos field of the CDS_TimeEvent structure passed holds time information in MSF format. CDDA_EVENT_PAUSED (struct CDS_Event *) - The drive has been paused. CDDA_EVENT_RESUMED (struct CDS_Event *) - Playing is resumed after drive had been set into pause mode. CDDA_EVENT_RESTART (struct CDS_Event *) - Called when the playing had finished and is now restarted. This happens when CDPA_Loops is < 0 or > 1. CDDA_EVENT_TRACK (struct CDS_TrackEvent *) - The hook function will be called with the current track number when the track number has changed, i.e. when the drive has crossed a track border on playback. CDDA_EVENT_STOPPED (struct CDS_Event *) - Playback has been stopped prematurely, e.g. when you called CDDA_Stop(), but also when another program accesses the disc in a way that interrupts cdda.library's playback. CDDA_EVENT_FINISHED (struct CDS_Event *) - Playback has finished normally. RESULT success - TRUE if playing was started, FALSE otherwise. In case of failure, call IoErr() to receive the error code. Especially, CDDA_Err_IsBusy means that another program is playing audio at the moment. NOTES All start and end times given are added to calculate the start and ending times. For example, if you give a start track of 3, a start minute of 2 and start second of 30, then playback starts 2:30 minutes into track 3. It is possible that the playback could not be started even though the function returned success. SEE ALSO dos.library/IoErr() cdda.library/CDDA_Pause cdda.library/CDDA_Pause NAME CDDA_Pause -- Put the drive into pause mode. SYNOPSIS success = CDDA_Pause( CDrive ) D0 A0 BOOL CDDA_Pause( CDRIVEPTR ); FUNCTION Puts a drive into pause mode. INPUTS CDrive - Drive to be put into pause mode. RESULT success - TRUE if playing was paused, FALSE otherwise. In case of failure, call IoErr() to receive the error code. NOTES You can only pause playbacks you have initiated with CDDA_Play() yourself, not those of other tasks. BUGS Pause does not work properly when in quick search mode. SEE ALSO CDDA_Resume(), dos.library/IoErr() cdda.library/CDDA_Resume cdda.library/CDDA_Resume NAME CDDA_Resume -- Resume paused playback. SYNOPSIS success = CDDA_Resume( CDrive ) D0 A0 BOOL CDDA_Resume( CDRIVEPTR ); FUNCTION Resumes a playback operation previously paused with CDDA_Pause(). INPUTS CDrive - Drive to be resumed. RESULT success - TRUE if playing was resumed, FALSE otherwise. In case of failure, call IoErr() to receive the error code. NOTES You can only resume playbacks you have paused with CDDA_Pause() yourself. SEE ALSO CDDA_Pause(), dos.library/IoErr() cdda.library/CDDA_Stop cdda.library/CDDA_Stop NAME CDDA_Stop -- Stops playback. SYNOPSIS success = CDDA_Stop( CDrive ) D0 A0 BOOL CDDA_Stop( CDRIVEPTR ); FUNCTION Stops a playback operation previously started with CDDA_Play(). INPUTS CDrive - Drive to be stopped. RESULT success - TRUE if playing was stopped, FALSE otherwise. In case of failure, call IoErr() to receive the error code. NOTES You can only resume playbacks you have paused with CDDA_Pause() yourself. SEE ALSO CDDA_Play(), dos.library/IoErr() cdda.library/CDDA_Search cdda.library/CDDA_Search NAME CDDA_Search -- Start or stop quick search. SYNOPSIS success = CDDA_Search( CDrive, mode ) D0 A0 D0 BOOL CDDA_Search( CDRIVEPTR, ULONG ); FUNCTION Does a quick audio search while still monitoring sound. INPUTS CDrive - Drive to be affected. mode - One of: CDDA_SEARCH_NORMAL - Resumes normal playback. CDDA_SEARCH_FORWARD - Starts quick search forward. CDDA_SEARCH_BACKWARD - Starts quick search backward. RESULT success - TRUE if search is ok, FALSE otherwise. NOTES Quick searching only works while you are playing audio. Quick searching is not unproblematic since all parameters passed to the CDDA_Play() call are still in effect. That includes loops and start/end positions. Try to avoid using user-controlled quick search while looping other than endless or once is in effect since switching between forward to backward search can count as a full loop when the start or end position is being crossed. Also, do not pause the drive while quick searching. Always reset mode to normal first. cdda.library/CDDA_LoadTray cdda.library/CDDA_LoadTray NAME CDDA_LoadTray -- Loads the CD tray. SYNOPSIS success = CDDA_LoadTray( CDrive ) D0 A0 BOOL CDDA_LoadTray( CDRIVEPTR ); FUNCTION Ensures the CD tray is loaded. INPUTS CDrive - Drive of which to load the CD tray. RESULT success - TRUE if successful, FALSE otherwise. In case of failure, call IoErr() to receive the error code. NOTES You must have obtained the drive with CDDA_ObtainDrive() before you can load the tray. SEE ALSO CDDA_EjectTray(), CDDA_ObtainDrive(), dos.library/IoErr() cdda.library/CDDA_EjectTray cdda.library/CDDA_EjectTray NAME CDDA_EjectTray -- Ejects the CD tray. SYNOPSIS success = CDDA_EjectTray( CDrive ) D0 A0 BOOL CDDA_EjectTray( CDRIVEPTR ); FUNCTION Ejects the CD tray. INPUTS CDrive - Drive of which to eject the CD tray. RESULT success - TRUE if successful, FALSE otherwise. In case of failure, call IoErr() to receive the error code. NOTES You must have obtained the drive with CDDA_ObtainDrive() before you can eject the tray. Note that the tray won't be ejected while audio is being played, even if you have initiated the play action yourself. In this case, make sure you call CDDA_Stop() first. SEE ALSO CDDA_LoadTray(), CDDA_ObtainDrive(), CDDA_Stop(), dos.library/IoErr()