Speex Codec Documentation

When using optimized fixed-point code on Trimedia, be aware of the following:

1. Memory Alignment: Optimized fixed-point code requires memory alignment. Use the configuration to debug functions where memory is not properly aligned.
2. Rounding Differences: Some QX fractions are packed together using the formula (frac1 * a + frac2 * a) >> X instead of ((frac1 * a) >> X) + ((frac2 * a) >> X). This is done for accuracy in rounding but may cause slight differences between optimized and unoptimized code.
3. Testing Status: Fixed-point encoding/decoding is tested on narrowband. Wideband and ultra-wideband testing is not yet complete. Floating-point optimization for preprocess/mdf is tested, but fixed-point optimization for these modules is not yet verified.

To use optimized code on Trimedia hardware, ensure that the TM_ASM macro is defined. This enables optimized implementations in several core modules including lpc.c, ltp.c, vq.c, and various FFT-related files.

Additionally, for quant_lsp.c, the code includes specific headers based on the architecture:

• If BFIN_ASM is defined: #include "quant_lsp_bfin.h"
• If TM_ASM is defined: #include "quant_lsp_tm.h"

To enable specific hardware acceleration or fixed-point features in Speex on Windows, you must manually add specific macros to the "Preprocessor Definitions" section of your Visual C++ (VC) project options. These settings are applied per configuration (e.g., Debug, Release).

Available Macros:

• USE_SSE: Enables Intel Streaming SIMD Extensions (SSE).
• FIXED_POINT: Enables fixed-point arithmetic.
• EPIC_48K: Enables Epic 48k support.

Important Constraint: USE_SSE and FIXED_POINT are mutually exclusive. You cannot enable both at the same time.

/* Add these to Preprocessor Definitions in Visual C project settings */
USE_SSE
// OR
FIXED_POINT
EPIC_48K

Speex provides command-line utilities for compressing and decompressing audio files. Use speexenc to encode a .wav file into the Speex compressed format (.spx), and speexdec to decode a .spx file back into a .wav file.

Note: Speex is optimized for voice compression at bitrates between 2-45 kbps, making it suitable for VoIP, streaming, and speech archiving.

# Encode a WAV file to Speex format
speexenc [options] input_file.wav compressed_file.spx

# Decode a Speex file back to WAV format
speexdec [options] compressed_file.spx output_file.wav

To build Speex for Symbian OS, use the Symbian abuild tool. The symbian/ directory contains the necessary build definition files:

• bld.inf: Component definition file.
• speex.mmp: Project specification file.
• config.h: Configuration options for both emulator and device builds.

The speexclient is a simple tool designed to demonstrate how to use Speex in a VoIP context. It functions by sending and receiving audio via UDP between two machines. It does not use standard protocols and does not manage connection states; it simply transmits audio to/from the specified ports.

To establish a communication link between two machines (e.g., Alice and Bob), you must specify the local audio device, the remote host, and the respective UDP ports for receiving audio.

# On Alice's machine:
speexclient plughw:0,0 bob.somewhere.net alice_port bob_port

# On Bob's machine:
speexclient plughw:0,0 alice.somewhere.net bob_port alice_port

To cross-compile Speex for the Blackfin DSP (specifically for the STAMP development board) using a source tarball, run the configuration script with the --enable-blackfin-asm, --enable-fixed-point, and --host=bfin-uclinux flags. Note that --enable-blackfin-asm is optional but provides a performance increase of approximately 2x. After configuring, navigate to libspeex and run make.

./configure --enable-blackfin-asm --enable-fixed-point --host=bfin-uclinux
cd libspeex
make

When developing for Symbian OS, you cannot use statically defined SpeexMode structures or the speex_mode_list array. Instead, you must use the speex_lib_get_mode() function to retrieve the appropriate mode.

This function was introduced in libspeex 1.1.7 and is declared in <speex/speex.h>.

// Replace array access:
// mode = speex_mode_list[modeID];
mode = speex_lib_get_mode(modeID);

// Replace static structure references:
// mode1 = &speex_nb_mode;
// mode2 = &speex_wb_mode;
// mode3 = &speex_uwb_mode;

mode1 = speex_lib_get_mode(SPEEX_MODEID_NB);
mode2 = speex_lib_get_mode(SPEEX_MODEID_WB);
mode3 = speex_lib_get_mode(SPEEX_MODEID_UWB);

To cross-compile Speex for the Blackfin DSP using the Git repository, clone the repository, run autogen.sh with the required flags (--enable-blackfin-asm, --enable-fixed-point, and --host=bfin-uclinux), then build the library in the libspeex directory. The --enable-blackfin-asm flag is optional but recommended for a ~2x speedup.

git clone git://git.xiph.org/speex.git
cd speex
./autogen.sh --enable-blackfin-asm --enable-fixed-point --host=bfin-uclinux
cd libspeex
make

If you are using the Trimedia compiler (__TCS__), you must apply specific patches to ensure successful compilation. The Trimedia compiler does not support const * const declarations, which are used in the standard Speex codebase.

To fix this, modify modes.c and speex.h to use a simpler const SpeexMode * declaration when __TCS__ is defined.

// In modes.c
#ifdef __TCS__
const SpeexMode * speex_mode_list[SPEEX_NB_MODES] = {&speex_nb_mode, &speex_wb_mode, &speex_uwb_mode};
#else
const SpeexMode * const speex_mode_list[SPEEX_NB_MODES] = {&speex_nb_mode, &speex_wb_mode, &speex_uwb_mode};
#endif

// In speex.h
#ifdef __TCS__
extern const SpeexMode * speex_mode_list[SPEEX_NB_MODES];
#else
extern const SpeexMode * const speex_mode_list[SPEEX_NB_MODES];
#endif

The config.h file is used to manage memory behavior for the TI DSP builds. It is not automatically generated. You can use it to:

• Change memory allocation method: Switch between using standard calloc or using manual memory allocation.
• Debug memory usage: Enable or disable debug prints for memory allocation, which assists in determining the necessary memory sizes for your specific implementation.