CTR-VCT  2.0.2
VoiceChat Libraries
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
vct.h File Reference

Go to the source code of this file.

Structures

struct  VCTAudioInfo
 Stores information related to audio. More...
 
struct  VCTSession
 Defines the structure for a session. Used for managing CIDs and the session state. More...
 
struct  VCTConfig
 Stores initialization parameters for the VCT library. More...
 

Macros

#define VCT_ERROR_NONE   0
 
#define VCT_ERROR_BAD_PARAM   -1
 
#define VCT_ERROR_BAD_MODE   -2
 
#define VCT_ERROR_BAD_REQUEST   -3
 
#define VCT_ERROR_SEND_FAIL   -4
 
#define VCT_ERROR_EXHAUST_CLIENTS   -6
 
#define VCT_MAX_SESSION   16
 
#define VCT_MAX_CONFERENCE_CLIENT   16
 
#define VCT_MAX_CLIENT   16
 
#define VCT_MAX_AUDIO_STREAM   (VCT_MAX_CONFERENCE_CLIENT - 1)
 
#define VCT_MAGIC_PACKET_HEADER   0x5f564354
 Magic number in the VCT packet header. More...
 
#define VCT_CODEC_DEFAULT   VCT_CODEC_4BIT_ADPCM
 Default audio codec. More...
 
#define VCT_SPARE_CODEC_DEFAULT   VCT_CODEC_2BIT_ADPCM
 Default audio codec for spare packets. More...
 
#define VCT_AUDIO_FRAME_LENGTH_MIN   64
 Specifies the minimum audio frame length (in milliseconds). More...
 
#define VCT_AUDIO_FRAME_LENGTH_MAX   192
 Specifies the maximum audio frame length (in milliseconds). More...
 
#define VCT_AUDIO_FRAME_LENGTH_DEFAULT   144
 Specifies the default audio frame length (in milliseconds). More...
 
#define VCT_AUDIO_DATA_SIZE_PER_MILLI_SEC   16
 
#define VCT_AUDIO_DATA_SIZE_MIN   (VCT_AUDIO_FRAME_LENGTH_MIN * VCT_AUDIO_DATA_SIZE_PER_MILLI_SEC)
 
#define VCT_AUDIO_DATA_SIZE_MAX   (VCT_AUDIO_FRAME_LENGTH_MAX * VCT_AUDIO_DATA_SIZE_PER_MILLI_SEC)
 
#define VCT_AUDIO_DATA_SIZE_DEFAULT   (VCT_AUDIO_FRAME_LENGTH_DEFAULT * VCT_AUDIO_DATA_SIZE_PER_MILLI_SEC)
 
#define VCT_AUDIO_FRAME_RATE   8000
 Audio frame rate (8 kHz). More...
 
#define VCT_AUDIO_HEADER_SIZE   12
 Header size for VCT audio data packets. More...
 
#define VCT_AUDIO_2_BIT_ADPCM_PACKET_SIZE_MAX   (VCT_AUDIO_HEADER_SIZE + 2 * VCT_AUDIO_FRAME_LENGTH_MAX + 4)
 
#define VCT_AUDIO_3_BIT_ADPCM_PACKET_SIZE_MAX   (VCT_AUDIO_HEADER_SIZE + 3 * VCT_AUDIO_FRAME_LENGTH_MAX + 4)
 
#define VCT_AUDIO_4_BIT_ADPCM_PACKET_SIZE_MAX   (VCT_AUDIO_HEADER_SIZE + 4 * VCT_AUDIO_FRAME_LENGTH_MAX + 4)
 
#define VCT_AUDIO_SPARE_PACKET_SIZE_MAX   VCT_AUDIO_2_BIT_ADPCM_PACKET_SIZE_MAX
 
#define VCT_AUDIO_PACKET_BUFFER_SIZE   (VCT_AUDIO_DATA_SIZE_MAX + VCT_AUDIO_SPARE_PACKET_SIZE_MAX)
 
#define VCT_AUDIO_BUFFER_PACKET_HEADER   56
 
#define VCT_AUDIO_BUFFER_SIZE   (VCT_AUDIO_PACKET_BUFFER_SIZE + VCT_AUDIO_BUFFER_PACKET_HEADER)
 
#define VCT_DEFAULT_AUDIO_BUFFER_COUNT   8
 
#define VCT_MIN_AUDIO_BUFFER_COUNT   4
 
#define VCT_MAX_AUDIO_BUFFER_COUNT   (24 * VCT_MAX_AUDIO_STREAM)
 
#define VCT_DEFAULT_AUDIO_BUFFER_SIZE
 
#define VCT_VAD_DETECT_GAIN_UP_DEFAULT   350
 
#define VCT_VAD_LOST_GAIN_UP_DEFAULT   280
 
#define VCT_VAD_INVALID_SCALE_THRESHOLD_DEFAULT   (7 * 7)
 
#define VCT_VAD_CLAMP_GAIN_MAX   0x3FFFFFFF
 
#define VCT_VAD_RELEASE_TIME_DEFAULT   5
 
#define VCT_CONFIG_FLAG_NONE   0x00
 
#define VCT_CONFIG_FLAG_VAD   0x01
 VAD (Voice Activity Detection) feature. More...
 
#define VCT_CONFIG_FLAG_ECHO_CANCEL   0x02
 Echo cancellation. More...
 
#define VCT_CONFIG_FLAG_HPF   0x04
 High-pass filter. More...
 
#define VCT_CONFIG_FLAG_SPARE_PACKET   0x08
 Spare packet. More...
 
#define VCT_CONFIG_FLAG_DROP_RECOVER   0x20
 Drop recovery. More...
 
#define VCT_CONFIG_FLAG_BPF   0x40
 Biquad filter. More...
 
#define VCT_CONFIG_FLAG_ALL   0xff
 
#define VCT_CONFIG_FLAG_DEFAULT
 

Typedefs

typedef struct VCTSession_ VCTSession
 
typedef void(* VCTEventCallback )(u16 cid, VCTEvent result, VCTSession *session, void *param)
 Defines the type for an event callback. More...
 
typedef bool(* VCTSendCallback )(u16 cid, const void *buff, u32 size, bool isReliable)
 Defines the type for a send callback. More...
 

Enumerations

enum  VCTMode {
  VCT_MODE_NULL,
  VCT_MODE_CONFERENCE
}
 
enum  VCTState {
  VCT_STATE_INIT,
  VCT_STATE_TALKING
}
 Enumerates session states. More...
 
enum  VCTEvent {
  VCT_EVENT_NONE,
  VCT_EVENT_CONNECTED,
  VCT_EVENT_DISCONNECTED
}
 Enumerates voice chat library events. More...
 
enum  VCTCodec {
  VCT_CODEC_8BIT_RAW,
  VCT_CODEC_G711_ULAW,
  VCT_CODEC_2BIT_ADPCM,
  VCT_CODEC_3BIT_ADPCM,
  VCT_CODEC_4BIT_ADPCM,
  VCT_CODEC_END
}
 Enumerates audio codecs. More...
 
enum  VCTECMode {
  VCT_EC_STANDARD,
  VCT_EC_HIGHPERFORMANCE
}
 Enumerates echo cancellation modes. More...
 

Functions

bool VCT_DeleteSession (VCTSession *session)
 Deletes the specified session. More...
 
s32 VCT_AddConferenceClient (u16 cid)
 Adds a client to the conference. More...
 
s32 VCT_RemoveConferenceClient (u16 cid)
 Removes a client from the conference. More...
 
bool VCT_OnConferenceClient (u16 cid)
 Returns whether a client is in the conference. More...
 
Initialization and Finalization
bool VCT_Init (VCTConfig *config)
 This function initializes the VCT library. More...
 
bool VCT_IsInitialized (void)
 Checks whether the VCT library is finished being initialized. More...
 
void VCT_Cleanup (void)
 Finalizes the VCT library. More...
 
void VCT_Main (void)
 This function runs the main loop of the VCT library. More...
 
Per-frame Execution
bool VCT_HandleData (u16 cid, u8 *buffer, u32 size)
 Processes voice chat data. More...
 
Audio Streaming
bool VCT_StartStreaming (const VCTSession *session)
 Starts audio streaming. More...
 
void VCT_ClearStreaming (const VCTSession *session)
 Clears audio streaming. More...
 
void VCT_StopStreaming (const VCTSession *session)
 Stops audio streaming. More...
 
bool VCT_SendAudioEx (const void *audio_data, u32 micScale, u32 micOffset)
 Queues audio data in the send queue. More...
 
bool VCT_ReceiveAudio (void *audio_data, u32 length, u16 outCIDList[])
 Extracts audio data from the receive buffer. More...
 
bool VCT_SetCodec (VCTCodec codec)
 Sets the audio codec. More...
 
VCTCodec VCT_GetCodec (void)
 Gets the currently configured audio codec. More...
 
bool VCT_IsValidCodec (VCTCodec codec)
 Determines whether the main packet audio codec type specified by codec is usable. More...
 
bool VCT_SetAudioFrameLength (u32 frameLength)
 Sets the audio frame length. More...
 
u32 VCT_GetAudioFrameLength (void)
 Gets the currently configured audio frame length. More...
 
u32 VCT_GetAudioDataSize (void)
 Gets the packet size of audio data. More...
 
u32 VCT_GetAudioScale (const void *audio, u32 length)
 Gets the calculated audio scale (square of the average power) of the input audio data. More...
 
void VCT_GetAudioInfoFromCid (u16 cid, VCTAudioInfo *info)
 Gets audio streaming information for the party specified by cid. More...
 
Noise Skipping
void VCT_SetNoiseSkipTime (u32 count)
 Sets the length of time for which sound is not sent in VCT_SignalNoiseSkip. More...
 
u32 VCT_GetNoiseSkipTime (void)
 Returns the length of time for which sound is not sent in VCT_SignalNoiseSkip. More...
 
void VCT_SignalNoiseSkip (void)
 When VAD is enabled and not active, this function makes VAD active on the sound of button presses so that audio is not sent. More...
 
Spare Packets
void VCT_EnableSparePacket (bool flag)
 This function enables and disables the spare packet feature. More...
 
bool VCT_IsEnableSparePacket (void)
 This function gets whether the spare packet feature is enabled or disabled. More...
 
bool VCT_SetSpareCodec (VCTCodec spareCodec)
 Sets the audio codec for spare packets. More...
 
VCTCodec VCT_GetSpareCodec (void)
 Gets the currently configured audio codec for spare packets. More...
 
bool VCT_IsValidSpareCodec (VCTCodec codec)
 Determines whether you can use the codec type specified by codec as a spare-packet codec type. More...
 
VAD
void VCT_EnableVAD (bool flag)
 Enables or disables the VAD feature. More...
 
bool VCT_IsEnableVAD (void)
 Gets whether the VAD feature is enabled. More...
 
bool VCT_GetVADActivity (void)
 VAD Gets the audio detection results from the VAD algorithm. More...
 
void VCT_ResetVAD (void)
 Resets the internal VAD status. More...
 
void VCT_SetVADActiveGain (u16 value)
 Sets the speech frame detection threshold. More...
 
u16 VCT_GetVADActiveGain (void)
 Gets the current speech frame detection threshold. More...
 
void VCT_SetVADInactiveGain (u16 value)
 Sets the silent frame detection threshold. More...
 
u16 VCT_GetVADInactiveGain (void)
 Gets the current silent frame detection threshold. More...
 
void VCT_SetVADReleaseTime (u32 count)
 Sets the time that must elapse after silence is detected before packet transmission is stopped. More...
 
u32 VCT_GetVADReleaseTime (void)
 Gets the time that must elapse after silence is detected before packet transmission is stopped. More...
 
void VCT_SetVADClampGain (u32 value)
 Sets the volume threshold as a volume scale value (the square of the average power) for unconditionally determining silence. More...
 
u32 VCT_GetVADClampGain (void)
 Gets the volume threshold as a volume scale value for unconditionally determining silence. More...
 
Echo Canceler
void VCT_HandleReference (const u8 *buffer, u32 size)
 Supplies reference data for the echo canceler. More...
 

Macro Definition Documentation

#define VCT_AUDIO_2_BIT_ADPCM_PACKET_SIZE_MAX   (VCT_AUDIO_HEADER_SIZE + 2 * VCT_AUDIO_FRAME_LENGTH_MAX + 4)
#define VCT_AUDIO_3_BIT_ADPCM_PACKET_SIZE_MAX   (VCT_AUDIO_HEADER_SIZE + 3 * VCT_AUDIO_FRAME_LENGTH_MAX + 4)
#define VCT_AUDIO_4_BIT_ADPCM_PACKET_SIZE_MAX   (VCT_AUDIO_HEADER_SIZE + 4 * VCT_AUDIO_FRAME_LENGTH_MAX + 4)
#define VCT_AUDIO_BUFFER_PACKET_HEADER   56
#define VCT_AUDIO_BUFFER_SIZE   (VCT_AUDIO_PACKET_BUFFER_SIZE + VCT_AUDIO_BUFFER_PACKET_HEADER)
#define VCT_AUDIO_DATA_SIZE_DEFAULT   (VCT_AUDIO_FRAME_LENGTH_DEFAULT * VCT_AUDIO_DATA_SIZE_PER_MILLI_SEC)
#define VCT_AUDIO_DATA_SIZE_MAX   (VCT_AUDIO_FRAME_LENGTH_MAX * VCT_AUDIO_DATA_SIZE_PER_MILLI_SEC)
#define VCT_AUDIO_DATA_SIZE_MIN   (VCT_AUDIO_FRAME_LENGTH_MIN * VCT_AUDIO_DATA_SIZE_PER_MILLI_SEC)
#define VCT_AUDIO_DATA_SIZE_PER_MILLI_SEC   16
#define VCT_AUDIO_FRAME_LENGTH_DEFAULT   144

Specifies the default audio frame length (in milliseconds).

#define VCT_AUDIO_FRAME_LENGTH_MAX   192

Specifies the maximum audio frame length (in milliseconds).

#define VCT_AUDIO_FRAME_LENGTH_MIN   64

Specifies the minimum audio frame length (in milliseconds).

#define VCT_AUDIO_FRAME_RATE   8000

Audio frame rate (8 kHz).

#define VCT_AUDIO_HEADER_SIZE   12

Header size for VCT audio data packets.

#define VCT_AUDIO_PACKET_BUFFER_SIZE   (VCT_AUDIO_DATA_SIZE_MAX + VCT_AUDIO_SPARE_PACKET_SIZE_MAX)
#define VCT_AUDIO_SPARE_PACKET_SIZE_MAX   VCT_AUDIO_2_BIT_ADPCM_PACKET_SIZE_MAX
#define VCT_CODEC_DEFAULT   VCT_CODEC_4BIT_ADPCM

Default audio codec.

#define VCT_CONFIG_FLAG_ALL   0xff
#define VCT_CONFIG_FLAG_BPF   0x40

Biquad filter.

#define VCT_CONFIG_FLAG_DEFAULT
Value:
VCT_CONFIG_FLAG_ECHO_CANCEL | \
VCT_CONFIG_FLAG_SPARE_PACKET | \
VCT_CONFIG_FLAG_DROP_RECOVER)
#define VCT_CONFIG_FLAG_DROP_RECOVER   0x20

Drop recovery.

#define VCT_CONFIG_FLAG_ECHO_CANCEL   0x02

Echo cancellation.

#define VCT_CONFIG_FLAG_HPF   0x04

High-pass filter.

#define VCT_CONFIG_FLAG_NONE   0x00
#define VCT_CONFIG_FLAG_SPARE_PACKET   0x08

Spare packet.

#define VCT_CONFIG_FLAG_VAD   0x01

VAD (Voice Activity Detection) feature.

#define VCT_DEFAULT_AUDIO_BUFFER_COUNT   8
#define VCT_DEFAULT_AUDIO_BUFFER_SIZE
#define VCT_ERROR_BAD_MODE   -2
#define VCT_ERROR_BAD_PARAM   -1
#define VCT_ERROR_BAD_REQUEST   -3
#define VCT_ERROR_EXHAUST_CLIENTS   -6
#define VCT_ERROR_NONE   0
#define VCT_ERROR_SEND_FAIL   -4
#define VCT_MAGIC_PACKET_HEADER   0x5f564354

Magic number in the VCT packet header.

#define VCT_MAX_AUDIO_BUFFER_COUNT   (24 * VCT_MAX_AUDIO_STREAM)
#define VCT_MAX_AUDIO_STREAM   (VCT_MAX_CONFERENCE_CLIENT - 1)
#define VCT_MAX_CLIENT   16
#define VCT_MAX_CONFERENCE_CLIENT   16
#define VCT_MAX_SESSION   16
#define VCT_MIN_AUDIO_BUFFER_COUNT   4
#define VCT_SPARE_CODEC_DEFAULT   VCT_CODEC_2BIT_ADPCM

Default audio codec for spare packets.

#define VCT_VAD_CLAMP_GAIN_MAX   0x3FFFFFFF
#define VCT_VAD_DETECT_GAIN_UP_DEFAULT   350
#define VCT_VAD_INVALID_SCALE_THRESHOLD_DEFAULT   (7 * 7)
#define VCT_VAD_LOST_GAIN_UP_DEFAULT   280
#define VCT_VAD_RELEASE_TIME_DEFAULT   5

Typedef Documentation

typedef void(* VCTEventCallback)(u16 cid, VCTEvent result, VCTSession *session, void *param)

Defines the type for an event callback.

See Also
VCTConfig, VCTSendCallback
typedef bool(* VCTSendCallback)(u16 cid, const void *buff, u32 size, bool isReliable)

Defines the type for a send callback.

See Also
VCTConfig, VCTEventCallback
typedef struct VCTSession_ VCTSession

Enumeration Type Documentation

enum VCTCodec

Enumerates audio codecs.

Enumerator
VCT_CODEC_8BIT_RAW 

Specifies 8-bit 8 kHz raw audio.

VCT_CODEC_G711_ULAW 

Specifies G711 u-Law.

VCT_CODEC_2BIT_ADPCM 

Specifies 2-bit IMA-ADPCM (non-standard).

VCT_CODEC_3BIT_ADPCM 

Specifies 3-bit IMA-ADPCM.

VCT_CODEC_4BIT_ADPCM 

Specifies 4-bit IMA-ADPCM.

VCT_CODEC_END 
enum VCTECMode

Enumerates echo cancellation modes.

Enumerator
VCT_EC_STANDARD 

Specifies standard echo cancellation.

VCT_EC_HIGHPERFORMANCE 

Specifies high-performance echo cancellation (only available in debug mode).

enum VCTEvent

Enumerates voice chat library events.

Enumerator
VCT_EVENT_NONE 
VCT_EVENT_CONNECTED 

Connected to the remote client.

VCT_EVENT_DISCONNECTED 

Disconnected.

enum VCTMode
Enumerator
VCT_MODE_NULL 
VCT_MODE_CONFERENCE 

Conference mode.

enum VCTState

Enumerates session states.

Enumerator
VCT_STATE_INIT 

Specifies an initialized state.

VCT_STATE_TALKING 

Specifies that the peers are talking.

Function Documentation

s32 VCT_AddConferenceClient ( u16  cid)

Adds a client to the conference.

One's own connection ID does not need to be specified. (It is ignored internally by the function even if it is specified.) To start a conference, this function must be called by all parties for each other. For example, for three systems with the connection IDs 1, 2, and 3 to start a conference, system 1 must add 2 and 3, system 2 must add 1 and 3, and system 3 must add 1 and 2.

If N is the maximum number of people who can connect in a conference, the maximum number of clients that the local system can add to a conference is N - 1. Before adding clients you must use the VCT_Init function to specify x number of VCTSession structures, where x = (total number of participants - 1). If there are not enough sessions, the function returns an error.

An error also occurs if this function is called and the mode is not VCT_MODE_CONFERENCE.

Parameters
[in]cidThe connection ID of the client being added.
Return values
0Indicates that the connection ID of the client was added successfully.
NegativeThe error code when adding the connection ID of the client failed.


Revision History:

2013/06/11 Fixed a mistake in the description of the return value.

2011/08/31 Initial version.

void VCT_Cleanup ( void  )

Finalizes the VCT library.

Call this function when finalizing VoiceChat or changing the operation mode (VCTMode).


Revision History:
2011/08/31 Initial version.
void VCT_ClearStreaming ( const VCTSession session)

Clears audio streaming.

Parameters
[in]sessionThe session for which to clear streaming.


Revision History:
2013/02/15 Initial version.
bool VCT_DeleteSession ( VCTSession session)

Deletes the specified session.

Parameters
[in]sessionThe VCTSession structure to delete.
Return values
trueDeletion succeeded.
falseDeletion failed.


Revision History:
2011/08/31 Initial version.
void VCT_EnableSparePacket ( bool  flag)

This function enables and disables the spare packet feature.

The spare packet feature is enabled by default.

Parameters
[in]flagSpecify true to enable or false to disable.


Revision History:
2011/08/31 Initial version.
void VCT_EnableVAD ( bool  flag)

Enables or disables the VAD feature.

The VAD feature is enabled by default.

When VAD is enabled, in addition to evaluating audio inside the VCT_Main function, decisions are also made automatically about whether to send packets.

Parameters
[in]flagSpecify true to enable or false to disable.


Revision History:
2011/08/31 Initial version.
u32 VCT_GetAudioDataSize ( void  )

Gets the packet size of audio data.

This function returns the data size calculated based on the currently configured audio frame length. You can use the VCT_GetAudioFrameLength function to get the currently set audio frame length.

If you call this function before initialization, the data size VCT_AUDIO_DATA_SIZE_DEFAULT corresponding to the recommended audio frame length VCT_AUDIO_FRAME_LENGTH_DEFAULT is returned.

Return values
u32Packet size of audio data.
Revision History:
2011/08/31 Initial version.
u32 VCT_GetAudioFrameLength ( void  )

Gets the currently configured audio frame length.

Returns the value set in the frameLength member of the VCTConfig structure at time of initialization, or the value set by the VCT_SetAudioFrameLength function after initialization.

If you call this function before initialization, the recommended value VCT_AUDIO_FRAME_LENGTH_DEFAULT is returned.

Return values
trueConfiguration succeeded.
falseConfiguration failed.


Revision History:
2011/08/31 Initial version.
void VCT_GetAudioInfoFromCid ( u16  cid,
VCTAudioInfo info 
)

Gets audio streaming information for the party specified by cid.

Parameters
[in]cidThe connection ID of the other party from which to get audio streaming information.
[in]infoPointer to an VCTAudioInfo structure.


Revision History:
2011/08/31 Initial version.
u32 VCT_GetAudioScale ( const void *  audio,
u32  length 
)

Gets the calculated audio scale (square of the average power) of the input audio data.

Before using the VCT_SendAudioEx function, use this function to get the volume scale value of the input audio data.

The length argument specifies the number of bytes of audio data to input. The audio data must have been sampled at 16 bits/8 kHz.

Parameters
[in]audioSpecifies the audio data.
[in]lengthSpecifies the number of bytes of the audio data.
Return values
trueThe received data is VoiceChat data.


Revision History:

2012/04/19 - Corrected the description of the length argument by changing "number of samples" to "number of bytes."

2011/09/29 - Clarified that the audio variable is const.

2011/08/31 Initial version.

VCTCodec VCT_GetCodec ( void  )

Gets the currently configured audio codec.

Use the VCT_GetSpareCodec function to get the audio codec type for spare packets.

Return values
@refVCTCodec The audio codec that is currently set for the main packet.
Revision History:
2011/08/31 Initial version.
u32 VCT_GetNoiseSkipTime ( void  )

Returns the length of time for which sound is not sent in VCT_SignalNoiseSkip.

Return values
u32The length of time for which sound is not sent (in milliseconds).


Revision History:
2012/03/01 Initial version.
VCTCodec VCT_GetSpareCodec ( void  )

Gets the currently configured audio codec for spare packets.

This value is meaningless if the spare packet feature is not used.

Note: The only codec type supported for spare packets is 2-bit ADPCM. At the present time, this function always returns VCT_CODEC_2BIT_ADPCM.

Return values
@refVCTCodec The currently set codec type for spare packets.


Revision History:
2011/08/31 Initial version.
u16 VCT_GetVADActiveGain ( void  )

Gets the current speech frame detection threshold.

Return values
u16Threshold for detecting a speech frame.


Revision History:
2011/08/31 Initial version.
bool VCT_GetVADActivity ( void  )

VAD Gets the audio detection results from the VAD algorithm.

Returns true while audio is detected in the frame (speech frame) and false while it is not (silent frame).

Always returns false while the VAD feature is disabled, regardless of the presence of speech.

Return values
trueSpecifies that audio is present.
falseSpecifies that no audio is present.


Revision History:
2011/08/31 Initial version.
u32 VCT_GetVADClampGain ( void  )

Gets the volume threshold as a volume scale value for unconditionally determining silence.

The volume scale value is specified in the range from 0 through 0x3FFFFFFF.

Return values
u32The volume threshold at which a frame is unconditionally determined to be silent.


Revision History:
2011/08/31 Initial version.
u16 VCT_GetVADInactiveGain ( void  )

Gets the current silent frame detection threshold.

Return values
u16Threshold for detecting a silent frame.


Revision History:
2011/08/31 Initial version.
u32 VCT_GetVADReleaseTime ( void  )

Gets the time that must elapse after silence is detected before packet transmission is stopped.

Return values
u32Release time (in number of packets).


Revision History:
2011/08/31 Initial version.
bool VCT_HandleData ( u16  cid,
u8 *  buffer,
u32  size 
)

Processes voice chat data.

Pass the data received by the communications library to this function.

Note
If the return value is true (that is, the received data is voice chat data), no additional processing is necessary because the callback function specified in the callback member variable of the VCTConfig structure is called from this function. If the return value is false, the received data is something other than voice chat data (game data, for example), and you must implement some means for the application to perform the necessary processing on the data.
Parameters
[in]cidConnectionID of the data sender.
[in]bufferPointer to the start of the received data.
[in]sizeThe size of the received data. This value is in bytes.
Return values
trueThe passed data is voice chat data.
falseEither the passed data is voice chat data, or the VCT library is not initialized.


Revision History:

2013/06/07 Revised the description.

2011/08/31 Initial version.

void VCT_HandleReference ( const u8 *  buffer,
u32  size 
)

Supplies reference data for the echo canceler.

Call the nn::snd::GetMixedBusData function at every sound DSP interrupt (every 5 ms), and pass the 5 ms of 16 bit/32 kHz/stereo data obtained by that function to the buffer of this function.

This function does nothing if size is not the correct size for 5 milliseconds of 16-bit/32-kHz stereo data.

Parameters
[in]bufferReference data for the echo canceler.
[in]sizeThe size of the reference data for the echo canceler.


Revision History:

2011/09/29 - Clarified that the buffer variable is const.

2011/08/31 Initial version.

bool VCT_Init ( VCTConfig config)

This function initializes the VCT library.

Parameters
[in]configVCTConfig structure.
Return values
trueInitialization succeeded.
falseInitialization failed.


Revision History:
2011/08/31 Initial version.
bool VCT_IsEnableSparePacket ( void  )

This function gets whether the spare packet feature is enabled or disabled.

The spare packet feature is enabled by default.

Return values
trueSpecifies that the spare packet feature is enabled.
falseSpecifies that the spare packet feature is disabled.


Revision History:
2011/08/31 Initial version.
bool VCT_IsEnableVAD ( void  )

Gets whether the VAD feature is enabled.

Return values
trueSpecifies that the VAD feature is enabled.
falseSpecifies that the VAD feature is disabled.


Revision History:
2011/08/31 Initial version.
bool VCT_IsInitialized ( void  )

Checks whether the VCT library is finished being initialized.

Return values
trueAlready initialized.
falsePre-initialized state.


Revision History:
2011/08/31 Initial version.
bool VCT_IsValidCodec ( VCTCodec  codec)

Determines whether the main packet audio codec type specified by codec is usable.

Parameters
[in]codecAudio codec type.
Return values
trueSpecifies that the codec can be used.
falseSpecifies that the codec cannot be used.


Revision History:
2011/08/31 Initial version.
bool VCT_IsValidSpareCodec ( VCTCodec  codec)

Determines whether you can use the codec type specified by codec as a spare-packet codec type.

Parameters
[in]codecThe codec type.
Return values
trueCan be used.
falseCannot be used.


Revision History:
2011/08/31 Initial version.
void VCT_Main ( void  )

This function runs the main loop of the VCT library.

Sends the audio data queued by VCT_SendAudioEx and decodes the received audio data passed by VCT_HandleData.

The process for sending data that takes place inside VCT_Main (the calling of the send callback) must be called a sufficient number of times, so you also need to call VCT_Main a sufficient number of times. If the audio frame length is length ms and there are num number of communication partners, you must call it more than (num * 1000 / length) times each second. For example, if the audio frame length is 144 ms and there are 8 connected systems, the calculation is 7 * 1000 / 144 = 48.6, so you must call it about 50 to 60 times each second. Also, make calls at regular intervals rather than all at once whenever possible, because audio processing is performed at regular intervals. For example, call it a sufficient number of times in each game frame.


Revision History:

2013/06/07 Added a description of the number of times to call VCT_Main.

2011/08/31 Initial version.

bool VCT_OnConferenceClient ( u16  cid)

Returns whether a client is in the conference.

Parameters
[in]cidThe connection ID of the client to check for membership in the conference.
Return values
trueParticipating.
falseNot a member.


Revision History:
2011/08/31 Initial version.
bool VCT_ReceiveAudio ( void *  audio_data,
u32  length,
u16  outCIDList[] 
)

Extracts audio data from the receive buffer.

The VCT_HandleData function decodes the received audio data. In Conference Mode, this function also acts internally to mix the audio if it is playing on more than one channel.

The audio data written to audio_data is in 16 bit/8 kHz format. This buffer must be aligned to a 32-byte boundary.

This function can be called regardless of whether audio streaming has started or not. If audio streaming has not started, the function clears the audio_data buffer to all zeroes.

If this function is called at varying intervals, breaks in the audio are more likely. If at all possible, call this function in precise multiples of the currently set audio frame length. (Use a timer or other means to call it in units of audio frames.) Use the VCT_GetAudioFrameLength function to get the currently set audio frame length.

This currently set audio frame length is the basis of the data size that is calculated for the length of audio data to write to the buffer. For length, specify the same value as this data size. If you specify any other value, data is not fetched. Use the VCT_GetAudioDataSize function to get the data size calculated based on the audio frame length that is currently set.

Specify outCIDList to get a list of the remote connection IDs that sent the stream. Use this option in Transceiver mode to do things such as switching the pan according to the person who is talking.

You can use the value returned by this function to determine whether there is any audio currently to play. This can be used to mute or turn down the volume of BGM when audio is playing.

Parameters
[out]audio_dataPointer to the audio data buffer.
[in]lengthSize of the audio data buffer.
[out]outCIDListA list of connection IDs for clients that have sent this stream. It is possible to specify NULL.
Return values
trueAudio data was written to the buffer.
falseData is not audio data, streaming has not started, or the library is not initialized.


Revision History:

2012/04/03 - Revised the description of the outCIDList argument.

2011/08/31 Initial version.

s32 VCT_RemoveConferenceClient ( u16  cid)

Removes a client from the conference.

Call this function for all participants in the conference, and not just the person being removed.

Parameters
[in]cidThe connection ID of the client to remove.
Return values
0Indicates that the connection ID of the client was removed successfully.
NegativeThe error code that is returned when removal of the connection ID of the client fails.
Revision History:
2011/08/31 Initial version.
void VCT_ResetVAD ( void  )

Resets the internal VAD status.

Call this function after making changes to the microphone gain or similar settings.


Revision History:
2011/08/31 Initial version.
bool VCT_SendAudioEx ( const void *  audio_data,
u32  micScale,
u32  micOffset 
)

Queues audio data in the send queue.

This function queues audio data in the send queue. This function also handles echo canceler processing.

VAD processing, audio encoding, and the sending of data packets are all performed in the VCT_Main function.

The data in audio_data must have been sampled at 16 bits/8 kHz and aligned to a 32-byte boundary. Calling this function once queues data for a single audio frame using this pointer as the starting point To get the corresponding size of a single audio frame, use the VCT_GetAudioDataSize function.

For micScale, specify the volume scale value that was returned by the VCT_GetAudioScale function.

For micOffset, specify the number of samples that is the computed difference between the newest microphone sample at the time of function execution and the last sample of microphone data input to this function. Specify 0 to input the most recent microphone sample to this function.

This function can be called regardless of whether audio streaming has started. If audio streaming has not yet started, this function does nothing.

If this function is called at varying intervals, the timestamps on the send packets also vary, and the receiving system experiences more errors. If at all possible, call this function in precise multiples of the currently set audio frame length. (Use a timer or other means to call this function in units of audio frames.) Use the VCT_GetAudioFrameLength function to get the currently set audio frame length.

Note: Use the VCT_GetVADActivity function to get the VAD determination result.

Parameters
[in]audio_dataThe audio data.
[in]micScaleThe volume scale value for the audio data.
[in]micOffsetSpecifies the offset (number of samples) between the latest microphone sample and last sample of the input microphone data.
Return values
trueThe audio data has been queued in the send queue.
falseThe audio data has not been queued in the send queue. (Streaming has not started, or the library is not initialized.)


Revision History:

2011/09/29 The session variable was declared const.

2011/08/31 Initial version.

bool VCT_SetAudioFrameLength ( u32  frameLength)

Sets the audio frame length.

For frameLength, you must specify a value between VCT_AUDIO_FRAME_LENGTH_MIN and VCT_AUDIO_FRAME_LENGTH_MAX that is also an integer multiple of 8.

Parameters
[in]frameLengthAudio frame length (in milliseconds).
Return values
trueConfiguration succeeded.
falseConfiguration failed.


Revision History:
2011/08/31 Initial version.
bool VCT_SetCodec ( VCTCodec  codec)

Sets the audio codec.

The codec can be changed even while streaming.

The only supported codecs are 4-bit ADPCM and 2-bit ADPCM. Returns false when an unsupported audio codec is specified.

Use the VCT_SetSpareCodec function to change the audio codec for spare packets.

Parameters
[in]codecThe changed audio codec type for the sender.
Return values
trueAudio data was written to the buffer.
falseData is not audio data, streaming has not started, or the library is not initialized.
Revision History:
2011/08/31 Initial version.
void VCT_SetNoiseSkipTime ( u32  count)

Sets the length of time for which sound is not sent in VCT_SignalNoiseSkip.

Parameters
[in]countSpecifies the length of time sound is not sent (in milliseconds).
Revision History:
2012/03/01 Initial version.
bool VCT_SetSpareCodec ( VCTCodec  spareCodec)

Sets the audio codec for spare packets.

By default, spare packets use the 2-bit ADPCM codec.

Use the VCT_SetCodec function to change the codec for main packets.

Note: The only codec type supported for spare packets is 2-bit ADPCM. Accordingly, this function does not need to be called at this time. Returns false when an unsupported codec has been specified.

Parameters
[in]spareCodecThe spare packet codec type.
Return values
trueSetting succeeded.
falseSetting failed.


Revision History:
2011/08/31 Initial version.
void VCT_SetVADActiveGain ( u16  value)

Sets the speech frame detection threshold.

When the previous audio frame is recognized as a silent frame, this threshold value is used to determine whether the current audio frame contains speech.

A frame is recognized as containing speech when the following condition is met, where Ts is the threshold value, Ec is the average speech power of the audio data in the current frame, and En is the average speech power of the audio data in the four previous frames.

Ec > En * Ts / 100

The value argument takes the threshold (Ts). The default value is 350. In this case, the threshold of the power difference between En and Ec is equivalent to 20 * log (350 / 100) = 10.9 dB.

Parameters
[in]valueSpecifies the speech frame detection threshold.


Revision History:
2011/08/31 Initial version.
void VCT_SetVADClampGain ( u32  value)

Sets the volume threshold as a volume scale value (the square of the average power) for unconditionally determining silence.

value takes a volume scale value in a range from 0 through 0x3FFFFFFF. Any audio frame with a volume scale value below this specified threshold is determined to be a silent frame.

Uses the volume scale value for audio data obtained by the VCT_GetAudioScale function.

The default value is 49.

Parameters
[in]valueThe volume threshold at which a frame is unconditionally determined to be silent.
Revision History:
2011/08/31 Initial version.
void VCT_SetVADInactiveGain ( u16  value)

Sets the silent frame detection threshold.

When the previous audio frame is recognized as a speech frame, this threshold value is used to determine whether the current audio frame is silent.

A frame is recognized as being a silent frame when the following condition is met, where Tn is the threshold value, Ec is the average speech power of the audio data in the most-recent four frames, and En is the average speech power of the audio data in the four frames prior to the last audio frame that was determined to be a silent frame.

Ec < En * Tn / 100

However, the sending of audio frames actually stops when silence is determined to continue for the consecutive number of frames specified by the VCT_SetVADReleaseTime function.

The value argument takes the threshold (Tn). The default value is 280. In this case, the threshold of the power difference between En and Ec is equivalent to 20 * log (280 / 100) = 8.94 dB.

Parameters
[in]valueSpecifies the silent frame detection threshold.


Revision History:
2011/08/31 Initial version.
void VCT_SetVADReleaseTime ( u32  count)

Sets the time that must elapse after silence is detected before packet transmission is stopped.

To prevent VAD from detecting silence in the middle of a conversation because, for example, the user takes a breath, set the release time to at least 500 ms.

For count, specify the time (in packets) to wait after VAD has detected silence before packet transmission is halted. The default is 5 packets (144 * 5 = 720 ms).

Parameters
[in]countRelease time (in number of packets).


Revision History:
2011/08/31 Initial version.
void VCT_SignalNoiseSkip ( void  )

When VAD is enabled and not active, this function makes VAD active on the sound of button presses so that audio is not sent.

Setting up this function enables you to prevent the VAD feature from activating and sending audio on the sound of button presses when VAD is enabled but not active. By not sending audio for a certain time period after button presses, you can minimize the button pressing sounds received by other players.

This function cannot remove button-press sounds while VAD is active and a conversation is being sent.

The duration (in milliseconds) to not send sound is specified with VCT_SetNoiseSkipTime.


Revision History:

2012/05/10 - Revised the description.

2012/03/15 - Supplemented the description.

2012/03/01 Initial version.

bool VCT_StartStreaming ( const VCTSession session)

Starts audio streaming.

Call this function after the session has been established.

Parameters
[in]sessionThe session for which to start streaming.
Return values
trueSuccess.
falseFailed.


Revision History:

2011/09/29 - Clarified that the session variable is const.

2011/08/31 Initial version.

void VCT_StopStreaming ( const VCTSession session)

Stops audio streaming.

Parameters
[in]sessionThe session for which to stop streaming.


Revision History:

2011/09/29 The session variable was declared const.

2011/08/31 Initial version.