spandsp 0.0.6

gsm0610.h

00001 /*
00002  * SpanDSP - a series of DSP components for telephony
00003  *
00004  * gsm0610.h - GSM 06.10 full rate speech codec.
00005  *
00006  * Written by Steve Underwood <steveu@coppice.org>
00007  *
00008  * Copyright (C) 2006 Steve Underwood
00009  *
00010  * All rights reserved.
00011  *
00012  * This program is free software; you can redistribute it and/or modify
00013  * it under the terms of the GNU Lesser General Public License version 2.1,
00014  * as published by the Free Software Foundation.
00015  *
00016  * This program is distributed in the hope that it will be useful,
00017  * but WITHOUT ANY WARRANTY; without even the implied warranty of
00018  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00019  * GNU Lesser General Public License for more details.
00020  *
00021  * You should have received a copy of the GNU Lesser General Public
00022  * License along with this program; if not, write to the Free Software
00023  * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
00024  */
00025 
00026 #if !defined(_SPANDSP_GSM0610_H_)
00027 #define _SPANDSP_GSM0610_H_
00028 
00029 /*! \page gsm0610_page GSM 06.10 encoding and decoding
00030 \section gsm0610_page_sec_1 What does it do?
00031 
00032 The GSM 06.10 module is an version of the widely used GSM FR codec software
00033 available from http://kbs.cs.tu-berlin.de/~jutta/toast.html. This version
00034 was produced since some versions of this codec are not bit exact, or not
00035 very efficient on modern processors. This implementation can use MMX instructions
00036 on Pentium class processors, or alternative methods on other processors. It
00037 passes all the ETSI test vectors. That is, it is a tested bit exact implementation.
00038 
00039 This implementation supports encoded data in one of three packing formats:
00040     - Unpacked, with the 76 parameters of a GSM 06.10 code frame each occupying a
00041       separate byte. (note that none of the parameters exceed 8 bits).
00042     - Packed the the 33 byte per frame, used for VoIP, where 4 bits per frame are wasted.
00043     - Packed in WAV49 format, where 2 frames are packed into 65 bytes.
00044 
00045 \section gsm0610_page_sec_2 How does it work?
00046 ???.
00047 */
00048 
00049 enum
00050 {
00051     GSM0610_PACKING_NONE,
00052     GSM0610_PACKING_WAV49,
00053     GSM0610_PACKING_VOIP
00054 };
00055 
00056 /*!
00057     GSM 06.10 FR codec unpacked frame.
00058 */
00059 typedef struct
00060 {
00061     int16_t LARc[8];
00062     int16_t Nc[4];
00063     int16_t bc[4];
00064     int16_t Mc[4];
00065     int16_t xmaxc[4];
00066     int16_t xMc[4][13];
00067 } gsm0610_frame_t;
00068 
00069 /*!
00070     GSM 06.10 FR codec state descriptor. This defines the state of
00071     a single working instance of the GSM 06.10 FR encoder or decoder.
00072 */
00073 typedef struct gsm0610_state_s gsm0610_state_t;
00074 
00075 #if defined(__cplusplus)
00076 extern "C"
00077 {
00078 #endif
00079 
00080 /*! Initialise a GSM 06.10 encode or decode context.
00081     \param s The GSM 06.10 context
00082     \param packing One of the GSM0610_PACKING_xxx options.
00083     \return A pointer to the GSM 06.10 context, or NULL for error. */
00084 SPAN_DECLARE(gsm0610_state_t *) gsm0610_init(gsm0610_state_t *s, int packing);
00085 
00086 /*! Release a GSM 06.10 encode or decode context.
00087     \param s The GSM 06.10 context
00088     \return 0 for success, else -1. */
00089 SPAN_DECLARE(int) gsm0610_release(gsm0610_state_t *s);
00090 
00091 /*! Free a GSM 06.10 encode or decode context.
00092     \param s The GSM 06.10 context
00093     \return 0 for success, else -1. */
00094 SPAN_DECLARE(int) gsm0610_free(gsm0610_state_t *s);
00095 
00096 /*! Set the packing format for a GSM 06.10 encode or decode context.
00097     \param s The GSM 06.10 context
00098     \param packing One of the GSM0610_PACKING_xxx options.
00099     \return 0 for success, else -1. */
00100 SPAN_DECLARE(int) gsm0610_set_packing(gsm0610_state_t *s, int packing);
00101 
00102 /*! Encode a buffer of linear PCM data to GSM 06.10.
00103     \param s The GSM 06.10 context.
00104     \param code The GSM 06.10 data produced.
00105     \param amp The audio sample buffer.
00106     \param len The number of samples in the buffer.
00107     \return The number of bytes of GSM 06.10 data produced. */
00108 SPAN_DECLARE(int) gsm0610_encode(gsm0610_state_t *s, uint8_t code[], const int16_t amp[], int len);
00109 
00110 /*! Decode a buffer of GSM 06.10 data to linear PCM.
00111     \param s The GSM 06.10 context.
00112     \param amp The audio sample buffer.
00113     \param code The GSM 06.10 data.
00114     \param len The number of bytes of GSM 06.10 data to be decoded.
00115     \return The number of samples returned. */
00116 SPAN_DECLARE(int) gsm0610_decode(gsm0610_state_t *s, int16_t amp[], const uint8_t code[], int len);
00117 
00118 SPAN_DECLARE(int) gsm0610_pack_none(uint8_t c[], const gsm0610_frame_t *s);
00119 
00120 /*! Pack a pair of GSM 06.10 frames in the format used for wave files (wave type 49).
00121     \param c The buffer for the packed data. This must be at least 65 bytes long.
00122     \param s A pointer to the frames to be packed.
00123     \return The number of bytes generated. */
00124 SPAN_DECLARE(int) gsm0610_pack_wav49(uint8_t c[], const gsm0610_frame_t *s);
00125 
00126 /*! Pack a GSM 06.10 frames in the format used for VoIP.
00127     \param c The buffer for the packed data. This must be at least 33 bytes long.
00128     \param s A pointer to the frame to be packed.
00129     \return The number of bytes generated. */
00130 SPAN_DECLARE(int) gsm0610_pack_voip(uint8_t c[], const gsm0610_frame_t *s);
00131 
00132 SPAN_DECLARE(int) gsm0610_unpack_none(gsm0610_frame_t *s, const uint8_t c[]);
00133 
00134 /*! Unpack a pair of GSM 06.10 frames from the format used for wave files (wave type 49).
00135     \param s A pointer to a buffer into which the frames will be packed.
00136     \param c The buffer containing the data to be unpacked. This must be at least 65 bytes long.
00137     \return The number of bytes absorbed. */
00138 SPAN_DECLARE(int) gsm0610_unpack_wav49(gsm0610_frame_t *s, const uint8_t c[]);
00139 
00140 /*! Unpack a GSM 06.10 frame from the format used for VoIP.
00141     \param s A pointer to a buffer into which the frame will be packed.
00142     \param c The buffer containing the data to be unpacked. This must be at least 33 bytes long.
00143     \return The number of bytes absorbed. */
00144 SPAN_DECLARE(int) gsm0610_unpack_voip(gsm0610_frame_t *s, const uint8_t c[]);
00145 
00146 #if defined(__cplusplus)
00147 }
00148 #endif
00149 
00150 #endif
00151 /*- End of include ---------------------------------------------------------*/