Application programmers interface (API)

This section describes the application programming interface (API) libraries of the SSRC module.

Type definitions

This section describes the type definitions of the SSRC module.

Types for allocation of instance and scratch memory

The instance memory is the memory that contains the state of one instance of the SSRC module. Multiple instances of the SSRC module can exist, each with it is own instance memory. S memory is the memory that is only used temporarily by the process function of the SSRC module. This memory can be used as scratch memory by any other function running in the same thread as the SSRC module. Different threads cannot share the scratch memories.

The application must allocate both the instance and the scratch memory. The SSRC module does not allocate memory.

There is a data type available for both the instance and the scratch memory, namely SSRC_Instance_t and SSRC_Scratch_t. The instance type is defined as structures of the correct size in the SSRC header file. Both the instance and the scratch memory must be 4 bytes aligned.

Parent topic:Type definitions

LVM_Fs_en

Definition:

typedef enum
{
    LVM_FS_8000    = 0,
    LVM_FS_11025   = 1,
    LVM_FS_12000   = 2,
    LVM_FS_16000   = 3,
    LVM_FS_22050   = 4,
    LVM_FS_24000   = 5,
    LVM_FS_32000   = 6,
    LVM_FS_44100   = 7,
    LVM_FS_48000   = 8
} LVM_Fs_en;

Description:

Used to pass the input and the output sample rate to the SSRC.

Parent topic:Type definitions

LVM_Format_en

Definition:

typedef enum
{
    LVM_STEREO          = 0,
    LVM_MONOINSTEREO    = 1,
    LVM_MONO            = 2
} LVM_Format_en;

Description:

The LVM_Format_en enumerated type is used to set the value of the SSRC data format.

The SSRC supports input data in two formats Mono and Stereo. For an input buffer of NumSamples = N (meaning N sample pairs for Stereo and MonoInStereo or N samples for Mono), the format of data in the buffer is as listed in Table 1:

Sample Number	Stereo	MonoInStereo	Mono
0	Left(0)	Mono(0)	Mono(0)
1	Right(0)	Mono(0)	Mono(1)
2	Left(1)	Mono(1)	Mono(2)
3	Right(1)	Mono(1)	Mono(3)
4	Left(2)	Mono(2)	Mono(4)
“	“	“	“
“	“	“	“
N-2	Left(N/2-1)	Mono(N/2-1)	Mono(N-2)
N-1	Right(N/2-1)	Mono(N/2-1)	Mono(N-1)
N	Left(N/2)	Mono(N/2)	Not Used
N+1	Right(N/2)	Mono(N/2)	Not Used
N+2	Left(N/2+1)	Mono(N/2+1)	Not Used
N+3	Right(N/2+1)	Mono(N/2+1)	Not Used
“	“	“	Not Used
“	“	“	Not Used
2*N-2	Left(N-1)	Mono(N-1)	Not Used

Parent topic:Type definitions

SSRC_Quality_en

Definition:

typedef enum
{
    SSRC_QUALITY_HIGH           = 0,
    SSRC_QUALITY_VERY_HIGH      = 1,
    SSRC_QUALITY_DUMMY          = LVM_MAXENUM
} SSRC_Quality_en;

Description:

Used to select the quality level of the SSRC. For details, see Performance figures. Selecting the highest-quality level, comes with a cost in the SSRC processing requirements. Therefore, it should only be done for critical applications.

Parent topic:Type definitions

Instance parameters

Definition:

typedef struct
{
    SSRC_Quality_en     Quality;
    LVM_Fs_en           SSRC_Fs_In;
    LVM_Fs_en           SSRC_Fs_Out;
    LVM_Format_en       SSRC_NrOfChannels;
    short               NrSamplesIn;
    short               NrSamplesOut;
} SSRC_Params_t;

Description:

Used to pass the SSRC instance parameters to the SSRC module. It is a structure that contains the members for input sample rate, output sample rate, the number of channels, and the number of samples on the input and output audio stream.

Parent topic:Type definitions

Nr of samples mode

Definition:

typedef enum
{
    SSRC_NR_SAMPLES_DEFAULT     = 0,
    SSRC_NR_SAMPLES_MIN         = 1,
    SSRC_NR_SAMPLES_DUMMY       = LVM_MAXENUM
} SSRC_NR_SAMPLES_MODE_en;

Description:

The SSRC_NR_SAMPLES_MODE_en enumerated type specifies the two different modes that can be used to retrieve the number of samples using the SSRC_GetNrSamples function.

Parent topic:Type definitions

Function return status

Definition:

typedef enum
{
    SSRC_OK                     = 0,
    SSRC_INVALID_FS             = 1,
    SSRC_INVALID_NR_CHANNELS    = 2,
    SSRC_NULL_POINTER           = 3,
    SSRC_WRONG_NR_SAMPLES       = 4,
    SSRC_ALLINGMENT_ERROR       = 5,
    SSRC_INVALID_MODE           = 6,
    SSRC_INVALID_VALUE          = 7,
    SSRC_ALLINGMENT_ERROR       = 8,
    LVXXX_RETURNSTATUS_DUMMY = LVM_MAXENUM
} SSRC_ReturnStatus_en;

Description:

The SSRC_ReturnStatus_en enumerated type specifies the different error codes returned by the API functions. For the exact meaning, see the individual function descriptions.

Parent topic:Type definitions

Parent topic:Application programmers interface (API)

Functions

This section lists all the API functions of the SSRC module and explains their parameters.

SSRC_GetNrSamples

Prototype:

SSRC_ReturnStatus_en SSRC_GetNrSamples
   (SSRC_NR_SAMPLES_MODE_en  Mode,
    SSRC_Params_t*           pSSRC_Params );

Description:

This function retrieves the number of samples or sample pairs for stereo used as an input and as an output of the SSRC module.

Name	Type	Description
Mode	SSRC_NR_SAMPLES_MODE_en	There are two modes: - `SSRC_NR_SAMPLES_DEFAULT`: In this mode, the function returns the number of samples for 40 ms blocks - `SSRC_NR_SAMPLES_MIN`: the function returns the minimal number of samples supported for this conversion ratio. The SSRC_Init function accepts each integer multiple of this ratio. Formula: `blocksize (ms) = 1/gcd(Fs_In,Fs_Out)`
pSSRC_Params	SSRC_Params_t*	Pointer to the instance parameters. The application fills in the values of the input sample rate, the output sample rate, and the number of channels. Based on this input, the `SSRC_GetNrSamples` fills in the values for the number of samples for the input and the output audio stream.

Returns:


`SSRC_OK`	When the function call succeeds.
`SSRC_INVALID_FS`	When the requested input or output sampling rates are invalid.
`SSRC_INVALID_NR_CHANNELS`	When the channel format is not equal to `LVM_MONO` or `LVM_STEREO`.
`SSRC_NULL_POINTER`	When `pSSRC_Params` is a `NULL` pointer.
`SSRC_INVALID_MODE`	When mode is not a valid setting.

Note: The SSRC_GetNrSamples function returns the values from the following tables. Instead of calling the SSRC_GetNrSamples function, use the values from these tables directly.

Sample rate	Nr of samples
8000	320
11025	441
12000	480
16000	640
22050	882
24000	960
32000	1280
44100	1764
48000	1920

In/Out	8000	11025	12000	16000	22050	24000	32000	44100	48000
8000	1 1	320 441	2 3	1 2	160 441	1 3	1 4	80 441	1 6
11025	441 320	1 1	147 160	441 640	1 2	147 320	441 1280	1 4	147 640
12000	3 2	160 147	1 1	3 4	80 147	1 2	3 8	40 147	1 4
16000	2 1	640 441	4 3	1 1	320 441	2 3	1 2	160 441	1 3
22050	441 160	2 1	147 80	441 320	1 1	147 160	441 640	1 2	147 320
24000	3 1	320 147	2 1	3 2	160 147	1 1	3 4	80 147	1 2
32000	4 1	1280 441	8 3	2 1	640 441	4 3	1 1	320 441	2 3
44100	441 80	4 1	147 40	441 160	2 1	147 80	441 320	1 1	147 160
48000	6 1	640 147	4 1	3 1	320 147	2 1	3 2	160 147	1 1

Parent topic:Functions

SSRC_GetScratchSize

Prototype:

SSRC_ReturnStatus_en SSRC_GetScratchSize
   (SSRC_Params_t*    pSSRC_Params,
    LVM_INT32*        pScratchSize );

Description:

This function retrieves the scratch size for a given conversion ratio and for given buffer sizes at the input and at the output.

Name	Type	Description
`pSSRC_Params`	`SSRC_Params_t*`	Pointer to the instance parameters. All members should have a valid value.
`pScratchSize`	`LVM_INT32*`	Pointer to the scratch size. The `SSRC_GetScratchSize` function fills in the correct value (in bytes).

|

Returns:


`SSRC_OK`	When the function call succeeds.
`SSRC_INVALID_FS`	When the requested input or output sampling rates are invalid.
`SSRC_INVALID_NR_CHANNELS`	When the channel format is not equal to `LVM_MONO` or `LVM_STEREO`.
`SSRC_NULL_POINTER`	When `pSSRC_Params` or `pScratchSize` is a `NULL` pointer.
`SSRC_WRONG_NR_SAMPLES`	When the number of samples on the input or on the output are incorrect.

Parent topic:Functions

SSRC_Init

Prototype:

SSRC_ReturnStatus_en SSRC_Init
   (SSRC_Instance_t* pSSRC_Instance,
    SSRC_Scratch_t*  pSSRC_Scratch,
    SSRC_Params_t*   pSSRC_Params,
    LVM_INT16**      ppInputInScratch,
    LVM_INT16**      ppOutputInScratch);

Description:

The SSRC_Init function initializes an instance of the SSRC module.

Name	Type	Description
`pSSRC_Instance`	`SSRC_Instance_t*`	Pointer to the instance of the SSRC. This application must allocate the memory before calling the `SSRC_Init` function.
`pSSRC_Scratch`	`SSRC_Scratch_t*`	Pointer to the scratch memory. The pointer is saved inside the instance and is used by the `SSRC_Process` function. The application must allocate the scratch memory before calling the `SSRC_Init` function.
`pSSRC_Params`	`SSRC_Params_t*`	Pointer to the instance parameters.
`ppInputInScratch`	`LVM_INT16**`	The SSRC module can be called with the input samples located in scratch. This pointer points to a location that holds the pointer to the location in the scratch memory that can be used to store the input samples. For example, to save memory.
`ppOutputInScratch`	`LVM_INT16**`	The SSRC module can store the output samples in the scratch memory. This pointer points to a location that holds the pointer to the location in the scratch memory that can be used to store the output samples. For example, to save memory.

Returns:


`SSRC_OK`	When the function call succeeds.
`SSRC_INVALID_FS`	When the requested input or output sampling rates are invalid.
`SSRC_INVALID_NR_CHANNELS`	When the channel format is not equal to `LVM_MONO` or `LVM_STEREO`.
`SSRC_NULL_POINTER`	When `pSSRC_Params` or `pScratchSize` is a `NULL` pointer.
`SSRC_WRONG_NR_SAMPLES`	When the number of samples on the input or on the output are incorrect.
`SSRC_ALIGNMENT_ERROR`	When the instance memory or the scratch memory is not 4 bytes aligned.

Parent topic:Functions

SSRC_SetGains

Prototype:

SSRC_ReturnStatus_en SSRC_SetGains
   (SSRC_Instance_t* pSSRC_Instance,
    LVM_Mode_en      bHeadroomGainEnabled,
    LVM_Mode_en      bOutputGainEnabled,
    LVM_INT16       OutputGain);

Description:

This function sets headroom gain and the post gain of the SSRC. The SSRC_SetGains function is an optional function that should be used only in rare cases. Preferably, use the default settings.

Name

Type

Description

pSSRC_Instance

SSRC_Instance_t*

Pointer to the instance of the SSRC.

bHeadroomGainEnabled

LVM_Mode_en

Parameter to enable or disable the headroom gain of the SSRC. The default value is LVM_MODE_ON. LVM_MODE_OFF can be used if it can be guaranteed that the input level is below - 6 in all cases (the default headroom is -6 dB).

bOutputGainEnabled

LVM_Mode_en

Parameter to enable or disable the output gain. The default value is LVM_MODE_ON.

OutputGain

LVM_INT16

The value of the output gain. The output gain is a linear gain value. 0x7FFF is equal to +6 dB and 0x0000 corresponds to -inf dB. By default, a 3 dB gain is applied (OutputGain = 23197), resulting in an overall gain of -3 dB (-6 dB headroom +3 dB output gain).

Unit	Q format	Data Range	Default value
Linear gain	Q1.14	[0;32767]	23197

Returns:


`SSRC_OK`	When the function call succeeds
`SSRC_NULL_POINTER`	When `pSSRC_Instance` is a NULL pointer
`SSRC_INVALID_MODE`	Wrong value used for the `bHeadroomGainEnabled` or the `OutputGainEnabled` parameters.
`SSRC_INVALID_VALUE`	When `OutputGain` is out of the range [0;32767].

Parent topic:Functions

SSRC_Process

Prototype:

SSRC_ReturnStatus_en SSRC_Process
   (SSRC_Instance_t* pSSRC_Instance,
    LVM_INT16*       pSSRC_AudioIn,
    LVM_INT16*       pSSRC_AudioOut);

Description:

Process function for the SSRC module. The function takes pointers as input and output audio buffers.

The sample format used for the input and output buffers is 16-bit little-endian. Stereo buffers are interleaved (L1, R1, L2, R2, and so on), mono buffers are deinterleaved (L1, L2, and so on).

Name	Type	Description
`pSSRC_Instance`	`SSRC_Instance_t*`	Pointer to the instance of the SSRC.
`pSSRC_AudioIn`	`LVM_INT16*`	Pointer to the input samples.
`pSSRC_AudioOut`	`LVM_INT16*`	Pointer to the output samples.

Returns:


`SSRC_OK`	When the function call succeeds.
`SSRC_NULL_POINTER`	When one of `pSSRC_Instance`, `pSSRC_AudioIn`, or `pSSRC_AudioOut` is `NULL`.

Parent topic:Functions

SSRC_Process_D32

Prototype:

SSRC_ReturnStatus_en SSRC_Process_D32
   (SSRC_Instance_t* pSSRC_Instance,
    LVM_INT32*       pSSRC_AudioIn,
    LVM_INT32*       pSSRC_AudioOut);

Description:

Process function for the SSRC module. The function takes pointers as input and output audio buffers.

The sample format used for the input and output buffers is 32-bit little-endian. Stereo buffers are interleaved (L1, R1, L2, R2, and so on), mono buffers are deinterleaved (L1, L2, and so on).

Name	Type	Description
`pSSRC_Instance`	`SSRC_Instance_t*`	Pointer to the instance of the SSRC.
`pSSRC_AudioIn`	`LVM_INT32*`	Pointer to the input samples.
`pSSRC_AudioOut`	`LVM_INT32*`	Pointer to the output samples.