[id] = MixSample(id, len, pitch, fmt, smp1, opt1, ...)

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).

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

id

optional: identifier of new sample; this is only used if Nil is passed in the first argument

MixSample(1, 10 * 44100, 44100, #STEREO16, 2, {}, 3,
          {Threshold = 3 * 44100}, 4, {6 * 44100})