Name
InsertSample -- insert one sample into another one (V5.0)
Synopsis
InsertSample(src, dst, pos[, len, table])
Function
This function can be used to insert len PCM frames of the sample specified in src into PCM frame position pos of the sample specified in dst. If the optional argument len is not specified, the whole sample will be inserted into the position specified in pos. If the two samples do not use the same format, this function will automatically perform an appropriate conversion of the audio data so that sample depth, channel layout, and sampling rate of the two samples match.

The optional table argument allows you to configure advanced options for the insert operation. The following tags are currently recognized by the optional table argument:

Start, End:
These two tags allow you to specify a range in the source sample that should be inserted into the destination one. This is useful if you want to insert only a part of the source sample into the destination. Both values have to be specified in PCM frames. These tags default to 0 for Start and length of the source sample for End. This means that by default the whole sample will be inserted.

Offset:
Specifies an offset into the source sample at which InsertSample() should start fetching PCM data for the destination sample. This offset must be specified in PCM frames and is relative to the position specified in Start. For instance, if you pass 10000 in Start and 100 in Offset, then InsertSample() will start fetching PCM data at offset 10100. This tag defaults to 0 which means start fetching PCM data from the beginning of the source sample.

Loop:
Specifies whether or not InsertSample() should continue to fetch PCM data at the beginning of the source sample once its end has been reached. This defaults to True which means InsertSample() 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 Start tag.

Please note that this command will extend the length of the destination sample. Existing audio data will not be overwritten. It will just be shifted forward by the insert operation.

Inputs
src
identifier of the source sample
dst
identifier of the sample that shall be modified
pos
position in PCM frames where src should be inserted into dst
len
optional: number of PCM frames to insert into src (defaults to the length of dst)
table
optional: table containing further parameters (see above)
Example
InsertSample(1, 2, 44100, 44100, {Start = 25000, End = 30000})
The code above inserts one second of audio data from sample 1 into sample 2. The sample will be inserted at offset 44100. Audio data will be fetched from sample 1 but only in the range of PCM frames 25000 to 30000 in a loop.
Show TOC