Name
MixSample -- mix existing sample(s) into a new sample (V5.0)
Synopsis
[id] = MixSample(id, len, pitch, fmt, smp1, opt1, ...)
Function
This function can be used to mix one or more existing samples into a new sample. The new sample will be added to Hollywood's sample list and can be accessed by the specified id. If you pass Nil in id, MixSample() will automatically select a vacant identifier and return it to you. The second argument len specifies the desired length of the new sample in PCM frames. The third argument pitch specifies how many frames per second should be sent to the audio device. For CD quality, you would pass 44100 as the pitch argument but in many cases 22050 is also sufficient. The fmt argument specifies the desired sample format for the new sample. Currently, the following formats are supported: #MONO8, #STEREO8, #MONO16, and #STEREO16. The former two specify 8-bit PCM encodings while the latter two use 16-bits per channel.

The samples that should be mixed into the new sample are passed to MixSample() from argument 5 onwards. For each sample that should be mixed into the new sample you have to pass its identifier as well as a table that contains further parameters for the mixing operation. You can repeat this pattern as many times as you like. The options table that has to be passed for each sample supports the following tags:

Pitch:
Specifies the frequency that should be used when mixing this sample. This tag defaults to the sample's current frequency defined using SetPitch().

Offset:
Specifies the offset inside the sample from which PCM data should be fetched for mixing. This must be specified in PCM frames. This tag defaults to 0 which means start fetching data from the beginning.

Length:
Specifies the maximum number of PCM frames that should be mixed. Defaults to -1 which means mix as many frames as available into the new sample.

Loop:
Specifies whether or not the mixer should continue to fetch PCM data at the beginning of the sample once its end has been reached. This defaults to True which means the mixer will automatically revert to the beginning of the sample if its end has been reached and more PCM data is required.

Scale:
Specifies a scaling factor that should be applied to the mixing operation. If you are mixing many samples together, you are likely to get some noise artefacts you do not want. You can reduce these artefacts by reducing the volume level. This can be achieved using this tag. Every PCM frame will be multiplied with the scaling factor you pass here. Thus, to reduce the volume by 50%, simply pass 0.5 here. This tag defaults to 1.0 which means no scaling should be applied.

Threshold:
This tag allows you to specify a threshold at which this sample should be mixed into the destination sample. For example, if you would like this sample to kick in after 10,000 PCM frames have been mixed, you would specify 10000 here. The value specified here must be passed in PCM frames. This tag defaults to 0 which means that this sample should be mixed into the destination sample right from the start.

This function is powerful. It will perform automatic conversion between different sample encodings, sampling rates, and channel layouts. Also, you can mix as many samples into the new sample as you like. The samples to be mixed can also be the same, i.e. you can mix the same sample into the new samples multiple times using different mixing parameters like varying pitch speed or thresholds. If you get unwanted noise artefacts, try reducing the volume of single samples using the Scale tag (see above).

Inputs
id
identifier for the new sample or Nil for auto selection
len
desired length for the new sample in PCM frames
pitch
desired playback frequency for the new sample
fmt
desired format for the new sample
smp1
first sample to mix
opt1
options table for first sample to mix
...
optional: you can repeat the id/options sequence as often as you want so you can mix as many samples together as you like
Results
id
optional: identifier of new sample; this is only used if Nil is passed in the first argument
Example
MixSample(1, 10 * 44100, 44100, #STEREO16, 2, {}, 3,
          {Threshold = 3 * 44100}, 4, {6 * 44100})
The code above creates a new sample in 44.1 format, using 16 bits per PCM frame and two channels. The sample's length will be exactly 10 seconds. The sample will start with sample 2. After three seconds sample 3 will kick in and after six seconds sample 4 will start to play.

Show TOC