Functions#

This section describes the functions provided in the AFX SDK.

NvAFX_GetEffectList#

This function retrieves a list of supported audio effects:

NvAFX_Status NvAFX_GetEffectList(
             int* num_effects,
             NvAFX_EffectSelector* effects[]
);

Parameters#

num_effects [out]

Type: int*

Pointer to an integer that contains the number of effects returned.

effects [out]

Type: NvAFX_EffectSelector* []

Address to a list of effect selection strings supported by the SDK. This list is statically allocated by the SDK, so the caller should not allocate memory for this parameter or free it after use. Refer to NvAFX_EffectSelector for more information about selection strings.

Return Value#

NVAFX_STATUS_SUCCESS on success.

Remarks#

This function retrieves the list of audio effects supported by the SDK. The selection strings for the Audio Effects SDK are populated in the effects output parameter. The number of available effects is written to the num_effects output parameter.

NvAFX_CreateEffect#

This function creates an effect instance:

NvAFX_Status NvAFX_CreateEffect(
   NvAFX_EffectSelector code,
   NvAFX_Handle* effect
);

Parameters#

code [in]

Type: NvAFX_EffectSelector

The selection string for the type of audio effect to be created. Refer to NvAFX_EffectSelector for more information about the allowed selection strings.

effect [out]

Type: NvAFX_Handle*

The pointer to the location where the handle to the newly created audio effect instance will be stored.

Return Value#

NVAFX_STATUS_SUCCESS on success.

Remarks#

This function creates an instance of the specified type of audio effect and returns the handle to this effect via the effect output parameter.

NvAFX_CreateChainedEffect#

This function creates a chained effect instance:

NvAFX_Status NvAFX_CreateEffect(
   NvAFX_EffectSelector code,
   NvAFX_Handle* effect
);

Parameters#

code [in]

Type: NvAFX_EffectSelector

The selection string for the type of chained audio effect to be created. Refer to NvAFX_EffectSelector for more information about the allowed selection strings.

effect [out]

Type: NvAFX_Handle*

The pointer to the location where the handle to the newly created audio effect instance will be stored.

Return Value#

NVAFX_STATUS_SUCCESS on success.

Remarks#

This function creates an instance of the specified type of chained audio effect and returns the handle to this effect via the effect output parameter.

NvAFX_DestroyEffect#

This function destroys an effect instance:

NvAFX_Status NvAFX_DestroyEffect(
   NvAFX_Handle effect
);

Parameters#

effect [in]

Type: NvAFX_Handle

The handle to the audio effect instance to be destroyed.

Return Value#

NVAFX_STATUS_SUCCESS on success.

Remarks#

This function destroys the audio effect instance with the specified handle and frees all resources and memory used by that instance.

NvAFX_SetString#

This function sets a string parameter of the specified effect:

NvAFX_Status NvAFX_SetString(
   NvAFX_Handle effect,
   NvAFX_ParameterSelector param_name,
   const char* val
);

Parameters#

effect [in]

Type: NvAFX_Handle

The handle to the audio effect instance.

param_name [in]

Type: NvAFX_ParameterSelector

For the list of allowed options, see Set the Parameters of an Audio Effect.

val [in]

Type: char*

Pointer to the character string to be set.

Return Value#

NVAFX_STATUS_SUCCESS on success.

Remarks#

This function sets the value of the specified character string parameter for the specified audio effect to val.

NvAFX_SetStringList#

This function sets a string parameter of the specified effect:

NvAFX_Status NvAFX_SetStringList(
   NvAFX_Handle effect,
   NvAFX_ParameterSelector param_name,
   const char** list, unsigned int list_size
);

Parameters#

effect [in]

Type: NvAFX_Handle

The handle to the audio effect instance.

param_name [in]

Type: NvAFX_ParameterSelector

For the list of allowed options, see Set the Parameters of an Audio Effect.

list [in]

Type: char**

Pointer to the character array to be set.

list_size [in]

Type: unsigned int

Size of the character array to be set.

Return Value#

NVAFX_STATUS_SUCCESS on success.

Remarks#

This function sets the value of the specified character string parameter for the specified audio effect to val.

NvAFX_SetU32#

This function sets a unit parameter of the specified effect:

NvAFX_Status NvAFX_SetU32(
   NvAFX_Handle effect,
   NvAFX_ParameterSelector param_name,
   unsigned int val
);

Parameters#

effect [in]

Type: NvAFX_Handle

The handle to the audio effect.

param_name [in]

Type: NvAFX_ParameterSelector

For the list of allowed options, see Set the Parameters of an Audio Effect.

Any other selector string returns an error.

Note

Valid values for setting NVAFX_PARAM_NUM_SAMPLES_PER_INPUT_FRAME can be queried using NvAFX_GetU32List() function with NVAFX_PARAM_SUPPORTED_NUM_SAMPLES_PER_FRAME as the selector. Setting any other value would result in an error.

val [in]

Type: unsigned int

Value to be set for the parameter.

Return Value#

NVAFX_STATUS_SUCCESS on success.

Remarks#

This function sets the value of the specified 32-bit unsigned integer parameter for the specified audio effect to the val parameter.

NvAFX_GetString#

This function gets the current value of the set string parameter of the specified effect:

NvAFX_Status NvAFX_GetString(
   NvAFX_Handle effect,
   NvAFX_ParameterSelector param_name,
   char* val,
   int max_length
);

Parameters#

effect [in]

Type: NvAFX_Handle

The handle to the audio effect instance.

param_name [in]

Type: NvAFX_ParameterSelector

For the list of allowed options, see Get the Parameters of an Audio Effect.

val [out]

Type: char*

The address of the buffer where the requested character string would be stored. This buffer must be allocated by and freed by the caller.

max_length [i

Type: int

The length in bytes of the buffer that is specified by the val parameter.

Return Value#

NVAFX_STATUS_SUCCESS on success.

Remarks#

This function gets the value of the character string parameter for the specified audio effect and writes the retrieved string to the buffer at the location specified by the val parameter.

NvAFX_GetU32#

This function gets the value of a uint parameter of the specified effect:

NvAFX_Status NvAFX_GetU32(
   NvAFX_Handle effect,
   NvAFX_ParameterSelector param_name,
   unsigned int* val
   );

Parameters#

effect [in]

Type: NvAFX_Handle

The handle to the audio effect instance.

param_name [in]

Type: NvAFX_ParameterSelector

For the list of allowed options, see Get the Parameters of an Audio Effect. Any other selector string returns an error.

Note

Effect parameters (except for supported frame size list) can be queried only after the effect is loaded. Querying parameters before model load may return invalid values/function may fail with error code.

For SDK, while NVAFX_PARAM_NUM_SAMPLES_PER_INPUT_FRAME can be queried after model load using this API (returns the default number of samples per frame, if not set), you should use NvAFX_GetU32List() with the NVAFX_PARAM_SUPPORTED_NUM_SAMPLES_PER_FRAME parameter to get the list of supported values. You can then use NvAFX_SetU32() with the NVAFX_PARAM_NUM_SAMPLES_PER_FRAME parameter to set the value.

val [out]

Type: unsigned int*

The address of the buffer where the retrieved 32-bit unsigned integer parameter value will be written.

NvAFX_GetU32List#

This function gets the uint list parameter values for the specified effect:

NvAFX_Status NvAFX_GetU32List(
   NvAFX_Handle effect,
   NvAFX_ParameterSelector param_name,
   unsigned int* list[],
   int* list_size
   );

Remarks#

This function gets the value of the specified 32-bit unsigned integer parameter for the specified audio effect and writes the retrieved value to the buffer specified by val.

Parameters#

effect [in]

Type: NvAFX_Handle

The handle to the audio effect instance.

param_name [in]

Type: NvAFX_ParameterSelector

The following selector: NVAFX_PARAM_SUPPORTED_NUM_SAMPLES_PER_FRAME

Any other selector string returns an error.

Note

Values returned for NVAFX_PARAM_SUPPORTED_NUM_SAMPLES_PER_FRAME as the selector depends on the sample rate. Sample rate must be set using NvAFX_SetU32() with the NVAFX_PARAM_SAMPLE_RATE selector before making this call.

list [out]

Type: unsigned int* []

The address to a list containing the 32-bit unsigned values for the given selector.

Note

The application needs to call this API with list_size initialized to zero, and list set to nullptr to get the size of list to be allocated. The size will be returned in list_size parameter.The application can then allocate an U32 array of at least list_size and call the API again with list pointing to the array. For an example, see Create an Audio Effect.

list_size [out]

Type: int*

Pointer to an integer that contains the number of values returned in the list.

Return Values#

NVAFX_STATUS_SUCCESS on success.
NVAFX_STATUS_OUTPUT_BUFFER_TOO_SMALL when the list_size is less than the minimum required size of the list array.

Remarks#

This function gets the list of 32-bit unsigned integer values for the specified audio effect and writes the retrieved values to a buffer specified by list and writes the size of the returned list in the buffer specified by list_size.

NvAFX_GetBoolList#

This function gets the boolean list parameter values for the specified effect:

NvAFX_Status NvAFX_GetBoolList(
   NvAFX_Handle effect,
   NvAFX_ParameterSelector param_name,
   NvAFX_Bool* list[],
   int* list_size
);

Parameters#

effect [in]

Type: NvAFX_Handle

The handle to the audio effect instance.

param_name [in]

Type: NvAFX_ParameterSelector

The following selector: NVAFX_PARAM_VAD_RESULT

Any other selector string returns an error.

list [out]

Type: NvAFX_Bool* []

The address to a list that contains the boolean values for the given selector.

Note

The application needs to call this API with list_size initialized to zero, and list set to nullptr to get the size of list to be allocated. The size will be returned in list_size parameter.The application can then allocate an array of at least list_size and call the API again with list pointing to the array. For an example, see Create an Audio Effect.

list_size [out]

Type: int*

Pointer to an integer that contains the number of values that were returned in the list.

Return Values#

NVAFX_STATUS_SUCCESS on success.
NVAFX_STATUS_OUTPUT_BUFFER_TOO_SMALL when the list_size is less than the minimum required size of the list array.

Remarks#

This function gets the list of boolean values for the specified audio effect, writes the retrieved values to a buffer specified by list, and writes the size of the returned list in the buffer specified by list_size.

NvAFX_GetSupportedDevices (Windows SDK only)#

The function gets a list of compatible devices that are supported by the currently set model file but is not supported by chained effects:

NvAFX_Status NvAFX_GetSupportedDevices(
   NvAFX_Handle effect,
   int *num,
   int *devices
);

Parameters#

effect [in]

Type: NvAFX_Handle

The handle to the audio effect instance to load.

num [in, out]

Type: int*

The size of the input array. If the call succeeds, this value will be set by the function.

devices [in, out]

Type: int*

Array of size num. The function will fill the array with CUDA device indices of devices supported by the model, in descending order of preference, where the first device is the most preferred device.

Return Value#

NVAFX_STATUS_SUCCESS on success.

Remarks#

This function gets the devices supported by the model.

NvAFX_Load#

This function validates effect parameters and loads the specified effect:

NvAFX_Status NvAFX_Load(
        NvAFX_Handle effect
);

Parameters#

effect [in]

Type: NvAFX_Handle

The handle to the audio effect instance to load.

Return Value#

NVAFX_STATUS_SUCCESS on success.

Remarks#

This function validates the parameters that are set for the effect and loads the specified audio effect.

NvAFX_Run#

This function runs the specified effect:

NvAFX_Status NvAFX_Run(
   NvAFX_Handle effect,
   const float** input,
   float** output,
   unsigned num_samples,
   unsigned num_channels
);

Parameters#

effect [in]

Type: NvAFX_Handle

The handle to the audio effect instance to run.

input [in]

Type: const float**

Pointer to a user-allocated array of buffers where each buffer holds the audio data for one channel.The size of the array must be equal to the number of input samples in the frame (set via NVAFX_PARAM_NUM_SAMPLES_PER_INPUT_FRAME) multiplied by the number of streams for which the effect is configured (set via NVAFX_PARAM_NUM_STREAMS, always 1 for Windows SDK). The number of channels must be equal to the value of the NVAFX_PARAM_NUM_INPUT_CHANNELS parameter that was obtained by the NvAFX_GetU32() function.

The sample rate of the audio data must be equal to the input sample rate of the effect (can be queried using NvAFX_GetU32 using the NVAFX_PARAM_INPUT_SAMPLE_RATE selector).

output [out]

Type: float**

Pointer to a user-allocated array of buffers to which the output of the effect will be written. After this function returns, each buffer will contain audio data for one channel.

Note

The buffers must be allocated by and later freed by the calling program. NvAFX_Run internally copies input/output to/from the GPU, so pinning input/output buffers does not have any effect.

The size of the array must be equal to the number of output samples in the frame (set via NVAFX_PARAM_NUM_SAMPLES_PER_OUTPUT_FRAME) multiplied by the number of streams for which the effect is configured (set via NVAFX_PARAM_NUM_STREAMS, always 1 for Windows SDK).

num_samples [in]

Type: unsigned

The number of samples in the input buffer.

num_channels [in]

Type: unsigned

The number of input channels.

Return Value#

NVAFX_STATUS_SUCCESS on success.

Remarks#

This function runs the specified audio effect by reading the contents of the input buffer, applying the audio effect, and writing the output to the output buffer.

NvAFX_Reset#

This function resets the internal state and flushes the internal history for the specified batches:

Windows SDK:

NvAFX_Status NvAFX_Reset(
   NvAFX_Handle effect
);

Linux SDK:

NvAFX_Status NvAFX_Reset(
   NvAFX_Handle effect,
   NvAFX_Bool* list,
   int length
);

Note

This functionality is not supported by Speaker Separation effects.

Parameters#

effect [in]

Type: NvAFX_Handle

The handle to the audio effect instance to run.

list [in] (Linux SDK only)

Type: NvAFX_Bool *

Pointer to a memory location which indicates the streams to be reset. The i-th element in this array should be set to NVAFX_TRUE to reset the i-th stream, and to NVAFX_FALSE otherwise.

length [in] (Linux SDK only)

Type: int

Number of elements in the array specified. Should be equal to the number of streams (batches).

Return Value#

NVAFX_STATUS_SUCCESS on success.

NvAFX_SetBoolList#

This function sets a list parameter of the specified effect:

NvAFX_Status NvAFX_SetBoolList(
   NvAFX_Handle effect,
   NvAFX_ParameterSelector param_name,
   const NvAFX_Bool* list,
   unsigned int list_size
);

Parameters#

effect [in]

Type: NvAFX_Handle

The handle to the audio effect.

param_name [in]

Type: NvAFX_ParameterSelector

The following selectors are supported for this function: NVAFX_PARAM_ACTIVE_STREAMS

Any other selector string returns an error.

list [in]

Type: NvAFX_Bool*

Array of Boolean values to be set for the parameter.

list_size [in]

Type: unsigned int

Size of the Boolean array passed as input.

Return Value#

NVAFX_STATUS_SUCCESS on success.

Remarks#

This function sets the boolean values of the list parameter for the specified audio effect to the values from list.

NvAFX_SetU32List#

This function sets a list parameter of the specified effect:

NvAFX_Status NvAFX_SetU32List(
   NvAFX_Handle effect,
   NvAFX_ParameterSelector param_name,
   const unsigned int* list,
   unsigned int list_size
);

Parameters#

effect [in]

Type: NvAFX_Handle

The handle to the audio effect.

param_name [in]

Type: NvAFX_ParameterSelector

The following selectors are supported for this function: NVAFX_PARAM_CHAINED_EFFECT_GPU_LIST

Any other selector string returns an error.

list [in]

Type: unsigned int*

Array of U32 values to be set for the parameter.

list_size [in]

Type: unsigned int

Size of the array that was passed as the input.

Return Value#

NVAFX_STATUS_SUCCESS on success.

Remarks#

This function sets the U32 values of the list parameter for the specified audio effect to the values from list.

NvAFX_SetFloatList#

This function sets a list parameter of the specified effect:

NvAFX_Status NvAFX_SetU32List(
   NvAFX_Handle effect,
   NvAFX_ParameterSelector param_name,
   float* list,
   unsigned int list_size
);

Parameters#

effect [in]

Type: NvAFX_Handle

The handle to the audio effect.

param_name [in]

Type: NvAFX_ParameterSelector

The following selectors are supported for this function: NVAFX_PARAM_CHAINED_EFFECT_GPU_LIST

Any other selector string returns an error.

list [in]

Type: unsigned float*

Array of float values to be set for the parameter.

list_size [in]

Type: unsigned int

Size of the array that was passed as the input.

Return Value#

NVAFX_STATUS_SUCCESS on success.

Remarks#

This function sets the float values of the list parameter for the specified audio effect to the values from list. This function currently is supported only for setting per-stream intensity ratio for the Background Noise Removal effect

NvAFX_SetStreamFloatList (Linux SDK Only)#

This function is used to set a list of floats for a specified subset of streams:

NvAFX_Status NvAFX_SetStreamFloatList(
   NvAFX_Handle effect,
   NvAFX_ParameterSelector param_name,
   const unsigned int* stream_idx, const float** values,
   unsigned int list_size);

Parameters#

effect [in]

Type: NvAFX_Handle

The handle to the audio effect.

param_name [in]

Type: NvAFX_ParameterSelector

The following selectors are supported by this function: NVAFX_PARAM_REFERENCE_AUDIO

Any other selector string returns an error..

stream_idx [in]

Type: const unsigned int*

List of streams for which data is to be set (starts with 0 for the first stream).

values [in]

Type: const float**

Per stream data to be passed in.

list_size [in]

Type: unsigned int

Number of streams to set

Return Value#

NVAFX_STATUS_SUCCESS on success.

Remarks#

This API allows the user to set float list values only for specified streams.

For example, in the Voice Font effect, this API can be used to set the reference audio of specific streams (eg, 1st and 2nd stream)

NvAFX_InitializeLogger#

This function initializes the SDK logger:

NvAFX_Status NvAFX_InitializeLogger(
   LoggingSeverity level,
   int target,
   const char *filename,
   logging_cb_t cb,
   void* userdata
);

Parameters#

level [in]

Type: LoggingSeverity

The logging level to enable. Enabling a level is inclusive of the levels preceding it.

For example, LOG_LEVEL_INFO also includes LOG_LEVEL_WARNING and LOG_LEVEL_ERROR.

This field can have either of the following values :

LOG_LEVEL_FATAL (Windows Only)

LOG_LEVEL_ERROR

LOG_LEVEL_WARNING

LOG_LEVEL_INFO

target [in]

Type: int

Logging targets to write logs to, LoggingTarget can be binary OR’d to enable multiple targets.

The following targets can be used:

LOG_TARGET_NONE = 0x0

LOG_TARGET_STDERR = 0x1

LOG_LEVEL_FILE = 0x2

LOG_LEVEL_CALLBACK = 0x4

filename [in]

Type: const char*

The path of the file where to write logs. Used only when LOG_TARGET_FILE is enabled.

Note

The directory in which the log file resides must exist. For example, if the filename is /foo/bar/log.txt, the /foo/bar directory must already exist. If the log.txt file exists, it is overwritten.

cb [in]

Type: const char *

Callback to use if LOG_TARGET_CALLBACK is enabled. NULL can be passed if not using a callback target.

userdata [in]

Type: void *

Data passed back with log callback. Used only when LOG_TARGET_CALLBACK is enabled.

A null value can also be passed.

Return Value#

NVAFX_STATUS_SUCCESS on success.

Remarks#

This API enables logging in the SDK. Depending on the flags passed, logs are either redirected to stderr, file, or callback. Logging can be disabled using the NvAFX_UninitializeLogger API. Refer to NvAFX_UninitializeLogger for more information.

NvAFX_UninitializeLogger#

NvAFX_Status NvAFX_UninitializeLogger(void);

Parameters#

NvAFX_UninitializeLogger requires no parameters.

Return Value#

NVAFX_STATUS_SUCCESS on success.

Remarks#

This API disables all logging targets. Logging can be started again using the NvAFX_InitializeLogger() API. Refer to NvAFX_InitializeLogger for more information.