Name
CreateMusic -- create dynamic music stream (V5.0)
Synopsis
[id] = CreateMusic(id, pitch, fmt)
Function
This function can be used to create a dynamic music stream that has to be fed constantly with new PCM data through a user defined callback function. This allows you to play gapless audio using PCM data generated on the fly by a callback function. The music object will be added to Hollywood's music list and can be accessed through the specified id. If you pass Nil in id, CreateMusic() will automatically select a vacant identifier and return it to you. You also have to specify the desired playback frequency for the music in the pitch argument as well as the encoding of the PCM data in the fmt argument. Currently, the following formats are supported: #MONO8, #STEREO8, #MONO16, and #STEREO16.

Before you call this function, you have to install a callback function of type FillMusicBuffer using the InstallEventHandler() function. This callback will then be called whenever the audio server needs new PCM data. To deliver the new PCM data to the audio server, your callback has to call the FillMusicBuffer() function. See FillMusicBuffer for details.

Once you have created the music object using CreateMusic(), you can then use all the regular commands from the music library to work with the new music. For instance, you can use PlayMusic() to start playback and PauseMusic() to pause the music object.

Make sure that you always use a main loop that calls WaitEvent() when you use this function because the callback function of CreateMusic() will always be called by WaitEvent()! If you do not use a WaitEvent() loop, your callback will never get called and thus no sound will ever play!

Please note that this is a lowlevel function that runs pretty close on the hardware level. Thus, your callback function should never block your script for a longer time. It should return as soon as possible. Never call any functions that could block the script in CreateMusic() callback functions. For instance, calling Wait() or SystemRequest() in a music callback is a very bad idea.

Inputs
id
identifier for the new music or Nil for auto selection
pitch
desired playback frequency for the music object
fmt
desired format for the music object
Results
id
optional: identifier of new music object; this is only used if Nil is passed in the first argument

Show TOC