Name
BeginMusicStream -- create sound stream (V11.0)
Synopsis
[id] = BeginMusicStream(id, file$, freq, infmt[, outfmt, table])
Library
sound

Function
This function allows you to create an sound stream object on disk that you can then subsequently append sound data to it using WriteMusicStream(). The advantage of BeginMusicStream() over SaveMusic() is that SaveMusic() requires you to provide an existing music object as the source, whereas BeginMusicStream() allows you to append sound data to your stream from individual sample object source, which gives you the utmost flexibility. Because of its sequential design, BeginMusicStream() can be used to create new sound streams of virtually unlimited size and length. You could easily create a 2 hour sound stream with this function.

The first argument to BeginMusicStream() must be an id for the new sound stream object. Alternatively, you can specify Nil and BeginMusicStream() will return a handle to the object to you. The second argument specifies a path to a file that shall be created for this sound stream. The freq argument must be set to the desired playback frequency in Hertz, e.g. 44100 for CD quality. The infmt parameter specifies the format of the samples you're going to write to the sound stream, i.e. their bit depth and number of channels. Currently, the following formats are supported for infmt: #MONO8, #STEREO8, #MONO16, and #STEREO16.

The optional argument outfmt specifies the desired format for the sound stream file that will be created by BeginMusicStream(). By default, Hollywood supports the following two output formats:

#SNDFMT_WAVE:
Use the RIFF WAVE format. This is the default.

#SNDFMT_SVX:
Use the IFF 8SVX (8-bit) or IFF 16SV (16-bit) format.

Additional output formats can be made available by plugins.

The optional table argument table supports the following additional tags:

Bitrate:
If the file format specified in the outfmt argument supports audio compression using a specific bitrate, this tag can be used to specify that bitrate. For the #SNDFMT_WAVE and #SNDFMT_SVX formats this tag doesn't have any effect.

Quality:
If the file format specified in the outfmt argument supports audio compression using a specific quality setting, this tag can be used to specify that quality. For the #SNDFMT_WAVE and #SNDFMT_SVX formats this tag doesn't have any effect.

Adapter:
This tag allows you to specify one or more file adapters that should be asked if they want to save the specified file. If you use this tag, you must set it to a string containing the name(s) of one or more adapter(s). Defaults to the adapter set using SetDefaultAdapter(). See Loaders and adapters for details.

UserTags:
This tag can be used to specify additional data that should be passed to loaders and adapters. If you use this tag, you must set it to a table of key-value pairs that contain the additional data that should be passed to plugins. See User tags for details.

Once you have successfully created a new sound stream object using BeginMusicStream(), you can then sequentially append sound data to it using WriteMusicStream(). When you are done adding sound data, you have to call FinishMusicStream to finalize the sound file on disk and make it ready for use.

Inputs
id
id for the sound stream object or Nil for auto id selection
file$
destination file
freq
desired playback frequency in Hertz for the sound stream (must be one of #MONO8, #STEREO8, #MONO16, or #STEREO16)
infmt
format of the samples you're going to add to this sound stream
outfmt
optional: output audio format to use (defaults to #SNDFMT_WAVE)
table
optional: further arguments for save operation (see above)
Results
id
optional: identifier of the sound stream; will only be returned when you pass Nil as argument 1 (see above)
Example
OpenMusic(1, "test.mod", {TimedProtracker = True})
type = GetAttribute(#MUSIC, 1, #ATTRTYPE)
numsmp = GetAttribute(#MUSIC, 1, #ATTRNUMFRAMES)
freq = GetAttribute(#MUSIC, 1, #ATTRPITCH)
BeginMusicStream(1, "out.wav", freq, type)
While numsmp > 0
   GetMusicSample(1, 1, Min(numsmp, freq), {Hardware = False})
   WriteMusicStream(1, 1)
   numsmp = numsmp - GetAttribute(#SAMPLE, 1, #ATTRNUMFRAMES)
Wend
FinishMusicStream(1)
The code above shows how to convert a Protracker module into a WAVE file using BeginMusicStream().
Show TOC