/ HALion Developer Resource / HALion Script / Reference /

decompose

decompose{arguments}

(Since HALion 7.0)

Description

Function to decompose an audio file into its tonal and noise components. You specify the audio file with the AudioFile object that is returned by the AudioFile.open function. The decompose function can be configured with named arguments. The named arguments are optional and if called without, decompose will be executed with its default settings.

Available in: Controller.

Arguments

Argument	Description	Value Type
callback	This callback function is called with the AudioFile object and the file path of the ouput sample(s) as arguments after the original sample has been decomposed. If called without a callback function, decompose will be executed in the same thread. If called with a callback function as argument, decompose will be executed in a separate, parallel thread.	function, optional
start	The start position in samples. The created samples are trimmed to this position. The default is 0 samples.	number, optional
length	The duration in samples. Set this to less than or equal to 0 to use all samples from the specified `start` to the end of the sample. By default, everything from `start` to the end of the sample is decomposed. The created samples are trimmed to this length.	number, optional
sensitivity	Determines the minimum level difference that is needed to distinguish the tonal from the noise signals. The sensitivity is specified in dB and the value range is from -96 to 0 dB. The default is -24 dB.	number, optional
cutoff	Sets the frequency limit below which the algorithm detects tonal signals. Any signals above the cutoff frequency are classified as noise, regardless of the `sensitivity` and `duration` arguments. The cutoff is specified in Hz and the value range is from 20 to 20000 Hz. The default is 20000 Hz.	number, optional
duration	Allows you to specify the minimum length for a tonal signal in milliseconds. Signals that are shorter than the specified duration are classified as noise, longer signals are classified as tonal. The value range is fom 0 to 100 ms. The default is 80 ms.	number, optional
tonalLevel	Specifies the level of the tonal component in dB. The value range is from -96 to +12 dB. The default is 0 dB.	number, optional
noiseLevel	Specifies the level of the noise component in dB. The value range is from -96 to +12 dB. The default is 0 dB.	number, optional
outputMode	Defines if only one of the components, both components, or a mix of them is created. See Decompose Output Modes for details.	number, optional
outputPath	Specifies the path for the decomposed audio files. If the string is empty, invalid, or nil, the file paths of the decompose settings of the plug-in will be used. The default is nil.	string, optional

❕ Samples that were loaded from a VST Sound container can only be decomposed if the ouputPath argument is set to a valid file location. You can use getDecomposeOutputPath to obtain the file location from the decompose settings of the plug-in.

Example

outputModes = { "Tonal", "Noise", "All", "Mix", }
 
defineParameter { name = "Decompose", default = false, onChanged = function() if Decompose then onDecompose() end end }
defineParameter { name = "Cancel", default = false}
defineParameter { name = "Sensitivity", default = -24, min = -96, max = 0, increment = 0.1 }
defineParameter { name = "Cutoff", default = 20000, min = 20, max = 20000, increment = 1 }
defineParameter { name = "Duration", default = 80, min = 0, max = 100, increment = 0.1 }
defineParameter { name = "TonalLevel", default = 0, min = -96, max = 12, increment = 0.1 }
defineParameter { name = "NoiseLevel", default = 0, min = -96, max = 12, increment = 0.1 }
defineParameter { name = "Start", default = 0, min = 0, max = 1000, increment = 1 }
defineParameter { name = "Length", default = 0, min = 0, max = 1000, increment = 1 }
defineParameter { name = "OutputMode", default = DecomposeOutputMode.all, strings = outputModes }
defineParameter { name = "OutputPath", default = "" }
defineParameter { name = "Subfolder", default = "" }
 
function onDecomposeFinished(audioFile, file1, file2)
    print("Progress: 100%")
    print(audioFile.fileName, audioFile.length)
    if file1 then
        local afile1 = AudioFile.open(file1)
        print(afile1.fileName, afile1.length)
    end
    if file2 then
        local afile2 = AudioFile.open(file2)
        print(afile2.fileName, afile2.length)
    end
end
 
function onDecompose()
    zones = this.parent:findZones(true)
    for i, zone in ipairs(zones) do
        local samplePath = zone:getParameter("SampleOsc.Filename")
        local afile = AudioFile.open(samplePath)
        local startSamples = Start * afile.rate/1000
        local lengthSamples = Length * afile.rate/1000
        if not Subfolder == "" then
            if OutputPath == "" then
                OutputPath = getDecomposeOutputPath(samplePath)..Subfolder
            else
                OutputPath = OutputPath..Subfolder
            end
        end
        print("Decompose: "..samplePath)
        afile:decompose{
            callback = onDecomposeFinished,
            start = startSamples,
            length = lengthSamples,
            sensitivity = Sensitivity,
            cutoff = Cutoff,
            duration = Duration,
            tonalLevel = TonalLevel,
            noiseLevel = NoiseLevel,
            outputMode = OutputMode,
            outputPath = OutputPath,
        }
        while afile:getDecomposeProgress() < 1 do
            if Cancel then
                afile:cancelDecompose()
                break
            end
            local progress, errorMessage = afile:getDecomposeProgress()
            if errorMessage then
                print(errorMessage)
                break
            end
            local progressPercent = 100 * progress
            print(string.format("Progress: %2d%%", progressPercent))
            wait(2000)
        end
        if Cancel then
            Cancel = false
            print("Decompose Canceled!")
            break
        end
    end
    print("Decompose finished.")
    Decompose = false
end

See also: cancelDecompose, getDecomposeProgress, Decompose Output Modes, getDecomposeSettings, getDecomposeOutputPath