diff options
author | Sylvain Munaut <tnt@246tNt.com> | 2013-12-17 18:14:43 +0100 |
---|---|---|
committer | Sylvain Munaut <tnt@246tNt.com> | 2013-12-17 18:15:43 +0100 |
commit | 074f93ad742cc672524e0877eb3385adf37a90f1 (patch) | |
tree | e862f33f1620d76cd4037b91ce0b2c2229103e7c | |
parent | df95ae699fe76d4c4206fee50bf10948dca90518 (diff) |
codec: Documentation
Signed-off-by: Sylvain Munaut <tnt@246tNt.com>
-rw-r--r-- | src/codec/ambe.c | 37 | ||||
-rw-r--r-- | src/codec/codec.c | 2 | ||||
-rw-r--r-- | src/codec/frame.c | 44 | ||||
-rw-r--r-- | src/codec/math.c | 2 | ||||
-rw-r--r-- | src/codec/private.h | 12 | ||||
-rw-r--r-- | src/codec/tables.c | 50 | ||||
-rw-r--r-- | src/codec/tone.c | 8 |
7 files changed, 116 insertions, 39 deletions
diff --git a/src/codec/ambe.c b/src/codec/ambe.c index d571010..5776762 100644 --- a/src/codec/ambe.c +++ b/src/codec/ambe.c @@ -17,7 +17,7 @@ * along with this program. If not, see <http://www.gnu.org/licenses/>. */ -/*! \addtogroup codec/private +/*! \addtogroup codec_private * @{ */ @@ -33,6 +33,9 @@ #include "private.h" +/*! \brief Initializes decoder state + * \param[in] dec Decoder state structure + */ void ambe_decode_init(struct ambe_decoder *dec) { @@ -40,6 +43,9 @@ ambe_decode_init(struct ambe_decoder *dec) mbe_initMbeParms(&dec->mp_prev); } +/*! \brief Release all resources associated with a decoder + * \param[in] dec Decoder state structure + */ void ambe_decode_fini(struct ambe_decoder *dec) { @@ -47,6 +53,10 @@ ambe_decode_fini(struct ambe_decoder *dec) } +/*! \brief Identify the type of frame + * \param[in] frame Frame data (10 bytes = 80 bits) + * \returns See \ref ambe_frame_type for possible return values + */ static enum ambe_frame_type ambe_classify_frame(const uint8_t *frame) { @@ -62,6 +72,10 @@ ambe_classify_frame(const uint8_t *frame) }; } +/*! \brief Converts an internal \ref ambe_subframe to a mbelib's \ref mbe_parameters + * \param[out] mp mbelib's parameters structure to fill in + * \param[in] sf Internal suframe data + */ static void ambe_subframe_to_mbelib(mbe_parms *mp, struct ambe_subframe *sf) { @@ -82,6 +96,14 @@ ambe_subframe_to_mbelib(mbe_parms *mp, struct ambe_subframe *sf) } } +/*! \brief Decodes an AMBE speech frame to audio + * \param[in] dec Decoder state structure + * \param[out] audio Output audio buffer + * \param[in] N number of audio samples to produce (152..168) + * \param[in] frame Frame data (10 bytes = 80 bits) + * \param[in] bad Bad Frame Indicator. Set to 1 if frame is corrupt + * \returns 0 for success. Negative error code otherwise. + */ static int ambe_decode_speech(struct ambe_decoder *dec, int16_t *audio, int N, @@ -117,6 +139,14 @@ ambe_decode_speech(struct ambe_decoder *dec, return 0; } +/*! \brief Decodes an AMBE frame to audio + * \param[in] dec Decoder state structure + * \param[out] audio Output audio buffer + * \param[in] N number of audio samples to produce (152..168) + * \param[in] frame Frame data (10 bytes = 80 bits) + * \param[in] bad Bad Frame Indicator. Set to 1 if frame is corrupt + * \returns 0 for success. Negative error code otherwise. + */ int ambe_decode_frame(struct ambe_decoder *dec, int16_t *audio, int N, @@ -138,6 +168,11 @@ ambe_decode_frame(struct ambe_decoder *dec, return -EINVAL; } +/*! \brief Generates audio for DTX period + * \param[in] dec Decoder state structure + * \param[out] audio Output audio buffer + * \param[in] N number of audio samples to produce (152..168) + */ int ambe_decode_dtx(struct ambe_decoder *dec, int16_t *audio, int N) diff --git a/src/codec/codec.c b/src/codec/codec.c index c422b5b..1720ea6 100644 --- a/src/codec/codec.c +++ b/src/codec/codec.c @@ -37,7 +37,7 @@ /*! \brief Structure for GMR1 codec state */ struct gmr1_codec { - struct ambe_decoder dec; /*< \brief decoder state */ + struct ambe_decoder dec; /*!< \brief Decoder state */ }; diff --git a/src/codec/frame.c b/src/codec/frame.c index 309fd8f..c212b41 100644 --- a/src/codec/frame.c +++ b/src/codec/frame.c @@ -17,7 +17,7 @@ * along with this program. If not, see <http://www.gnu.org/licenses/>. */ -/*! \addtogroup codec/private +/*! \addtogroup codec_private * @{ */ @@ -32,6 +32,13 @@ #include "private.h" +/*! \brief Grab the requested bits from a frame and shift them up as requested + * \param[in] frame Frame data bytes + * \param[in] p Position of the first bit to grab + * \param[in] l Number of bits to grab (max 8) + * \param[in] s How many bits to shift the result up + * \returns The selected bits as a uint8_t + */ static inline uint8_t _get_bits(const uint8_t *frame, int p, int l, int s) { @@ -46,6 +53,10 @@ _get_bits(const uint8_t *frame, int p, int l, int s) return (v & ((1<<l)-1)) << s; } +/*! \brief Unpack a frame into its raw encoded parameters + * \param[out] rp Encoded frame raw parameters to unpack into + * \param[in] frame Frame data (10 bytes = 80 bits) + */ void ambe_frame_unpack_raw(struct ambe_raw_params *rp, const uint8_t *frame) { @@ -67,6 +78,12 @@ ambe_frame_unpack_raw(struct ambe_raw_params *rp, const uint8_t *frame) rp->sf0_perr_58 = _get_bits(p, 44, 2, 3) | _get_bits(p, 77, 3, 0); } +/*! \brief Interpolates fundamental between subframes + * \param[in] f0log_prev log(fund(-1)) Previous subframe log freq + * \param[in] f0log_cur log(fund(0)) Current subframe log freq + * \param[in] rule Which interpolation rule to apply + * \returns The interpolated log(fund) frequency + */ static float ambe_interpolate_f0log(float f0log_prev, float f0log_cur, int rule) { @@ -104,6 +121,9 @@ ambe_interpolate_f0log(float f0log_prev, float f0log_cur, int rule) return 0.0f; /* Not reached */ } +/*! \brief Computes and fill-in L and Lb vaues for a given subframe (from f0) + * \param[in] sf Subframe + */ static void ambe_subframe_compute_L_Lb(struct ambe_subframe *sf) { @@ -120,6 +140,12 @@ ambe_subframe_compute_L_Lb(struct ambe_subframe *sf) sf->Lb[3] = ambe_hpg_tbl[sf->L - 9][3]; } +/*! \brief Resample and "ac-couple" (remove mean) a magnitude array to a new L + * \param[in] mag_dst Destination magnitude array (L_dst elements) + * \param[in] L_dst Target number of magnitudes + * \param[in] mag_src Source magnitude array (L_src elements) + * \param[in] L_src Source number of magnitudes + */ static void ambe_resample_mag(float *mag_dst, int L_dst, float *mag_src, int L_src) { @@ -154,6 +180,11 @@ ambe_resample_mag(float *mag_dst, int L_dst, float *mag_src, int L_src) mag_dst[i] -= avg; } +/*! \brief Compute the spectral magnitudes of subframe 1 from raw params + * \param[inout] sf Current subframe1 data + * \param[in] sf_prev Previous subframe1 data + * \param[in] rp Encoded frame raw parameters + */ static void ambe_subframe1_compute_mag(struct ambe_subframe *sf, struct ambe_subframe *sf_prev, @@ -224,6 +255,12 @@ ambe_subframe1_compute_mag(struct ambe_subframe *sf, sf->Mlog[i] += ofs; } +/*! \brief Compute the spectral magnitudes of subframe 0 from raw params & sf1 + * \param[inout] sf Current subframe0 data + * \param[in] sf1_prev Previous subframe 1 data + * \param[in] sf1_cur Current subframe 1 data + * \param[in] rp Encoded frame raw parameters + */ static void ambe_subframe0_compute_mag(struct ambe_subframe *sf, struct ambe_subframe *sf1_prev, @@ -263,6 +300,11 @@ ambe_subframe0_compute_mag(struct ambe_subframe *sf, sf->Mlog[i] = gain + corr[i] + (alpha * mag_p[i]) + ((1.0f - alpha) * mag_c[i]); } +/*! \brief Decodes the speech parameters for both subframes from raw params + * \param[out] sf Array of 2 subframes data to fill-in + * \param[in] sf_prev Previous subframe 1 data + * \param[in] rp Encoded frame raw parameters + */ int ambe_frame_decode_params(struct ambe_subframe *sf, struct ambe_subframe *sf_prev, diff --git a/src/codec/math.c b/src/codec/math.c index 334677a..3f4cc33 100644 --- a/src/codec/math.c +++ b/src/codec/math.c @@ -17,7 +17,7 @@ * along with this program. If not, see <http://www.gnu.org/licenses/>. */ -/*! \addtogroup codec/private +/*! \addtogroup codec_private * @{ */ diff --git a/src/codec/private.h b/src/codec/private.h index 9edea03..b6eddaf 100644 --- a/src/codec/private.h +++ b/src/codec/private.h @@ -20,8 +20,8 @@ #ifndef __OSMO_GMR1_CODEC_PRIVATE_H__ #define __OSMO_GMR1_CODEC_PRIVATE_H__ -/*! \defgroup codec/private AMBE vocoder - internal API - * \ingroup codec/private +/*! \defgroup codec_private AMBE vocoder - internal API + * \ingroup codec * @{ */ @@ -34,15 +34,15 @@ #include "mbelib.h" -#define AMBE_RATE 8000 /*< \brief AMBE sample rate */ +#define AMBE_RATE 8000 /*!< \brief AMBE sample rate (Hz) */ /*! \brief AMBE possible frame types */ enum ambe_frame_type { - AMBE_SPEECH, /*< \brief Speed frame */ - AMBE_SILENCE, /*< \brief Silence indication frame */ - AMBE_TONE, /*< \brief Tone frame */ + AMBE_SPEECH, /*!< \brief Speech frame */ + AMBE_SILENCE, /*!< \brief Silence indication frame */ + AMBE_TONE, /*!< \brief Tone frame */ }; /*! \brief AMBE encoded frame raw parameters */ diff --git a/src/codec/tables.c b/src/codec/tables.c index 32c19b6..6accc24 100644 --- a/src/codec/tables.c +++ b/src/codec/tables.c @@ -17,7 +17,7 @@ * along with this program. If not, see <http://www.gnu.org/licenses/>. */ -/*! \addtogroup codec/private +/*! \addtogroup codec_private * @{ */ @@ -28,7 +28,7 @@ #include <stdint.h> /*! \brief Number of harmonics per group for a given L (starts at L=9) */ -const uint8_t ambe_hpg_tbl[48][4] = { +extern const uint8_t ambe_hpg_tbl[48][4] = { { 2, 2, 2, 3} /* L = 9 */, { 2, 2, 3, 3}, { 2, 3, 3, 3}, @@ -79,8 +79,8 @@ const uint8_t ambe_hpg_tbl[48][4] = { { 11, 13, 15, 17}, /* L = 56 */ }; -/* \brief Gain (subframe 0, subframe 1) */ -const float ambe_gain_tbl[256][2] = { +/*! \brief Gain (subframe 0, subframe 1) */ +extern const float ambe_gain_tbl[256][2] = { { -0.250000f, -0.250000f }, { +0.500000f, -0.500000f }, { +0.750000f, +0.750000f }, @@ -340,7 +340,7 @@ const float ambe_gain_tbl[256][2] = { }; /*! \brief V/UV decisions (subframe 0 = low byte. MSBs = low freq) */ -const uint16_t ambe_v_uv_tbl[64] = { +extern const uint16_t ambe_v_uv_tbl[64] = { 0x0000, 0xffff, 0xc0c0, 0xe0e0, 0xf0f0, 0x8080, 0xfefe, 0x0080, 0xfcfc, 0x80c0, 0xf8f8, 0x8000, 0x00c0, 0xfffe, 0xfeff, 0xc000, 0xf0e0, 0xc0e0, 0xfbfb, 0xfcfe, 0xf8f0, 0xfdfd, 0xfffb, 0xe000, @@ -351,8 +351,8 @@ const uint16_t ambe_v_uv_tbl[64] = { 0x1000, 0xe0e1, 0xe0f8, 0xf2f0, 0xf8ff, 0xfafe, 0xfff7, 0xdfdf, }; -/* \brief PRBA[1:2] */ -const float ambe_prba12_tbl[128][2] = { +/*! \brief PRBA[1:2] */ +extern const float ambe_prba12_tbl[128][2] = { { -0.042480f, +0.271484f }, { -0.082031f, +0.219727f }, { -0.579102f, +0.062988f }, @@ -483,8 +483,8 @@ const float ambe_prba12_tbl[128][2] = { { +0.425781f, -0.049316f }, }; -/* \brief PRBA[3:4] */ -const float ambe_prba34_tbl[64][2] = { +/*! \brief PRBA[3:4] */ +extern const float ambe_prba34_tbl[64][2] = { { +0.439453f, +0.273438f }, { +0.307129f, +0.220215f }, { +0.338867f, +0.147949f }, @@ -551,8 +551,8 @@ const float ambe_prba34_tbl[64][2] = { { -0.333496f, -0.238770f }, }; -/* \brief PRBA[5:7] */ -const float ambe_prba57_tbl[128][3] = { +/*! \brief PRBA[5:7] */ +extern const float ambe_prba57_tbl[128][3] = { { +0.012695f, -0.156250f, -0.120605f }, { -0.009277f, -0.090332f, -0.065918f }, { -0.062500f, -0.173340f, -0.151855f }, @@ -683,8 +683,8 @@ const float ambe_prba57_tbl[128][3] = { { -0.042480f, +0.068359f, +0.100586f }, }; -/* \brief HOC for 1st frequency block */ -const float ambe_hoc0_tbl[128][4] = { +/*! \brief HOC for 1st frequency block */ +extern const float ambe_hoc0_tbl[128][4] = { { +0.368652f, -0.230469f, -0.191406f, +0.158203f }, { +0.300781f, -0.079102f, -0.018066f, +0.124512f }, { +0.318848f, -0.202637f, +0.081055f, -0.000977f }, @@ -815,8 +815,8 @@ const float ambe_hoc0_tbl[128][4] = { { -0.461914f, +0.264160f, +0.172363f, -0.184082f }, }; -/* \brief HOC for 2nd frequency block */ -const float ambe_hoc1_tbl[64][4] = { +/*! \brief HOC for 2nd frequency block */ +extern const float ambe_hoc1_tbl[64][4] = { { -0.364258f, +0.365723f, +0.244141f, +0.045410f }, { -0.579102f, +0.200684f, -0.009766f, +0.049316f }, { -0.227051f, +0.341309f, -0.048828f, -0.008301f }, @@ -883,8 +883,8 @@ const float ambe_hoc1_tbl[64][4] = { { +0.332520f, -0.322754f, -0.201172f, -0.001465f }, }; -/* \brief HOC for 3rd frequency block */ -const float ambe_hoc2_tbl[64][4] = { +/*! \brief HOC for 3rd frequency block */ +extern const float ambe_hoc2_tbl[64][4] = { { -0.107422f, +0.202637f, +0.255859f, -0.011719f }, { -0.214844f, -0.538086f, -0.206543f, +0.003418f }, { -0.027832f, -0.366211f, -0.125488f, +0.198730f }, @@ -951,8 +951,8 @@ const float ambe_hoc2_tbl[64][4] = { { +0.104492f, +0.204590f, -0.219238f, +0.086914f }, }; -/* \brief HOC for last frequency block */ -const float ambe_hoc3_tbl[64][4] = { +/*! \brief HOC for last frequency block */ +extern const float ambe_hoc3_tbl[64][4] = { { +0.168457f, +0.110352f, +0.166504f, -0.110840f }, { +0.338379f, +0.063965f, +0.101074f, +0.089844f }, { +0.256836f, -0.126465f, +0.064941f, -0.130371f }, @@ -1019,16 +1019,16 @@ const float ambe_hoc3_tbl[64][4] = { { +1.952637f, +3.729004f, +2.333496f, +3.879395f }, }; -/* \brief Interpolation ratios for subframe 0 magnitude prediction */ -const float ambe_sf0_interp_tbl[4] = { +/*! \brief Interpolation ratios for subframe 0 magnitude prediction */ +extern const float ambe_sf0_interp_tbl[4] = { 0.90f, 0.70f, 0.50f, 0.17f, }; -/* \brief Prediction Error [1:4] for subframe 0 */ -const float ambe_sf0_perr14_tbl[64][4] = { +/*! \brief Prediction Error [1:4] for subframe 0 */ +extern const float ambe_sf0_perr14_tbl[64][4] = { { -0.106445f, +0.011230f, -0.166992f, -0.022461f }, { -0.056641f, +0.166504f, -0.139648f, -0.102051f }, { -0.004883f, +0.052246f, -0.106934f, +0.084961f }, @@ -1095,8 +1095,8 @@ const float ambe_sf0_perr14_tbl[64][4] = { { +0.178223f, -0.077148f, +0.190918f, +0.095215f }, }; -/* \brief Prediction Error [5:8] for subframe 0 */ -const float ambe_sf0_perr58_tbl[32][4] = { +/*! \brief Prediction Error [5:8] for subframe 0 */ +extern const float ambe_sf0_perr58_tbl[32][4] = { { -0.006836f, +0.065430f, +0.135254f, +0.032715f }, { -0.019531f, +0.053223f, +0.054688f, -0.052734f }, { -0.143066f, +0.037598f, +0.059082f, +0.054688f }, diff --git a/src/codec/tone.c b/src/codec/tone.c index 4549f5d..ff9f151 100644 --- a/src/codec/tone.c +++ b/src/codec/tone.c @@ -17,7 +17,7 @@ * along with this program. If not, see <http://www.gnu.org/licenses/>. */ -/*! \addtogroup codec/private +/*! \addtogroup codec_private * @{ */ @@ -35,9 +35,9 @@ /*! \brief Structure describing a dual-frequency tone */ struct tone_desc { - char *name; - int f1; - int f2; + char *name; /*!< \brief Tone description */ + int f1; /*!< \brief Frequency 1 (Hz) */ + int f2; /*!< \brief Frequency 2 (Hz) */ }; /*! \brief DTMF tones descriptions */ |