CD Audio Actions Plugin Help

Add full CD music control to your projects using the CD Audio actions plugin. The CDAudio plugin is perfect for working with "mixed-mode" CDs, where there are one or more audio tracks in addition to a data track. Mixed-mode CDs are often used to create an "enhanced" audio CD which plays normally in a regular CD player and presents additional multimedia content when placed in a computer's CD-ROM drive.

This plugin comes with a full set of actions to give you extensive control over the CD, such as play, pause, stop and seek. There are also actions to query the CD contents, get track length information, set the playback volume and choose play modes such as single, loop and random.

Add the CDAudio plugin to your toolbox, and you can create hybrid audio/data CD's faster and easier than ever before!

Mixed-Mode CD's

The CDAudio plugin is perfect for working with "mixed-mode" CDs, where there are one or more audio tracks in addition to a data track. Mixed-mode CDs are often used to create an "enhanced" audio CD which plays normally in a regular CD player and presents additional multimedia content when placed in a computer's CD-ROM drive.

Data in Track 1

Description:

This form of mixed mode CD places the data track as the first music track on the disk.

Pros:

The CD is recorded as a Mode 1 ROM, therefore it can be played on virtually every CD ROM drive produced.

Cons:

Some CD players will attempt to play the data track. Most new players will skip over the track because it is listed as "data" in the CD's table of contents, but some players will attempt to play the data track as audio, resulting in a very loud noise (like the screech of a fax machine).
This method is typically only used in situations where it is unlikely that the CD will be played in a CD audio player.

Pre-Gap / Track-Zero

Description:

This form of a mixed mode CD hides the data track in the pause before track 1 begins.

Pros:

Older CD players do not typically attempt to play the data track.

Cons:

If the user rewinds the CD into the data track, the data can be played back as audio, resulting in a very loud disconcerting noise.
This type of CD does not conform to the official standard and may not be compatible with some players or operating system software.

CD Extra or Enhanced CD

Description:

This form of a mixed mode CD contains two sessions (a multi-session disk). The first session contains up to 98 audio tracks, and the second session contains the data track. Audio CD players can only 'see' the first session, and thus will not play the data track. Most CD-ROM drives can see both sessions, and will load your AutoPlay application.

Pros:

Even older CD players won't play the data track, so the user's ears and speakers are safe from damage.
This format is the most compatible with both stand-alone CD players and CD-ROM drives.

Cons:

Enhanced CDs are not playable on Photo CD players.
Requires a CD-ROM drive that is able to read multi-session discs.

Conclusion

Our Suggestion:

We suggest that you use the 'Enhanced CD' type, due to its wider scope of compatibility. Virtually any CD-ROM created for Windows 95 or greater supports this format.

The data files will be recognized in Windows Explorer as though there are no audio tracks, because Windows Explorer typically can only see the last session in a multi-session disk. Audio players, on the other hand, typically see only the first session in a multi-session disk. Therefore, both CD-ROMS and stand-alone audio players are able to play the audio tracks.

Burning an Enhanced CD (CD Extra) with Nero:

To burn an Enhanced CD with Nero Burning ROM (6.0 or greater):

Select "CD Extra" and input desired settings.
Add your audio tracks by dragging your audio files to the track window.
Add your data files by dragging them to the folder structure window.

Actions

CDAudio.GetCurrentPos
CDAudio.GetNumTracks
CDAudio.GetPlayMode
CDAudio.GetTrack
CDAudio.GetTrackLength
CDAudio.GetVolume
CDAudio.IsPaused
CDAudio.LoadCD
CDAudio.Pause
CDAudio.Play
CDAudio.Seek
CDAudio.SetPlayMode
CDAudio.SetTrack
CDAudio.SetVolume
CDAudio.Stop
CDAudio.TogglePlay

number CDAudio.GetCurrentPos ();

Description:

Retrieves the current time position (in seconds) of the current audio CD track.

Returns:

(number) The current position of the audio CD track, in seconds. If an error occurs, -1 will be returned. You can use Application.GetLastError to determine whether this action failed, and why.

Example:

-- Get the position of the current audio track in seconds
nPos = CDAudio.GetCurrentPos();

number CDAudio.GetNumTracks (string Drive);

Description:

Determines how many tracks are on an audio CD.

Drive:

The drive that the audio CD is loaded in (e.g. "D:\\", "D", "D:").

Returns:

(number) The number of tracks on the audio CD. If an error occurs, 0 will be returned. You can use Application.GetLastError to determine whether this action failed, and why.

Example:

-- Get the number of tracks on drive D:
nTracks = CDAudio.GetNumTracks("D");

number CDAudio.GetPlayMode ();

Description:

Retrieves the current play mode of the audio CD.

Returns:

(number) The current play mode:

0 (CDAudio.PLAYCONTINUOUS) - Start from the current track and play to end of CD.
1 (CDAudio.PLAYONCE) - Play the current track, then stop.
2 (CDAudio.PLAYLOOPED) - Play the current track, looping forever until stopped manually.
3 (CDAudio.PLAYRANDOM) - Play tracks in random order.

Example:

-- Get the current play mode on the source drive
nPlayMode = CDAudio.GetNumTracks(_SourceDrive);

number CDAudio.GetTrack ();

Description:

Retrieves the current track on the currently loaded audio CD.

Returns:

(number) The current track. If an error occurs, 0 will be returned. You can use Application.GetLastError to determine whether this action failed, and why.

Example:

-- Get the current track
nCurrentTrack = CDAudio.GetTrack();

number CDAudio.GetTrackLength (number Track);

Description:

Retrieves the length of the specified track on the currently loaded audio CD.

Returns:

(number) The length of the track in seconds. If an error occurs, 0 will be returned. You can use Application.GetLastError to determine whether this action failed, and why.

Example:

-- Get the length of track 4
nTrackLength = CDAudio.GetTrackLength(4);

number CDAudio.GetVolume ();

Description:

Retrieves the current volume of the audio CD, as a number between 0 and 255.

Returns:

(number) The volume of the currently loaded audio CD. If an error occurs, -1 will be returned. You can use Application.GetLastError to determine whether this action failed, and why.

Example:

-- Get the current volume
nVolume = CDAudio.GetVolume();

number CDAudio.IsPaused ();

Description:

Determines whether the audio CD is currently paused.

Returns:

(boolean) True if the audio CD is paused, or false if it is playing or stopped. You can use Application.GetLastError to determine whether this action failed, and why.

Example:

-- Display a message if the CD is paused
if CDAudio.IsPaused() then
    Dialog.Message("", "The CD is paused.");
end

CDAudio.LoadCD (string Drive);

Description:

"Loads" an audio CD so that it can be played, paused, etc. Use this action to select a CD-ROM drive for future CDAudio operations.

Tip: Set the playmode to CDAudio.PLAYRANDOM before calling CDAudio.LoadCD() to have the "first track" chosen at random. Otherwise, the current track will default to track 1.

Drive:

(string) The drive that the audio CD is loaded in (e.g. "D:\\", "D", "D:"). Leave blank ("") to specify the user's default CD-ROM drive.

Returns:

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.

Example:

-- Select the "D:" drive and play track 3
CDAudio.LoadCD("D");
CDAudio.SetTrack(3);
CDAudio.Play();

CDAudio.Pause ();

Description:

Paused the audio CD.

Returns:

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.

Example:

-- Pause the CD
CDAudio.Pause();

CDAudio.Play ();

Description:

Plays the current track on the audio CD.

Note: This resumes playback if the audio CD is paused...otherwise, it begins playing the track from the beginning.

Tip: Before calling CDAudio.Play() for the first time, you need to use CDAudio.LoadCD() to select a CD-ROM drive for playback.

Returns:

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.

Example 1:

-- Start playing (or resume playing) the current track on the currently loaded Audio CD
CDAudio.Play();

Example 2:

-- Play track 5 on the "E:" drive
CDAudio.LoadCD("E");
CDAudio.SetTrack(5);
CDAudio.Play();

CDAudio.Seek (number SeekType, number SeekTime);

Description:

Seeks to a different time in the current track of the audio CD.

SeekType:

(number) The type of seek to perform:

SEEK_BEGINNING (0) - Seek to the beginning of the current track.
SEEK_END (1) - Seek to the end of the current track.
SEEK_FORWARD (2) - Seek forward.
SEEK_BACKWARD (3) - Seek backward.
SEEK_SPECIFIC (4) - Seek to a specific time within the track.

SeekTime:

(number) The time in seconds to seek to (or seek by).

Note: SeekTime is only used if SeekType is 2, 3 or 4.

Returns:

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.

Example:

-- Seek ahead 5 seconds
CDAudio.Seek(SEEK_FORWARD, 5);

CDAudio.SetPlayMode (number PlayMode);

Description:

Sets the play mode for the audio CD.

PlayMode:

(number) The play mode to set:

CDAudio.PLAYCONTINUOUS (0) - Start from the current track and play to end of CD.
CDAudio.PLAYONCE (1) - Play the current track, then stop.
CDAudio.PLAYLOOPED (2) - Play the current track, looping forever until stopped manually.
CDAudio.PLAYRANDOM (3) - Play tracks in random order.

Returns:

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.

Example:

-- Start playing the tracks on drive E: in random order
CDAudio.LoadCD("E");
CDAudio.SetPlayMode(CDAudio.PLAYRANDOM);
CDAudio.Play();

CDAudio.SetTrack (number Track);

Description:

Sets the current track on the currently loaded audio CD.

Note: If the audio CD is currently playing, this starts playing the new track automatically.

Track:

(number) The CD track to switch to. The first track starts at 1.

Returns:

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.

Example:

-- Switch to track # 8
CDAudio.SetTrack(8);

CDAudio.SetVolume (number Volume);

Description:

Sets the volume of the audio CD.

Volume:

(number) The volume as a number between 0 and 255, where 0 is quietest and 255 is loudest.

Returns:

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.

Example:

-- Get the current volume
nVolume = CDAudio.GetVolume();

CDAudio.Stop ();

Description:

Stops playing the current track on the audio CD.

Returns:

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.

Example:

-- Stop playing the current track
CDAudio.Stop();

CDAudio.TogglePlay ();

Description:

Toggles the audio CD between playing and pausing.

Tip: Use this to create a button that toggles playback on and off, pausing when playing, and resuming when paused.

Returns:

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.

Example:

-- Play the current track if it's paused, or pause it if it's playing
CDAudio.TogglePlay();

0	(CDAudio.OK)	-	(no error)
32000	(CDAudio.ERR_UNABLE_TO_INIT)	-	Unable to initialize sound system.
32001	(CDAudio.ERR_NOT_INITIALIZED)	-	Sound system not initialized.
32002	(CDAudio.ERR_NOT_CD_DRIVE)	-	The specified drive is not an audio CD drive.
32003	(CDAudio.ERR_NO_CD_IN_DRIVE)	-	The specified drive does not contain an audio CD. The drive is empty.
32004	(CDAudio.ERR_TRACK_TOO_LOW)	-	The specified track is out of range. Track numbers begin at 1.
32005	(CDAudio.ERR_TRACK_TOO_HIGH)	-	The specified track is out of range for the current audio CD.
32006	(CDAudio.ERR_UNABLE_TO_PLAY)	-	An error occurred while trying to play the audio CD.
32007	(CDAudio.ERR_UNABLE_TO_PAUSE)	-	An error occurred while trying to pause the audio CD.
32008	(CDAudio.ERR_UNABLE_TO_STOP)	-	An error occurred while trying to stop the audio CD.
32009	(CDAudio.ERR_INVALID_PLAYMODE)	-	Invalid PlayMode value.
32010	(CDAudio.ERR_UNABLE_TO_GET_TRACK)	-	An error occurred while trying to determine the current track.
32011	(CDAudio.ERR_UNABLE_TO_SET_TRACK)	-	An error occurred while trying to change the track.
32012	(CDAudio.ERR_VOLUME_OUT_OF_RANGE)	-	The specified volume is out of range.
32013	(CDAudio.ERR_UNABLE_TO_GET_VOLUME)	-	An error occurred while trying to get the audio CD volume.
32014	(CDAudio.ERR_UNABLE_TO_SET_VOLUME)	-	An error occurred while trying to set the audio CD volume.
32015	(CDAudio.ERR_UNABLE_TO_GET_CURRENT_POSITION)	-	An error occurred while trying to get the current audio CD track position.
32016	(CDAudio.ERR_UNABLE_TO_SEEK)	-	An error occurred while trying to perform a seek on the current audio CD track.
32017	(CDAudio.ERR_SEEK_TIME_OUT_OF_RANGE)	-	The specified seek time is out of range for the current audio CD track.
32018	(CDAudio.ERR_UNABLE_TO_GET_TRACK_LENGTH)	-	An error occurred while trying to get the length of an audio CD track.

CD Audio Actions Plugin

Description

Mixed-Mode CD's

Data in Track 1

Description:

Pros:

Cons:

Pre-Gap / Track-Zero

Description:

Pros:

Cons:

CD Extra or Enhanced CD

Description:

Pros:

Cons:

Conclusion

Our Suggestion:

Burning an Enhanced CD (CD Extra) with Nero:

Actions

Description:

Returns:

Example:

Description:

Drive:

Returns:

Example:

Description:

Returns:

Example:

Description:

Returns:

Example:

Description:

Returns:

Example:

Description:

Returns:

Example:

Description:

Returns:

Example:

Description:

Drive:

Returns:

Example:

Description:

Returns:

Example:

Description:

Returns:

Example 1:

Example 2:

Description:

SeekType:

SeekTime:

Returns:

Example:

Description:

PlayMode:

Returns:

Example:

Description:

Track:

Returns:

Example:

Description:

Volume:

Returns:

Example:

Description:

Returns:

Example:

Description:

Returns:

Example:

Error Codes

Change Log

2.0.0.0

1.0.2.0

1.0.1.0