Hopefully constructive criticism to improve the SDK

AI & Data Science Deep Learning (Training & Inference) Maxine
1

I have ~30 years of programming experience and just started using the Maxine Audio SDK a few days ago.
The documentation looks like a good attempt was made at it, but parts of it are a little sketchy.

This doc has many grammar errors and/or typos, even some in the actual code.
Example:

unsigned num_samples_per_frame, num_channels, sample_rate;
NvAFX_Status err;
err = NvAFX_GetU32(handle, NVAFX_PARAM_NUM_SAMPLES_PER_INPUT_FRAME, &num_samples_per_frame);
err = NvAFX_GetU32(handle, NVAFX_PARAM_NUM_INTPUT_CHANNELS, &num_channels);
err = NvAFX_GetU32(handle, NVAFX_PARAM__OUTPUT_SAMPLE_RATE, &sample_rate);

NVAFX_PARAM_NUM_SAMPLES_PER_INPUT_FRAME does not exist in the Windows SDK nvAudioEffects.h, but NVAFX_PARAM_NUM_INPUT_SAMPLES_PER_FRAME does.
NVAFX_PARAM_NUM_INTPUT_CHANNELS?
NVAFX_PARAM__OUTPUT_SAMPLE_RATE?

To further the confusion, the docs say:

To get the default number of samples per input frame, specify one of the following options:

  • For Linux
    NVAFX_PARAM_NUM_SAMPLES_PER_INPUT_FRAME

  • For Windows
    NVAFX_PARAM_NUM_INPUT_SAMPLES_PER_FRAME

Why two separate but nearly identical names?
Why not just deprecate one and consolidate them to a single consistent name?

Stepping back from all of this, it is also very confusing to first tell someone:
https://docs.nvidia.com/deeplearning/maxine/audio-effects-sdk/index.html#set-params-audio-effect

4.3. Setting the Parameters of an Audio Effect
To set U32 values, call the NvAFX_SetU32() function with the following parameters:
…

Then to say in the next section https://docs.nvidia.com/deeplearning/maxine/audio-effects-sdk/index.html#get-params-effect

4.4. Getting the Parameters of an Effect
… Before running an audio effect, the number of channels that are supported by the effect must be queried.

If querying values is mandatory, why would you first educate someone on setting values before educating them on how to query the values before setting them?
Why not just show them to query first, and then set everything?

I have perhaps the simplest hello-world C++ code in the world, but I seem to be unable to query simple values:

#include <iostream>
#include <nvAudioEffects.h>
int main()
{
    NvAFX_Handle handle = 0;
    NvAFX_Status result;

    //
    // Works fine...
    //
    result = NvAFX_CreateEffect(NVAFX_EFFECT_DENOISER, &handle);
    if (result != NVAFX_STATUS_SUCCESS)
    {
        std::cerr << "NvAFX_CreateEffect() failed" << std::endl;
        goto CLEANUP;
    }

    unsigned num_samples_per_frame, num_channels, sample_rate;
    result = NvAFX_GetU32(handle, NVAFX_PARAM_NUM_INPUT_SAMPLES_PER_FRAME, &num_samples_per_frame);
    result = NvAFX_GetU32(handle, NVAFX_PARAM_NUM_INPUT_CHANNELS, &num_channels);
    result = NvAFX_GetU32(handle, NVAFX_PARAM_OUTPUT_SAMPLE_RATE, &sample_rate);
    // results are all NVAFX_STATUS_SUCCESS

    std::cout << "NvAFX NvAFX_GetU32: num_samples_per_frame=" << num_samples_per_frame << std::endl;
    // num_samples_per_frame == 0, seems broken?

    std::cout << "NvAFX NvAFX_GetU32: num_channels=" << num_channels << std::endl;
    // num_channels == 1, seems OK
    
    std::cout << "NvAFX NvAFX_GetU32: sample_rate=" << sample_rate << std::endl;
    // sample_rate == 0, seems broken?

CLEANUP:
    if (handle != 0)
    {
        result = NvAFX_DestroyEffect(handle);
        if (result != NVAFX_STATUS_SUCCESS)
        {
            std::cerr << "NvAFX_DestroyEffect() failed" << std::endl;
        }
        handle = 0;
    }
    return result == NVAFX_STATUS_SUCCESS ? 0 : 1;
}

I cannot find where in the docs it mentions that this behavior of NvAFX_GetU32 is expected/normal, especially when the docs intimate that NvAFX_GetU32 should be called before NvAFX_SetU32.

I also find it odd that there is no NvAFX_GetU32List in the Windows nvAudioEffects.h, even though https://docs.nvidia.com/deeplearning/maxine/audio-effects-sdk/index.html#nvafx-getu32 says:

Note: For the Linux SDK, although NVAFX_PARAM_NUM_SAMPLES_PER_INPUT_FRAME can be queried by using this API to get the default number of samples per frame, you should use NvAFX_GetU32List() with the NVAFX_PARAM_SUPPORTED_NUM_SAMPLES_PER_FRAME parameter to get the list of supported values.

I also find it inconsistent that int parameters in most methods are unsigned int, but int parameters in NvAFX_Run are just unsigned (no int).
Is there a reason for this?

I don’t mean any of this to be harsh; just letting you know of some kinks.
The AFX SDK was last updated in April, and is probably due for a little more polish.

Thanks.

1 Like