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
#define	speex_lib_get_mode(mode)   ((mode)==SPEEX_MODEID_NB ? &speex_nb_mode : speex_lib_get_mode (mode))
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

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

---