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_GetLevel 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_RequestLevel 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_GetLevel reset the driver stored peak value to zero.

Before the first call of tpro_GetLevel, the TPRO_LEVELINFO variable must be initialized with tpro_RequestLevel.

The level value in Pre, Post 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.