Programming with Speex (the libspeex API)

Encoding

In order to encode speech using Speex, you first need to:

#include <speex.h>

You then need to declare a Speex bit-packing struct

SpeexBits bits;

and a Speex encoder state

void *enc_state;

The two are initialized by:

speex_bits_init(&bits);

enc_state = speex_encoder_init(&speex_nb_mode);

For wideband coding, speex_nb_mode will be replaced by speex_wb_mode. In most cases, you will need to know the frame size used by the mode you are using. You can get that value in the frame_size variable with:

speex_encoder_ctl(enc_state,SPEEX_GET_FRAME_SIZE,&frame_size);

Once the initialization is done, for every input frame:

speex_bits_reset(&bits);

speex_encode(enc_state, input_frame, &bits);

nbBytes = speex_bits_write(&bits, byte_ptr, MAX_NB_BYTES);

where input_frame is a (float *) pointing to the beginning of a speech frame, byte_ptr is a (char *) where the encoded frame will be written, MAX_NB_BYTES is the maximum number of bytes that can be written to byte_ptr without causing an overflow and nbBytes is the number of bytes actually written to byte_ptr (the encoded size in bytes). Before calling speex_bits_write, it is possible to find the number of bytes that need to be written by calling speex_bits_nbytes(&bits), which returns a number of bytes.

After you're done with the encoding, free all resources with:

speex_bits_destroy(&bits);

speex_encoder_destroy(enc_state);

That's about it for the encoder.

Decoding

In order to encode speech using Speex, you first need to:

#include <speex.h>

You then need to declare a Speex bit-packing struct

SpeexBits bits;

and a Speex encoder state

void *dec_state;

The two are initialized by:

speex_bits_init(&bits);

dec_state = speex_decoder_init(&speex_nb_mode);

For wideband decoding, speex_nb_mode will be replaced by speex_wb_mode. You can get that value in the frame_size variable with:

speex_decoder_ctl(dec_state, SPEEX_GET_FRAME_SIZE, &frame_size); 

There is also a parameter that can be set for the decoder: whether or not to use a perceptual post-filter. This can be set by:

speex_decoder_ctl(dec_state, SPEEX_SET_PF, &pf); 

where pf is an int that with value 0 to have the post-filter disabled and 1 to have it enabled.

Again, once the decoder initialization is done, for every input frame:

speex_bits_read_from(&bits, input_bytes, nbBytes);

speex_decode(st, &bits, output_frame);

where input_bytes is a (char *) containing the bit-stream data received for a frame, nbBytes is the size (in bytes) of that bit-stream, and output_frame is a (float *) and points to the area where the decoded speech frame will be written. A NULL value as the first argument indicates that we don't have the bits for the current frame. When a frame is lost, the Speex decoder will do its best to "guess" the correct signal.

After you're done with the decoding, free all resources with:

speex_bits_destroy(&bits);

speex_decoder_destroy(dec_state);

Codec Options (speex_*_ctl)

The Speex encoder and decoder support many options and requests that can be accessed through the speex_encoder_ctl and speex_decoder_ctl functions. These functions are similar the the ioctl system call and their prototypes are:

void speex_encoder_ctl(void *encoder, int request, void *ptr);

void speex_decoder_ctl(void *encoder, int request, void *ptr);

The different values of request allowed are (note that some only apply to the encoder or the decoder):

SPEEX_SET_ENH**

Set perceptual enhancer to on (1) or off (0) (integer)

SPEEX_GET_ENH**

Get perceptual enhancer status (integer)

SPEEX_GET_FRAME_SIZE

Get the frame size used for the current mode (integer)

SPEEX_SET_QUALITY*

Set the encoder speech quality (integer 0 to 10)

SPEEX_GET_QUALITY*

Get the current encoder speech quality (integer 0 to 10)

SPEEX_SET_MODE*$\dagger$

 

SPEEX_GET_MODE*$\dagger$

 

SPEEX_SET_LOW_MODE*$\dagger$

 

SPEEX_GET_LOW_MODE*$\dagger$

 

SPEEX_SET_HIGH_MODE*$\dagger$

 

SPEEX_GET_HIGH_MODE*$\dagger$

 

SPEEX_SET_VBR*

Set variable bit-rate (VBR) to on (1) or off (0) (integer)

SPEEX_GET_VBR*

Get variable bit-rate (VBR) status (integer)

SPEEX_SET_VBR_QUALITY*

Set the encoder VBR speech quality (integer 0 to 10)

SPEEX_GET_VBR_QUALITY*

Get the current encoder VBR speech quality (integer 0 to 10)

SPEEX_SET_COMPLEXITY*

Set the CPU resources allowed for the encoder

SPEEX_GET_COMPLEXITY*

Get the CPU resources allowed for the encoder

SPEEX_GET_BITRATE

Get the current bit-rate in use (integer in bps)

*

applies only to the encoder

**

applies only to the decoder

$\dagger$

normally only used internally

Packing more than one frame per packet

Sometimes it is desirable to pack more than one frame per packet (or other basic unit of storage). The proper way to do it is to call speex_encode $N$ times before writing the stream with speex_bits_write.