soundfx.Process

Name

soundfx.Process -- apply effect(s) to sample(s)

Synopsis

[id] = soundfx.Process(src, dst[, fx])

Function

This function can be used to apply one or more effects to the sample(s) specified in src. The source sample(s) won't be modified directly. Instead, this function will create a new sample using the identifier specified by dst. If you pass Nil in dst, soundfx.Process() will automatically choose an available identifier and return it to you. The source and destination samples mustn't be the same.

The src argument can either be the identifier of a sample or it can be a table containing a number of samples. If src is a table, it must contain a subtable for each sample that you want to pass to soundfx.Process(). The subtable can contain the following fields:

ID: Specifies the ID of the sample. This table element must always be set.
Volume: Specifies the desired volume of the sample. This can be used to modify the volume before any effects are applied. Values smaller than 1.0 will decrease the volume, whereas values higher than 1.0 will increase the volume. This can be particularly useful when using the #SOUNDFX_MIX mode. In that case, it allows you to fine-tune the volume of the individual samples to be mixed together. This tag defaults to 1.0 which means that no changes to the volume will be made.

When passing multiple samples to soundfx.Process(), you can use the Mode table tag to specify how the samples should be processed. By default, #MODE_JOIN is used which means that the samples will be processed one after the other so that once soundfx.Process() has finished, all samples will have been joined together. Alternatively, you can also use #MODE_MIX which means that the samples will be mixed together. Finally, there's also #MODE_MERGE and #MODE_MULTIPLY. See below for details.

Note that when passing multiple samples to soundfx.Process(), all samples must use the same sampling rate. When using #MODE_JOIN (the default), the samples must also use the same channel layout.

The effect(s) that should be applied to the sample must be specified in the fx table argument. This must be set to a table of tables, i.e. a table containing an arbitrary number of subtables, each containing a single effect specification that should be applied to the sample. The effects are applied to the sample in the order they appear in the fx.

The subtables containing the effect specification must start with the name of the effect followed by the individual effect parameters. These differ from effect to effect. Please see the individual effect descriptions in the following chapters to find out about mandatory and optional effect parameters. Also see the chapter on effect parameters to learn about how the effect syntax is constructed. Also note that some effects like synth are generative which means that they produce their own audio instead of processing given audio data. To use such generative effects you need to use soundfx.Generate() instead of soundfx.Process().

Additionally, the fx table also allows you to specify some other options that shall be passed to the sound processor. The following options are currently recognized:

Mode

This specifies how the sound processor should behave in case multiple samples are passed to it. This can be set to the following constants:

#SOUNDFX_JOIN: This mode will simply concatenate the samples. The frequency and channel layout of the samples to be joined must be the same. This is the default.
#SOUNDFX_MIX: This mode will mix the samples. The frequency of the samples to be mixed must be the same. The channel layout of the samples can be different but in that case some channels in the output sample will not contain audio from every input sample.
#SOUNDFX_MERGE: This mode will merge the samples. The frequency of the samples to be merged must be the same. The channel layout of the samples can be different. A merged sample comprises all of the channels from all of the input samples, e.g. it is possible to merge two mono samples into a stereo one. The first and second mono sample would become the left and right channels of the stereo sample.
#SOUNDFX_MULTIPLY: This mode multiplies the sample values. The frequency of the samples to be multiplied must be the same. The sample values of corresponding channels will be treated as numbers in the interval -1 to +1. If the number of channels in the input samples is not the same, the missing channels are considered to contain all zero.

The default mode is #SOUNDFX_JOIN.

Frequency

The new frequency for the sample in Hertz. It's only necessary to set this if the effect alters the sample resolution, e.g. by resampling it, or if you're using soundfx.Generate() and you want to modify the generator effect's default frequency.

Bits

The new bit depth for the sample. Currently only 8 or 16 are supported here. It's only necessary to specify this if you want to change the bit depth of the sample or if you're using soundfx.Generate() and you want to modify the generator effect's default bit depth setting.

Channels

The new number of channels used by the sample. Currently only 1 (mono) or 2 (stereo) are supported here. It's only necessary to specify this if you want to change the channel layout of the sample or if you're using soundfx.Generate() and you want to modify the generator effect's default channel layout setting.

Verbosity

This tag can be used to set how much information the sound processor should output. This defaults to 0 which means that no messages are shown at all. The following verbosity levels are supported:

0: No messages are shown at all. This is the default.
1: Only error messages are shown. These are generated if the plugin cannot apply the requested effects.
2: Warning messages are also shown. These are generated if the plugin can complete the requested commands, but not exactly according to the requested command parameters, or if clipping occurs.
3: Descriptions of the processing phases are also shown. Useful for seeing exactly how the plugin is processing your audio.
4 and above: Messages to help with debugging are also shown.

By default, messages are printed to the standard output but you can also intercept them by installing a callback function using the Callback tag (see below).

Callback

If you set this tag to a Hollywood function, the SoundFX plugin will call the function periodically so that you can update a status bar or something similar. The callback function will also be called whenever the sound processor has to output a message. When the SoundFX plugin runs your callback, it will pass a table that has the following fields initialized to it:

Action: This will be set to either #SOUNDFX_STATUS if the callback has been run to inform you about a status update or it can be #SOUNDFX_OUTPUT if the callback has been run because a message should be output.
Processed: This contains the number of PCM frames already processed. This is only set if Action is #SOUNDFX_STATUS.
Total: This contains the total number of PCM frames to be processed. This is only set if Action is #SOUNDFX_STATUS.
Output: This contains the message string that should be output. This is only set if Action is #SOUNDFX_OUTPUT.
UserData: If you use the UserData tag (see below) to specify data that should be passed to the callback, this field will be initialized to contain this user data. Otherwise this field won't be set.

UserData

If you have set the Callback tag to a callback function, you can use this tag to specify user data that should be passed to your callback function whenever it is run. The user data you specify here will be passed in the UserData element of the table argument that is passed to the callback function.

Software

If this tag is set to True, the destination sample will be created as a software sample. See the Hollywood manual for more information on the difference between software and hardware samples. Defaults to False.

UseTempFile

Some effects can use a temporary file instead of memory buffers. If you want those sound effects to use a temporary file, set this tag to True. Otherwise everything will be done in memory. Setting this to True can be useful when dealing with large samples on low-memory systems. Defaults to False.

Note that the fx table can also be omitted. In that case, no effects are applied and the source sample is simply copied to the destination one, or, if multiple samples are specified, the source samples are concatenated to form the destination sample.

Inputs

src: identifier of the source sample or table containing multiple samples (see above)
dst: identifier for the new sample or Nil for auto id selection
fx: optional: table containing effect(s) and options to be applied

Results

id: optional: identifier of the sample; will only be returned when you pass Nil as argument 2 (see above)

Example

soundfx.Process(1, 2, {{"tempo", "0.8"}})

The code above reduces the tempo of sample 1 to 80% of its original playback speed and stores the result in sample 2.

soundfx.Process(1, 2, {{"phaser"}, {"vol", "0.5"}})

The code above first applies the phaser effect to sample 1 and then reduces the volume to 50%. The result will be stored in sample 2.

soundfx.Process(1, 2, {{"rate", "48k"}}, {Frequency = 48000})

The code above resamples the audio data of sample 1 to 48000hz and stores the result in sample 2. Note that we must pass the new frequency in the table which is passed as the 4th parameter. Passing the 4th parameter is only necessary for effects which modify the sample resolution (i.e. bit depth, frequency, channel layout). See above for more information.

soundfx.Process({{ID = 1}, {ID = 2}}, 3)

The code above will concatenate samples 1 and 2 and store the result in sample 3.

soundfx.Process({{ID = 1, Volume = 0.5}, {ID = 2}}, 3, {Mode =
                 #SOUNDFX_MIX})

The code above will mix samples 1 and 2 and store the result in sample 3. The volume of sample 1 will be reduced by 50% before mixing.

Show TOC