Name
GetMusicSample -- extract samples from music (V11.0)
Synopsis
[id] = GetMusicSample(srcid, id, length[, t])
Library
sound

Function
This function can be used to extract a number of samples from the music specified by srcid. It will create the new Hollywood sample object specified by id which will contain the audio data just extracted from the music. If you pass Nil in id, GetMusicSample() will automatically select an identifier and return it to you. Audio data extraction will start from the current music position which can be modified by SeekMusic(). GetMusicSample() will also advance the current music position by the number of samples read.

The length argument must contain the number of samples to extract, e.g. if you wish to extract 10 seconds of sound data from a music whose playback frequency is 44100hz, you'd have to pass 441000 in length (44100 * 10). Note that since sample data is quite memory hungry you should only extract a reasonable amount of samples per call to avoid running out of memory.

The music specified by srcid must not be playing. It must be in stopped state. Also note that calling GetMusicSample() will put the music object into a special read state which will block all other functions on the music object except SeekMusic(). If you want to start playback of the music object you have used GetMusicSample() on, you first have to close and re-open it.

There is also an optional table argument t allowing you to configure further options. This table argument accepts the following tags:

Hardware:
By default, Hollywood will always create hardware samples. These are samples that can be played instantly. If you don't want to play the sample, however, you can set this tag to False to create a software sample. Software samples are more efficient because they are completely independent of the audio hardware because they will never be played. Defaults to True.

Inputs
srcid
identifier of the music to extract audio data from
id
identifier for the new sample or Nil for auto selection
length
number of samples to extract from music
t
optional: table containing further options (see above)
Results
id
optional: identifier of new sample; this is only used if Nil is passed in the first argument
Example
freq = GetAttribute(#MUSIC, 1, #ATTRPITCH)
GetMusicSample(1, 1, freq * 10)
The code above extracts 10 seconds of audio data from music 1 and stores it in sample 1.
Show TOC