FillMusicBuffer(id, type$, samples[, table])
FillMusicBuffer()will send the specified audio data to Hollywood's sound server which will in turn send it to the audio device. This chain of processors makes it possible to play gapless, dynamically generated audio data from your script.
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
Hollywood will notify you when it needs more audio data by raising a
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
FillMusicBuffer() at other times! You must only call it inside of a callback
function of type
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:
Datatag of the optional table argument (see below).
IDtag of the optional table argument (see below). Furthermore, you can use the
Looptags to fine-tune the method that the audio server should use to fetch new PCM data. See below for more information.
Typetag, you do not have to specify anything else.
Endpacket, 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
The following tags are recognized:
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
Samplestag. 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.
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
Looptags. See below for more information.
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
Startand length of the specified sample for
End. This means that by default the whole sample will be used for fetching PCM data.
Start. For instance, if you pass 10000 in
Startand 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.
Truewhich 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
Please note that you have to use FlushMusicBuffer()
if you need to update the audio data with a very low latency.
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.