# Speex encoder and decoder

## Classes

struct | SpeexMode

## Defines

#define | SPEEX_SET_ENH 0
#define | SPEEX_GET_ENH 1
#define | SPEEX_GET_FRAME_SIZE 3
#define | SPEEX_SET_QUALITY 4
#define | SPEEX_SET_MODE 6
#define | SPEEX_GET_MODE 7
#define | SPEEX_SET_LOW_MODE 8
#define | SPEEX_GET_LOW_MODE 9
#define | SPEEX_SET_HIGH_MODE 10
#define | SPEEX_GET_HIGH_MODE 11
#define | SPEEX_SET_VBR 12
#define | SPEEX_GET_VBR 13
#define | SPEEX_SET_VBR_QUALITY 14
#define | SPEEX_GET_VBR_QUALITY 15
#define | SPEEX_SET_COMPLEXITY 16
#define | SPEEX_GET_COMPLEXITY 17
#define | SPEEX_SET_BITRATE 18
#define | SPEEX_GET_BITRATE 19
#define | SPEEX_SET_HANDLER 20
#define | SPEEX_SET_USER_HANDLER 22
#define | SPEEX_SET_SAMPLING_RATE 24
#define | SPEEX_GET_SAMPLING_RATE 25
#define | SPEEX_RESET_STATE 26
#define | SPEEX_GET_RELATIVE_QUALITY 29
#define | SPEEX_SET_VAD 30
#define | SPEEX_GET_VAD 31
#define | SPEEX_SET_ABR 32
#define | SPEEX_GET_ABR 33
#define | SPEEX_SET_DTX 34
#define | SPEEX_GET_DTX 35
#define | SPEEX_SET_SUBMODE_ENCODING 36
#define | SPEEX_GET_SUBMODE_ENCODING 37
#define | SPEEX_GET_LOOKAHEAD 39
#define | SPEEX_SET_PLC_TUNING 40
#define | SPEEX_GET_PLC_TUNING 41
#define | SPEEX_SET_VBR_MAX_BITRATE 42
#define | SPEEX_GET_VBR_MAX_BITRATE 43
#define | SPEEX_SET_HIGHPASS 44
#define | SPEEX_GET_HIGHPASS 45
#define | SPEEX_GET_ACTIVITY 47
#define | SPEEX_SET_PF 0
#define | SPEEX_GET_PF 1
#define | SPEEX_MODE_FRAME_SIZE 0
#define | SPEEX_SUBMODE_BITS_PER_FRAME 1
#define | SPEEX_LIB_GET_MAJOR_VERSION 1
#define | SPEEX_LIB_GET_MINOR_VERSION 3
#define | SPEEX_LIB_GET_MICRO_VERSION 5
#define | SPEEX_LIB_GET_EXTRA_VERSION 7
#define | SPEEX_LIB_GET_VERSION_STRING 9
#define | SPEEX_NB_MODES 3
#define | SPEEX_MODEID_NB 0
#define | SPEEX_MODEID_WB 1
#define | SPEEX_MODEID_UWB 2

## Typedefs

typedef void *(* | encoder_init_func )(const struct SpeexMode *mode)
typedef void(* | encoder_destroy_func )(void *st)
typedef int(* | encode_func )(void *state, void *in, SpeexBits *bits)
typedef int(* | encoder_ctl_func )(void *state, int request, void *ptr)
typedef void *(* | decoder_init_func )(const struct SpeexMode *mode)
typedef void(* | decoder_destroy_func )(void *st)
typedef int(* | decode_func )(void *state, SpeexBits *bits, void *out)
typedef int(* | decoder_ctl_func )(void *state, int request, void *ptr)
typedef int(* | mode_query_func )(const void *mode, int request, void *ptr)

## Functions

void * | speex_encoder_init (const SpeexMode *mode)
void | speex_encoder_destroy (void *state)
int | speex_encode (void *state, float *in, SpeexBits *bits)
int | speex_encode_int (void *state, spx_int16_t *in, SpeexBits *bits)
int | speex_encoder_ctl (void *state, int request, void *ptr)
void * | speex_decoder_init (const SpeexMode *mode)
void | speex_decoder_destroy (void *state)
int | speex_decode (void *state, SpeexBits *bits, float *out)
int | speex_decode_int (void *state, SpeexBits *bits, spx_int16_t *out)
int | speex_decoder_ctl (void *state, int request, void *ptr)
int | speex_mode_query (const SpeexMode *mode, int request, void *ptr)
int | speex_lib_ctl (int request, void *ptr)
const SpeexMode * | speex_lib_get_mode (int mode)

## Variables

const SpeexMode | speex_nb_mode
const SpeexMode | speex_wb_mode
const SpeexMode | speex_uwb_mode
const SpeexMode *const | speex_mode_list [SPEEX_NB_MODES]

## Detailed Description

This is the Speex codec itself.

## Define Documentation

#define SPEEX_GET_ABR 33

Get Average Bit-Rate (ABR) setting (in bps)

#define SPEEX_GET_ACTIVITY 47

Get "activity level" of the last decoded frame, i.e. how much damage we cause if we remove the frame

#define SPEEX_GET_BITRATE 19

Get current bit-rate used by the encoder or decoder

#define SPEEX_GET_COMPLEXITY 17

Get current complexity of the encoder (0-10)

#define SPEEX_GET_DTX 35

Get DTX status (1 for on, 0 for off)

#define SPEEX_GET_ENH 1

Get enhancement state (decoder only)

#define SPEEX_GET_FRAME_SIZE 3

Obtain frame size used by encoder/decoder

#define SPEEX_GET_HIGH_MODE 11

Get current high-band mode in use (wideband only)

#define SPEEX_GET_HIGHPASS 45

Get status of input/output high-pass filtering

#define SPEEX_GET_LOOKAHEAD 39

Returns the lookahead used by Speex

#define SPEEX_GET_LOW_MODE 9

Get current low-band mode in use (wideband only)

#define SPEEX_GET_MODE 7

Get current sub-mode in use

#define SPEEX_GET_PF 1

Equivalent to SPEEX_GET_ENH

#define SPEEX_GET_PLC_TUNING 41

Gets tuning for PLC

#define SPEEX_GET_RELATIVE_QUALITY 29

Get VBR info (mostly used internally)

#define SPEEX_GET_SAMPLING_RATE 25

Get sampling rate used in bit-rate computation

#define SPEEX_GET_SUBMODE_ENCODING 37

Get submode encoding in each frame

#define SPEEX_GET_VAD 31

Get VAD status (1 for on, 0 for off)

#define SPEEX_GET_VBR 13

Get VBR status (1 for on, 0 for off)

#define SPEEX_GET_VBR_MAX_BITRATE 43

Gets the max bit-rate allowed in VBR mode

#define SPEEX_GET_VBR_QUALITY 15

Get current quality value for VBR encoding (0-10)

#define SPEEX_LIB_GET_EXTRA_VERSION 7

Get extra Speex version

#define SPEEX_LIB_GET_MAJOR_VERSION 1

Get major Speex version

#define SPEEX_LIB_GET_MICRO_VERSION 5

Get micro Speex version

#define SPEEX_LIB_GET_MINOR_VERSION 3

Get minor Speex version

#define SPEEX_LIB_GET_VERSION_STRING 9

Get Speex version string

#define SPEEX_MODE_FRAME_SIZE 0

Query the frame size of a mode

#define SPEEX_MODEID_NB 0

modeID for the defined narrowband mode

#define SPEEX_MODEID_UWB 2

modeID for the defined ultra-wideband mode

#define SPEEX_MODEID_WB 1

modeID for the defined wideband mode

#define SPEEX_NB_MODES 3

Number of defined modes in Speex

#define SPEEX_RESET_STATE 26

Reset the encoder/decoder memories to zero

#define SPEEX_SET_ABR 32

Set Average Bit-Rate (ABR) to n bits per seconds

#define SPEEX_SET_BITRATE 18

Set bit-rate used by the encoder (or lower)

#define SPEEX_SET_COMPLEXITY 16

Set complexity of the encoder (0-10)

#define SPEEX_SET_DTX 34

Set DTX status (1 for on, 0 for off)

#define SPEEX_SET_ENH 0

Set enhancement on/off (decoder only)

#define SPEEX_SET_HANDLER 20

Define a handler function for in-band Speex request

#define SPEEX_SET_HIGH_MODE 10

Set high-band sub-mode to use (wideband only)

#define SPEEX_SET_HIGHPASS 44

Turn on/off input/output high-pass filtering

#define SPEEX_SET_LOW_MODE 8

Set low-band sub-mode to use (wideband only)

#define SPEEX_SET_MODE 6

Get current quality setting Set sub-mode to use

#define SPEEX_SET_PF 0

Equivalent to SPEEX_SET_ENH

#define SPEEX_SET_PLC_TUNING 40

Sets tuning for packet-loss concealment (expected loss rate)

#define SPEEX_SET_QUALITY 4

Set quality value

#define SPEEX_SET_SAMPLING_RATE 24

Set sampling rate used in bit-rate computation

#define SPEEX_SET_SUBMODE_ENCODING 36

Set submode encoding in each frame (1 for yes, 0 for no, setting to no breaks the standard)

#define SPEEX_SET_USER_HANDLER 22

Define a handler function for in-band user-defined request

#define SPEEX_SET_VAD 30

Set VAD status (1 for on, 0 for off)

#define SPEEX_SET_VBR 12

Set VBR on (1) or off (0)

#define SPEEX_SET_VBR_MAX_BITRATE 42

Sets the max bit-rate allowed in VBR mode

#define SPEEX_SET_VBR_QUALITY 14

Set quality value for VBR encoding (0-10)

#define SPEEX_SUBMODE_BITS_PER_FRAME 1

Query the size of an encoded frame for a particular sub-mode

## Typedef Documentation

typedef int(* decode_func)(void *state, SpeexBits *bits, void *out)

Main decoding function

typedef int(* decoder_ctl_func)(void *state, int request, void *ptr)

Function for controlling the decoder options

typedef void(* decoder_destroy_func)(void *st)

Decoder state destruction function

typedef void*(* decoder_init_func)(const struct SpeexMode *mode)

Decoder state initialization function

typedef int(* encode_func)(void *state, void *in, SpeexBits *bits)

Main encoding function

typedef int(* encoder_ctl_func)(void *state, int request, void *ptr)

Function for controlling the encoder options

typedef void(* encoder_destroy_func)(void *st)

Encoder state destruction function

typedef void*(* encoder_init_func)(const struct SpeexMode *mode)

Encoder state initialization function

typedef int(* mode_query_func)(const void *mode, int request, void *ptr)

Query function for a mode

## Function Documentation

int speex_decode | ( | void * | state,
|  | SpeexBits * | bits,
|  | float * | out |
| ) |  |  |

Uses an existing decoder state to decode one frame of speech from bit-stream bits. The output speech is saved written to out.

Parameters:

  | state | Decoder state
  | bits | Bit-stream from which to decode the frame (NULL if the packet was lost)
  | out | Where to write the decoded frame

Returns:
  return status (0 for no error, -1 for end of stream, -2 corrupt stream)

int speex_decode_int | ( | void * | state,
|  | SpeexBits * | bits,
|  | spx_int16_t * | out |
| ) |  |  |

Uses an existing decoder state to decode one frame of speech from bit-stream bits. The output speech is saved written to out.

Parameters:

  | state | Decoder state
  | bits | Bit-stream from which to decode the frame (NULL if the packet was lost)
  | out | Where to write the decoded frame

Returns:
  return status (0 for no error, -1 for end of stream, -2 corrupt stream)

int speex_decoder_ctl | ( | void * | state,
|  | int | request,
|  | void * | ptr |
| ) |  |  |

Used like the ioctl function to control the encoder parameters

Parameters:

  | state | Decoder state
  | request | ioctl-type request (one of the SPEEX_* macros)
  | ptr | Data exchanged to-from function

Returns:
  0 if no error, -1 if request in unknown, -2 for invalid parameter

void speex_decoder_destroy | ( | void * | state | ) |

Frees all resources associated to an existing decoder state.

Parameters:

  | state | State to be destroyed

void* speex_decoder_init | ( | const SpeexMode * | mode | ) |

Returns a handle to a newly created decoder state structure. For now, the mode argument can be &nb_mode or &wb_mode . In the future, more modes may be added. Note that for now if you have more than one channels to decode, you need one state per channel.

Parameters:

  | mode | Speex mode (one of speex_nb_mode or speex_wb_mode)

Returns:
  A newly created decoder state or NULL if state allocation fails

int speex_encode | ( | void * | state,
|  | float * | in,
|  | SpeexBits * | bits |
| ) |  |  |

Uses an existing encoder state to encode one frame of speech pointed to by "in". The encoded bit-stream is saved in "bits".

Parameters:

  | state | Encoder state
  | in | Frame that will be encoded with a +-2^15 range. This data MAY be overwritten by the encoder and should be considered uninitialised after the call.
  | bits | Bit-stream where the data will be written

Returns:
  0 if frame needs not be transmitted (DTX only), 1 otherwise

int speex_encode_int | ( | void * | state,
|  | spx_int16_t * | in,
|  | SpeexBits * | bits |
| ) |  |  |

Uses an existing encoder state to encode one frame of speech pointed to by "in". The encoded bit-stream is saved in "bits".

Parameters:

  | state | Encoder state
  | in | Frame that will be encoded with a +-2^15 range
  | bits | Bit-stream where the data will be written

Returns:
  0 if frame needs not be transmitted (DTX only), 1 otherwise

int speex_encoder_ctl | ( | void * | state,
|  | int | request,
|  | void * | ptr |
| ) |  |  |

Used like the ioctl function to control the encoder parameters

Parameters:

  | state | Encoder state
  | request | ioctl-type request (one of the SPEEX_* macros)
  | ptr | Data exchanged to-from function

Returns:
  0 if no error, -1 if request in unknown, -2 for invalid parameter

void speex_encoder_destroy | ( | void * | state | ) |

Frees all resources associated to an existing Speex encoder state.

Parameters:

  | state | Encoder state to be destroyed

void* speex_encoder_init | ( | const SpeexMode * | mode | ) |

Returns a handle to a newly created Speex encoder state structure. For now, the "mode" argument can be &nb_mode or &wb_mode . In the future, more modes may be added. Note that for now if you have more than one channels to encode, you need one state per channel.

Parameters:

  | mode | The mode to use (either speex_nb_mode or speex_wb.mode)

Returns:
  A newly created encoder state or NULL if state allocation fails

int speex_lib_ctl | ( | int | request,
|  | void * | ptr |
| ) |  |  |

Functions for controlling the behavior of libspeex

Parameters:

  | request | ioctl-type request (one of the SPEEX_LIB_* macros)
  | ptr | Data exchanged to-from function

Returns:
  0 if no error, -1 if request in unknown, -2 for invalid parameter

const SpeexMode* speex_lib_get_mode | ( | int | mode | ) |

Obtain one of the modes available

int speex_mode_query | ( | const SpeexMode * | mode,
|  | int | request,
|  | void * | ptr |
| ) |  |  |

Query function for mode information

Parameters:

  | mode | Speex mode
  | request | ioctl-type request (one of the SPEEX_* macros)
  | ptr | Data exchanged to-from function

Returns:
  0 if no error, -1 if request in unknown, -2 for invalid parameter

## Variable Documentation

const SpeexMode* const speex_mode_list[SPEEX_NB_MODES]

List of all modes available

const SpeexMode speex_nb_mode

Default narrowband mode

const SpeexMode speex_uwb_mode

Default "ultra-wideband" mode

const SpeexMode speex_wb_mode

Default wideband mode