Real-Time Parameter Tuning

Parameter tuning is the ability to modify parameters of your audio system in real time while streaming an audio signal. In algorithm development, tunable parameters enable you to quickly prototype and test various parameter configurations. In deployed applications, tunable parameters enable users to fine-tune general algorithms for specific purposes, and to react to changing dynamics.

Audio Toolbox™ is optimized for parameter tuning in a real-time audio stream. The System objects, blocks, and audio plugins provide various tunable parameters, including sample rate and frame size, making them robust tools when used in an audio stream loop.

To optimize your use of Audio Toolbox, package your audio processing algorithm as an audio plugin. Packaging your audio algorithm as an audio plugin enables you to graphically tune your algorithm using parameterTuner or Audio Test Bench:

• Audio Test Bench –– Creates a user interface (UI) for tunable parameters, enables you to specify input and output from your audio stream loop, and provides access to analysis tools such as the time scope and spectrum analyzer. Packaging your code as an audio plugin also enables you to quickly synchronize your parameters with MIDI controls.

• parameterTuner –– Creates a UI for tunable parameters that can be used from any MATLAB^® programmatic environment. You can customize your parameter controls to render as knobs, sliders, rocker switches, toggle switches, check boxes, or drop-downs. You can also define a custom background color, background image, or both. You can then place your audio plugin in an audio processing loop in a programmatic environment such as a script, and then tune parameters while the loop executes.

For more information, see Audio Plugins in MATLAB.

Other methods to create UIs in MATLAB include:

• App Designer –– Development environment for a large set of interactive controls with support for 2-D plots. See Create and Run a Simple App Using App Designer for more information.

• Programmatic workflow –– Use MATLAB functions to define your app element-by-element. This tutorial uses a programmatic approach.

See Ways to Build Apps for a more detailed list of the costs and benefits of the different approaches to parameter tuning.

Programmatic Parameter Tuning

If you can not package your algorithm as an audio plugin, you can create a tuning UI using basic MATLAB techniques.

This tutorial contains three files:

1. parameterRef –– Class definition that contains tunable parameters

2. parameterTuningUI –– Function that creates a UI for parameter tuning

3. AudioProcessingScript –– Script for audio processing

Inspect the diagram for an overview of how real-time parameter tuning is implemented. To implement real-time parameter tuning, walk through the example for explanations and step-by-step instructions.

1. Create Class with Tunable Parameters

To tune a parameter in an audio stream loop using a UI, you need to associate the parameter with the position of a UI widget. To associate a parameter with a UI widget, make the parameter an object of a handle class. Objects of handle classes are passed by reference, meaning that you can modify the value of the object in one place and use the updated value in another. For example, you can modify the value of the object using a slider on a figure and use the updated value in an audio processing loop.

Open the parameterRef class definition file.

classdef parameterRef < handle
    properties
        name
        value
    end
end

Objects of the parameterRef class have a name and value. The name is for display purposes on the UI. You use the value for tuning.

2. Create Function to Generate a UI

The parameterTuningUI function accepts your parameter, specified as an object handle, and the desired range. The function creates a figure with a slider associated with your parameter. The nested function, slidercb, is called whenever the slider position changes. The slider callback function maps the position of the slider to the parameter range, updates the value of the parameter, and updates the text on the UI. You can easily modify this function to tune multiple parameters in the same UI.

 parameterTuningUI

Open parameterTuningUI.

function parameterTuningUI(parameter,parameterMin,parameterMax)

% Map slider position to specified range
rangeVector = linspace(parameterMin,parameterMax,1001);
[~,idx] = min(abs(rangeVector-parameter.value));
initialSliderPosition = idx/1000;

% Main figure
hMainFigure = figure( ...
    'Name','Parameter Tuning', ...
    'MenuBar','none', ...
    'Toolbar','none', ...
    'HandleVisibility','callback', ...
    'NumberTitle','off', ...
    'IntegerHandle','off');
    
    % Slider to tune parameter
    uicontrol('Parent',hMainFigure, ...
        'Style','slider', ...
        'Position',[80,205,400,23], ...
        'Value',initialSliderPosition, ...
        'Callback',@slidercb);
    
    % Label for slider
    uicontrol('Parent',hMainFigure, ...
        'Style','text', ...
        'Position',[10,200,70,23], ...
        'String',parameter.name);
    
    % Display current parameter value
    paramValueDisplay = uicontrol('Parent',hMainFigure, ...
        'Style','text', ...
        'Position', [490,205,50,23], ...
        'BackgroundColor','white', ...
        'String',parameter.value);
    
    % Update parameter value if slider value changed
    function slidercb(slider,~)
        val = get(slider,'Value');
        rangeVectorIndex = round(val*1000)+1;
        parameter.value = rangeVector(rangeVectorIndex);
        set(paramValueDisplay,'String',num2str(parameter.value));
    end
end

3. Create Script for Audio Processing

The audio processing script:

1. Creates input and output objects for an audio stream loop.

2. Creates an object of the handle class, parameterRef, that stores your parameter name and value.

3. Calls the tuning UI function, parameterTuningUI, with your parameter and the parameter range.

4. Processes the audio in a loop. You can tune your parameter, x, in the audio stream loop.

 Run AudioProcessingScript

Open AudioProcessingScript, and then run the file.

%% A. Create input and output objects
fileReader = dsp.AudioFileReader( ...
    'speech_dft.mp3', ...
    'SamplesPerFrame',64, ...
    'PlayCount',3);
deviceWriter = audioDeviceWriter( ...
    'SampleRate',fileReader.SampleRate);

%% B. Create an object of a handle class
x = parameterRef;
x.name = 'gain';
x.value = 2.5;

%% C. Open the UI function for your parameter
parameterTuningUI(x,0,5);

%% D. Process audio in a loop
while ~isDone(fileReader)
    audioIn = fileReader();
    
    drawnow limitrate
    audioOut = audioIn.*x.value;
    
    deviceWriter(audioOut);
end

% Release input and output objects
release(fileReader)
release(deviceWriter)

While the script runs, move the position of the slider to update your parameter value and hear the result.