Trace PRO Control API | Version 1.0 Last updated 06.12.2006
© 12/2006 MARIAN, reproduction, distribution, and publication through any media permitted with written authorization of MARIAN only.

Introduction.. 3

Common Initialization/Finalization.. 3

The Functions. 3

tpro_Init 3

tpro_Done.. 3

tpro_GetNumCards.. 3

Handling Parameter Values. 4

The Functions. 4

tpro_mx_GetValue.. 4

tpro_mx_GetValueEx. 4

tpro_mx_SetValue.. 5

tpro_mx_SetValueEx. 5

Mixer Control 6

Mixer Architecture. 6

Mixer Channel Control 6

Sum Channel Control 8

Output Control 8

Output Architecture. 8

Output Channel Control 8

Audio Level Analysis. 10

How it works. 10

The Functions. 10

Structure TPRO_CHNLEVELINFO... 10

tpro_RequestLevel 12

tpro_GetLevel 13

# Introduction

This documentation covers the software interface to the Trace PRO driver, which is useful for third party application software to control the Trace PRO audio signals. It includes:

· Analog Input Level Control

· Mixer Channel Control

· Sum Channel Control

· Output Volume Control

· Output Signal Routing

· Signal Level Analysis

The software interface is delivered by the 32-Bit Windows™ DLL file “tproifc.dll”. Thus, it makes it very easy to use it in any 32-Bit-Windows™ based application software. The documentation includes a C++ language header file (tproifc.h) which contains all function prototypes and other declarations like constants and structures. Additional, this documentation comes with the Trace PRO user manual which helps to understand how the Trace PRO is working and how the Trace PRO Manager software visualizes the cards functionality.

In the following, the Trace PRO Control API is called TPROIFC.

# Common Initialization/Finalization

The application software should first initialize the TPROIFC by use of the function tpro_Init. Multiple clients of the interface are supported via the same DLL module.

If the software application finishes the use of TPROIFC it must call tpro_Done.

It is essential for the client software to get the number of installed and active Trace PRO PCI cards via tpro_GetNumCards because the number of the card is a main identifier for many functions.

### The Functions

#### tpro_Init

BOOL TPROCALL tpro_Init();
// initializes usage of TPROIFC

#### tpro_Done

VOID TPROCALL tpro_Done();

// finalizes usage of TPROIFC

#### tpro_GetNumCards

LONG TPROCALL tpro_GetNumCards();

// returns the number of installed, active Trace PRO PCI cards

# Handling Parameter Values

Every mixer parameter and also every output parameter can be read and set by use of two functions:
tpro_mx_GetValue and tpro_mx_SetValue. Each parameter is uniquely identified by a set of ID’s – the Card ID, the Channel Type ID, the Channel ID and the Parameter ID. Some parameters require also a sub parameter ID. Use the functions tpro_mx_GetValueEx and tpro_mx_SetValueEx to access these parameters.

The Card ID is a simple number beginning from 0 to the number of installed cards – 1. The number of installed cards can be easily determined through the function tpro_GetNumCards. All other ID’s are explained in the following sections.

### The Functions

#### tpro_mx_GetValue

LONG TPROCALL tpro_mx_GetValue (

LONG crdid,

LONG typid,

LONG chnid,

LONG parid,

PLONG pValue

);

// Gets the current Value of a specific mixer parameter

// Input:

// crdid = Card Id

// typid = Channel Type Id (see tpro_typid defines)

// chnid = Channel Id (see tpro_chnid defines)

// parid = Parameter Id (see tpro_parid defines)

// pValue = Pointer to a LONG variable for the result

// Output:

// *pValue filled will the current parameter value

// return < 0 ? Error : Success

#### tpro_mx_GetValueEx

LONG TPROCALL tpro_mx_GetValueEx (

LONG crdid,

LONG typid,

LONG chnid,

LONG parid,

LONG sparid,

PLONG pValue

);

// Gets the current Value of a specific mixer parameter

// Input:

// crdid = Card Id

// typid = Channel Type Id (see tpro_typid defines)

// chnid = Channel Id (see tpro_chnid defines)

// parid = Parameter Id (see tpro_parid defines)

// sparid = Sub-Parameter Id (see tpro_sparid defines)

// pValue = Pointer to a LONG variable for the result

// Output:

// *pValue filled will the current parameter value

// return < 0 ? Error : Success

#### tpro_mx_SetValue

LONG TPROCALL tpro_mx_SetValue (

LONG crdid,

LONG typid,

LONG chnid,

LONG parid,

LONG Value

);

// Sets the Value of a specific mixer parameter

// Input:

// crdid = Card Id

// typid = Channel Type Id (see tpro_typid defines)

// chnid = Channel Id (see tpro_chnid defines)

// parid = Parameter Id (see tpro_parid defines)

// Value = New Value for the Parameter

// Output:

// return < 0 ? Error : Success

#### tpro_mx_SetValueEx

LONG TPROCALL tpro_mx_SetValueEx (

LONG crdid,

LONG typid,

LONG chnid,

LONG parid,

LONG sparid,

LONG Value

);

// Sets the Value of a specific mixer parameter

// Input:

// crdid = Card Id

// typid = Channel Type Id (see tpro_typid defines)

// chnid = Channel Id (see tpro_chnid defines)

// parid = Parameter Id (see tpro_parid defines)

// sparid = Sub-Parameter Id (see tpro_sparid defines)

// Value = New Value for the Parameter

// Output:

// return < 0 ? Error : Success

# Mixer Control

### Mixer Architecture

The Mixer of the Trace PRO consists of 20 mono channels.

The first four channels control the audio signals of the input channels of the card. The next eight channels of the mixer channels control the audio signals of the playback channels of the card. “Playback channels” does not mean output channels. It really means the playback signals which any audio application sends to the drivers software. And the last eight channels control the signals laying on TDM BUS and which are used here as mixer input channels.

Which audio signal can be heard at a output depends on the Output Routing (see Output Control).

The signals of all mixer channels are mixed to eight individually sums – AUX1 … AUX6 and MASTER.

### Mixer Channel Control

Each mixer channel is identified by an ID for its type as mixer channel and an individual channel ID.

Type ID (tpro_typid) | Channel ID (tpro_chnid) | Trace PRO Device
0 | 0 | Analog Input 1
0 | 1 | Analog Input 2
0 | 2 | Digital Input L
0 | 3 | Digital Input R
0 | 4 | Play 1
0 | 5 | Play 2
0 | 6 | Play 3
0 | 7 | Play 4
0 | 8 | Play 5
0 | 9 | Play 6
0 | 10 | Play 7
0 | 11 | Play 8
0 | 12 | TDM 1
0 | 13 | TDM 2
0 | 14 | TDM 3
0 | 15 | TDM 4
0 | 16 | TDM 5
0 | 17 | TDM 6
0 | 18 | TDM 7
0 | 19 | TDM 8

See the appropriate type ID’s (tpro_typid_xxx) and channels ID’s (tpro_chnid_xxx) also in the tproifc.h.

Each mixer channel has a number of parameters. The following table shows these parameter.

Parameter ID (tpro_parid) | Name | Value Range | Remarks
0 | Source Select | Value | Source | Digital Input Channel Only: Determines the physical audio connector for the channel.
0 | XLR Input
1 | CD Input
8 | Gain Range | Value | Level == 0dBfs | For Analog Input Channels Only. Determines which analog level causes 0 dbfs on the digital side. Influences the recording level too.
0 | -6 dBv
1 | +8 dBu
2 | +15 dBu
3 | +18 dBu
9 | Analog Gain | 0..0x0A400 == -INF ..+18 dB | For Analog Input Channels Only. Influences the recording level too
1 | Digital Gain | 0..0x10000 == -INF ..+6 dB | Signal Level Adjustment. Analog Input: Influences the recording level too.
2 | AUX Volume | 0..0x10000 == -INF ..+6 dB | Signal level for mix at AUX N. This parameter needs a sub parameter which specifies the AUX number
3 | AUX Pre Fader | 1 || 0 == on || off | Determines whether or not the channel signal is mixed to the AUX N Bus pre (on) or post (off) the fader section. This parameter needs a sub parameter which specifies the AUX number
4 | Mute | 1 || 0 == on || off | Mutes (On) the channel signal at the AUX and Master Busses.
5 | Solo | 1 || 0 == on || off | Set the channel signal at the Master Sum to Solo (On).
6 | Master PAN | Value | Left | Right | Determines the signal level of the channel at the left and right channel of the Master sum.
0 | +6 dB | -INF
0x08000 | 0 dB | 0 dB
0x10000 | -INF | +6 dB
7 | Master Volume | 0..0x10000 == -INF ..+6 dB | Signal level for the mix at the Master Sum

Generally, all the values for dB ranges are like PCM sample values. The maximum value is +6 dB. Every “shift right” operation of the parameter value decreases the dB value by 6 dB. Thus, the following conversion routines apply:

Parameter Value to dB Value:

dBValue = Log2 (ParamValue/0x10000)*6 + 6;

dB Value to Parameter Value:

ParamValue = Round (Power (2, (dBValue-(-90))/6));

The Analog Gain Inputs is set directly in the AD converter. Thus, another value to dB conversion applies. Only the bits D8..D15 are significant. Please see the conversion table in the file ek4620a.pdf page 33. Additional, when the gain of the analog inputs is manipulated, this also influences the analog recording level, not only the mixer input level.

### Sum Channel Control

Each Sum channel is identified by an ID for its type as sum channel and an individual sum channel ID.

Type ID (tpro_typid) | Channel ID (tpro_chnid) | Sum Channel
1 | 0 | Master Left
1 | 1 | Master Right
1 | 2 | Aux 1
1 | 3 | Aux 2
1 | 4 | Aux 3
1 | 5 | Aux 4
1 | 6 | Aux 5
1 | 7 | Aux 6

See the appropriate type ID’s (tpro_typid_xxx) and channels ID’s (tpro_chnid_xxx) also in the tproifc.h.

Each sum channel has a parameter for the level adjustment of the audio mix. The following table shows this parameter and it’s value range.

Parameter ID (tpro_parid) | Name | Value Range | Remarks
0 | Volume | 0..0x8000 == -INF .. 0 dB | Sets the audio mix level for sum channel.

The conversion from dB value to parameter value and back should proceed like described in “Mixer Channel Control”.

# Output Control

### Output Architecture

The main task of the output control is the output signal routing and the control of the output signal level. Each channel of the output control is assigned to a physical output of the Trace PRO.

### Output Channel Control

Each output stereo channel is identified by an ID for its type as output channel and an individual channel ID.

Type ID (tpro_typid) | Channel ID (tpro_chnid) | Trace PRO Device
2 | 0 | Analog Output 1-2
2 | 1 | Digital Output
2 | 2 | TDM Bus Output 1-2
2 | 3 | TDM Bus Output 3-4
2 | 4 | TDM Bus Output 5-6
2 | 5 | TDM Bus Output 7-8

See the appropriate type ID’s (tpro_typid_xxx) and channels ID’s (tpro_chnid_xxx) also in the tproifc.h.

Each output channel has a number of parameters, shown in this table.

Parameter ID (tpro_parid) | Name | Value Range | Remarks
0 | Source Select | Value | Source | Determines the source signal which should be used for the output. Any of the available signals can be used – input, playback or sum signals
0 | Play 1-2
1 | Play 3-4
2 | Play 5-6
3 | Play 7-8
4 | Play 9-10
5 | Play 11-12
6 | Play 13-14
7 | Play 15-16
8 | Analog Input
9 | Digital Input
12 | TDM 1-2
13 | TDM 3-4
14 | TDM 5-6
15 | TDM 7-8
16 | Master Sum
17 | Aux 1-2
18 | Aux 3-4
19 | Aux 5-6
1 | Mute | 1 || 0 == On || Off | Mutes the Output (on)
2 | Volume Left | 0..0x8000 == -INF .. 0 dB | Controls output level left channel
3 | Volume Right | 0..0x8000 == -INF .. 0 dB | Controls output level right channel
4 | TDM On Bus | 1 || 0 == On || Off | For TDM Output Channels only: Switches the signal on the Bus or not
5 | Level Range | Value | Output Level @ 0 dbfs | For Analog Output channels Only: determines the analog level when having a digital level of 0 dbfs
0 | -6 dBv
1 | +8 dBu
2 | +18 dBu
6 | Format | 1 || 0 == Non-Audio || Audio | For Digital Output Channels Only: Sets the according AES3 channel state

The conversion from dB value to parameter value and back should proceed like described in “Mixer Channel Control”.

# Audio Level Analysis

The Trace PRO hardware analyzes the level of every audio signal available. Thus, any client software is able to get the results of the level analysis for its own purposes – mainly for the implementation of level meters.

### How it works

The Trace PRO hardware stores level values in a special part of the card memory. But before a level value is stored, the hardware compares it with the previous stored value which is only overwritten, if the new value is higher than the older. The stored value is reset to zero, if the driver software reads the value from the hardware. This way, the driver software always gets the maximum level which occurred between two read operations.

The driver software does the same for registered client software. It reads the level value from the hardware compares it with the last stored, client related level value and stores it only, if the client level value is less than the new level value. The client related level value is reset to zero, if the client software read its level value.

In this manner the hardware works with every sample, the driver does it approximately every 1 ms and it is up to the client software to get the level value in intervals which are appropriate for the clients purpose.

The implementation of a level meter can be done very easily. The client software could have 2 processes. The first process gets the level and displays it only if the actual displayed level display is less than the new value. The second process simply decreases the level display by a determined dB value in a determined time.

### The Functions

#### Structure TPRO_CHNLEVELINFO

typedef struct {

LONG Pre; // Source Level Pre Gain

LONG Post; // Level measured after Gain/Pan/Volume/Mute

BOOL AdOvl; // AD Channels only: AD signaled an Input Overload

BOOL ParChanged; // Any of channel parameters has changed - read
parameter values again

LONG Code; // Channel specific Error Code of last Get/Request Operation

LONG Requests; // Number of clients who need the level info of this channel

ULONG Handle; // Driver spec. Handle, do not use

ULONG hDev; // Driver spec. Handle, do not use

} TPRO_CHNLEVELINFO, *PTPRO_CHNLEVELINFO;

typedef struct {

LONG CardId; // IN: ID of target card

LONG reserved;

TPRO_CHNLEVELINFO Levels[TPRO_NUMCHANNELS]; // LevelInfo for each Mono signal available; indexes see: tpro_lvi_XXX constants

} TPRO_LEVELINFO, *PTPRO_LEVELINFO;

The structure TPRO_LEVELINFO with its array of TPRO_CHNLEVELINFO is used to request and get the level values for the different mono channels. For each mono channel a TPRO_CHNLEVELINFO structure is assigned in the Levels array of TPRO_LEVELINFO. Please see the array indexes in the following table and the “tproifc.h”.

Index | Channel
0 | Analog Input 1
1 | Analog Input 2
2 | Digital Input L
3 | Digital Input R
4 | Play 1
5 | Play 2
6 | Play 3
7 | Play 4
8 | Play 5
9 | Play 6
10 | Play 7
11 | Play 8
12 | Tdm 1
13 | Tdm 2
14 | Tdm 3
15 | Tdm 4
16 | Tdm 5
17 | Tdm 6
18 | Tdm 7
19 | Tdm 8
20 | Play 9
21 | Play 10
22 | Play 11
23 | Play 12
24 | Play 13
25 | Play 14
26 | Play 15
27 | Play 16
28 | Master Sum L
29 | Master Sum R
30 | Aux 1
31 | Aux 2
32 | Aux 3
33 | Aux 4
34 | Aux 5
35 | Aux 6

#### tpro_RequestLevel

LONG TPROCALL tpro_RequestLevel (PTPRO_LEVELINFO pLevelInfo);

// Switchs Level Anaysis for specific stereo channels on/off

// Input:

// pLevelInfo = pointer to level information structure

// pLevelInfo->CardId = ID of target card

// pLevelInfo->Levels[].Requests = initialized with >0 if Level required

// Output:

// pLevelInfo->Levels[].Code = Error Code for Request

// pLevelInfo->Levels[].Handle = Driver specific handle for client channel

// return < 0 ? Error : Success

This function switches the level analysis for specific stereo channels on and off. The driver software uses the information in pLevelInfo->Levels[].Requests for the level analysis state of the channel.

The client software can check the success of the operation for each channel by use of pLevelInfo->Levels[].Code. A value less than 0 indicates that the request could not be executed. This may occur with the Digital/TDM input channel only because of inappropriate clock settings (see users manual).

Example: The client software request the levels for the AES/EBU Input and any of the TDM inputs. With the default clock settings the driver assumes that both digital input clocks are not synchronized. Since the Trace PRO always works with one clock only, the signal of the AES/EBU input can be evaluated by using the clock of this input as reference. In this case, the TDM input clock can not be evaluated.

The client software should also observe the information in pLevelInfo->Levels[].Code after calling tpro_G etLevel because it may change because of recording/playback requests from audio recording applications. Read more about this in tprotpro_GetLevel.

The client software must use always the identical TPRO_LEVELINFO variable for tpro_Re questLevel and tpro_GetLevel calls because the driver writes client related information into this structure.

The client software must deactivate the level analysis for all channels before it exits.

#### tpro_GetLevel

LONG TPROCALL tpro_GetLevel (PTPRO_LEVELINFO pLevelInfo);

// Get the Levels for all requested MONO channels

// Input:

// pLevelInfo = pointer to level information structure,

// pLevelInfo->CardId = ID of target card

// Output:

// pLevelInfo->Levels[].Code = Error Code for Get
( < 0 ? Error : Success)

// pLevelInfo->Levels[].Pre = Level of the Source Signal
(PRE Gain/Fader)

// pLevelInfo->Levels[].Post = Level of the Signal after Gain, Pan, Fader, Mute

// pLevelInfo->Levels[].AdOvl = if TRUE then the AD Converter signaled an Input Overload

// pLevelInfo->Levels[].ParChanged = if TRUE then any parameter of the channel has changed

// return < 0 ? Error : Success

Using this function, the client software can get the levels of the different channels. The client software gets the level peak values that occurred between this and the previous call. A call of tpro_G etLevel reset the driver stored peak value to zero.

Before the first call of tpro_G etLevel, the TPRO_LEVELINFO variable must be initialized with tpro_R equestLevel.

The level value in Pre, Pos t of the TPRO_CHNLEVEKINFO structure is expressed like a PCM sample value. A conversion to a dB value can be done in the same way like the parameter values are converted (see Mixer Channel Control).

The following table contains the value ranges of the level values.

pLevelInfo->Levels[].Pre | 0..0x08000 == -INF .. 0 dB
pLevelInfo->Levels[].Post | 0..0x08000 == -INF .. +6 dB

The level value in Pre of the TPRO_CHNLEVELINFO structure always represent the level of the source signal. That means for

· Analog Input Channels the level after the gain control

· All other Mixer Channels the level prior the gain control

· Sum Channels the level prior the fader

The level value in Post of the TPRO_HNLEVELINFO structure always represent the level post fader. This way it is very easy for the client software to implement a switchable “pre fader metering”.

The client software should use pLevelInfo->Levels[].Code to evaluate to validity of the level values. This code can contain an error state for that channel even if tpro_RequestLevel not returned an error. This can be the case for the AES/EBU and TDM input channels only.

Example: Like mentioned, the Trace PRO works always with one reference clock only, means also with one sample rate only. If a client software requests a level information for the AES/EBU input with sample rate converters switched off, the driver uses the clock of this input. Imagine the AES/EBU input runs at 44.1 kHz and a recording software requests a recording from the analog input at 48 kHz. Since recording and playback have always the higher priority towards level analysis, the driver, according its default clock settings, would switch to the internal clock and would set it to 48 kHz. In this case, the level of the digital input could not be evaluated and the pLevelInfo->Levels[].Code would signal an error. After the recording has finished, the driver looks at the level request table and ensures the right clock settings for the requested levels. The pLevelInfo->Levels[].Code would signal no error again.