FillMusicBuffer(id, type$, samples[, table])

Hollywood's sound server decides when it needs more audio data and thus the sound server is also the one that decides when you have to call FillMusicBuffer(). Hollywood will notify you when it needs more audio data by raising a FillMusicBuffer event so that the callback function you provided using the InstallEventHandler() function will get called. Inside this callback function you will now have to call FillMusicBuffer() to feed new data to the sound server. It is not allowed to call FillMusicBuffer() at other times! You must only call it inside of a callback function of type FillMusicBuffer.

This function takes four arguments: The first one specifies the music object to use. Your callback will receive this information in the ID tag of the event message. The third argument specifies how many samples (in PCM frames) you are providing to the audio server. This must be set to exactly the same number of frames that are requested from you by the callback handler. You get the number of frames requested from you in the Samples tag of the event message. The table argument is optional and must only be used for certain types (see below). The type$ argument specifies how you will provide the new PCM data to the audio server. This can be one of the following strings:

‘PCM’

You will provide the new PCM data directly. In this case, you have to put an array that contains the new PCM frames into the Data tag of the optional table argument (see below).

‘Sample’

You will provide the new PCM data in the form of a sample. In this case, you have to put the identifier of the sample in the ID tag of the optional table argument (see below). Furthermore, you can use the Start, End, Offset, and Loop tags to fine-tune the method that the audio server should use to fetch new PCM data. See below for more information.

‘Mute’

If you specify this type, the audio server will mute audio output for the duration of the number of PCM frames requested. If you pass Mute in the Type tag, you do not have to specify anything else.

‘End’

Specify this type if you want playback of your music to stop. Once the audio server receives an End packet, it will wait until all queued packets have been played and will stop the playback of your music thereafter.

The tags in the optional table argument depend on the type specified in type$. The following tags are recognized:

Data:

If type$ is set to PCM, you need to return an array of PCM data in this tag. The array should contain as many frames as requested by the audio server in the Samples tag. The PCM data must be passed as signed integers. For 8-bit data the valid sample range runs from -128 to 127, and for 16-bit data the valid sample range runs from -32768 to 32767. If you are using stereo mode, you must pass interleaved PCM data, i.e. left channel sample is followed by right channel sample is followed by left channel sample, and so on.

ID:

If type$ is set to Sample, you need to return the identifier of a sample from which the audio server should fetch the PCM data in this tag. You can fine-tune the way the audio server fetches the PCM data from this sample using the Start, End, Offset, and Loop tags. See below for more information.

Start, End:

If type$ is set to Sample, these two tags allow you to specify the range in the source sample that the audio server should use for fetching samples. This is useful if you want the audio server to fetch data from only a part of the sample. Both values have to be specified in PCM frames. These tags default to 0 for Start and length of the specified sample for End. This means that by default the whole sample will be used for fetching PCM data.

Offset:

Specifies an offset into the sample at which the audio server should start fetching PCM data. This offset must be specified in PCM frames and is relative to the position specified in Start. For instance, if you pass 10000 in Start and 100 in Offset, then the audio server will start fetching PCM data from offset 10100. This tag defaults to 0 which means start fetching PCM data from the beginning of the sample.

Loop:

Specifies whether or not the audio server should continue fetching PCM data at the beginning of the source sample once its end has been reached. This defaults to True which means that the audio server will automatically revert to the beginning of the sample if its end has been reached and more PCM data is required. The beginning of the sample is defined by the value specified in the Start tag.

Please note that you have to use FlushMusicBuffer() if you need to update the audio data with a very low latency. FillMusicBuffer() will always buffer about 1 second of music data. This means that it will take about 1 second from the call to FillMusicBuffer() until you can actually hear the audio data that you've just sent. If you need to update the audio data in real-time, e.g. when seeking to a new position in the stream, you will have to flush the music buffer first. See FlushMusicBuffer for details.

id

identifier of the music object to use

type$

desired way for providing new audio data to the device (see above)

samples

number of samples that you are providing in PCM frames; must be identical to the number of samples requested by the FillMusicBuffer event

table

optional: table containing further options (see above)