osmo-gmr: AMBE vocoder - internal API

osmo-gmr 0.2.104-2b98 Osmocom GMR-1

Files | Data Structures | Macros | Enumerations | Functions | Variables
AMBE vocoder - internal API
AMBE vocoder

## Files
file | ambe.c
| Osmocom GMR-1 AMBE internal API.
file | frame.c
| Osmocom GMR-1 AMBE speech parameters to/from frame.
file | math.c
| Osmocom GMR-1 AMBE vocoder math functions.
file | private.h
| Osmocom GMR-1 AMBE vocoder private header.
file | synth.c
| Osmocom GMR-1 AMBE vocoder speech synthesis.
file | tables.c
| Osmocom GMR-1 AMBE vocoder tables.
file | tone.c
| Osmocom GMR-1 AMBE vocoder tone frames handling.

## Data Structures
struct | ambe_raw_params
| AMBE encoded frame raw parameters. More...
struct | ambe_subframe
| AMBE subframe parameters. More...
struct | ambe_synth
| AMBE synthesizer state. More...
struct | ambe_decoder
| AMBE decoder state. More...
struct | tone_desc
| Structure describing a dual-frequency tone. More...

## Macros
#define | AMBE_RATE 8000
| AMBE sample rate (Hz)
#define | M_PIf (3.141592653589793f)
| Value of pi as a float.

## Enumerations
enum | ambe_frame_type { AMBE_SPEECH , AMBE_SILENCE , AMBE_TONE }
| AMBE possible frame types. More...

## Functions
void | ambe_decode_init (struct ambe_decoder *dec)
| Initializes decoder state. More...
void | ambe_decode_fini (struct ambe_decoder *dec)
| Release all resources associated with a decoder. More...
int | ambe_decode_frame (struct ambe_decoder *dec, int16_t *audio, int N, const uint8_t *frame, int bad)
| Decodes an AMBE frame to audio. More...
int | ambe_decode_dtx (struct ambe_decoder *dec, int16_t *audio, int N)
| Generates audio for DTX period. More...
void | ambe_frame_unpack_raw (struct ambe_raw_params *rp, const uint8_t *frame)
| Unpack a frame into its raw encoded parameters. More...
void | ambe_frame_decode_params (struct ambe_subframe *sf, struct ambe_subframe *sf_prev, struct ambe_raw_params *rp)
| Decodes the speech parameters for both subframes from raw params. More...
void | ambe_subframe_expand (struct ambe_subframe *sf)
| Expands the decoded subframe params to prepare for synthesis. More...
float | cosf_fast (float angle)
| Fast Cosinus approximation using a simple table. More...
float | sinf_fast (float angle)
| Fast Sinus approximation using a simple table. More...
void | ambe_fdct (float *out, float *in, int N, int M)
| Forward Discrete Cosine Transform (fDCT) More...
void | ambe_idct (float *out, float *in, int N, int M)
| Inverse Discrete Cosine Transform (iDCT) More...
void | ambe_fdft_fc (float *out_i, float *out_q, float *in, int N, int M)
| Forward Discrete Fourrier Transform (float->complex) More...
void | ambe_idft_cf (float *out, float *in_i, float *in_q, int N, int M)
| Inverse Discret Fourrier Transform (complex->float) More...
void | ambe_synth_init (struct ambe_synth *synth)
| Initialized Synthesizer state. More...
void | ambe_synth_enhance (struct ambe_synth *synth, struct ambe_subframe *sf)
| Apply the spectral magnitude enhancement on the subframe. More...
void | ambe_synth_audio (struct ambe_synth *synth, int16_t *audio, struct ambe_subframe *sf, struct ambe_subframe *sf_prev)
| Generate audio for a given subframe. More...
int | ambe_decode_tone (struct ambe_decoder *dec, int16_t *audio, int N, const uint8_t *frame)
| Decodes an AMBE tone frame. More...

## Variables
const uint8_t | ambe_hpg_tbl [48][4]
| Number of harmonics per group for a given L (starts at L=9)
const float | ambe_gain_tbl [256][2]
| Gain (subframe 0, subframe 1)
const uint16_t | ambe_v_uv_tbl [64]
| V/UV decisions (subframe 0 = low byte. MSBs = low freq)
const float | ambe_prba12_tbl [128][2]
| PRBA[1:2].
const float | ambe_prba34_tbl [64][2]
| PRBA[3:4].
const float | ambe_prba57_tbl [128][3]
| PRBA[5:7].
const float | ambe_hoc0_tbl [128][4]
| HOC for 1st frequency block.
const float | ambe_hoc1_tbl [64][4]
| HOC for 2nd frequency block.
const float | ambe_hoc2_tbl [64][4]
| HOC for 3rd frequency block.
const float | ambe_hoc3_tbl [64][4]
| HOC for last frequency block.
const float | ambe_sf0_interp_tbl [4]
| Interpolation ratios for subframe 0 magnitude prediction.
const float | ambe_sf0_perr14_tbl [64][4]
| Prediction Error [1:4] for subframe 0.
const float | ambe_sf0_perr58_tbl [32][4]
| Prediction Error [5:8] for subframe 0.
const uint8_t | ambe_hpg_tbl [48][4]
| Number of harmonics per group for a given L (starts at L=9)
const float | ambe_gain_tbl [256][2]
| Gain (subframe 0, subframe 1)
const uint16_t | ambe_v_uv_tbl [64]
| V/UV decisions (subframe 0 = low byte. MSBs = low freq) More...
const float | ambe_prba12_tbl [128][2]
| PRBA[1:2].
const float | ambe_prba34_tbl [64][2]
| PRBA[3:4].
const float | ambe_prba57_tbl [128][3]
| PRBA[5:7].
const float | ambe_hoc0_tbl [128][4]
| HOC for 1st frequency block.
const float | ambe_hoc1_tbl [64][4]
| HOC for 2nd frequency block.
const float | ambe_hoc2_tbl [64][4]
| HOC for 3rd frequency block.
const float | ambe_hoc3_tbl [64][4]
| HOC for last frequency block.
const float | ambe_sf0_interp_tbl [4]
| Interpolation ratios for subframe 0 magnitude prediction. More...
const float | ambe_sf0_perr14_tbl [64][4]
| Prediction Error [1:4] for subframe 0.
const float | ambe_sf0_perr58_tbl [32][4]
| Prediction Error [5:8] for subframe 0.

## Detailed Description

## Enumeration Type Documentation

## ◆ ambe_frame_type

enum ambe_frame_type

AMBE possible frame types.

Enumerator
AMBE_SPEECH | Speech frame.
AMBE_SILENCE | Silence indication frame.
AMBE_TONE | Tone frame

## Function Documentation

## ◆ ambe_decode_dtx()

int ambe_decode_dtx | ( | struct ambe_decoder * | dec,
|  | int16_t * | audio,
|  | int | N
| ) |  |

Generates audio for DTX period.

Parameters

  [in] | dec | Decoder state structure
  [out] | audio | Output audio buffer
  [in] | N | number of audio samples to produce (152..168)

Referenced by gmr1_codec_decode_dtx().

## ◆ ambe_decode_fini()

void ambe_decode_fini | ( | struct ambe_decoder * | dec | ) |

Release all resources associated with a decoder.

Parameters

  [in] | dec | Decoder state structure

Referenced by gmr1_codec_release().

## ◆ ambe_decode_frame()

int ambe_decode_frame | ( | struct ambe_decoder * | dec,
|  | int16_t * | audio,
|  | int | N,
|  | const uint8_t * | frame,
|  | int | bad
| ) |  |

Decodes an AMBE frame to audio.

Parameters

  [in] | dec | Decoder state structure
  [out] | audio | Output audio buffer
  [in] | N | number of audio samples to produce (152..168)
  [in] | frame | Frame data (10 bytes = 80 bits)
  [in] | bad | Bad Frame Indicator. Set to 1 if frame is corrupt

Returns
  0 for success. Negative error code otherwise.

Referenced by gmr1_codec_decode_frame().

## ◆ ambe_decode_init()

void ambe_decode_init | ( | struct ambe_decoder * | dec | ) |

Initializes decoder state.

Parameters

  [in] | dec | Decoder state structure

References ambe_synth_init(), ambe_subframe::f0, ambe_subframe::L, M_PIf, ambe_decoder::sf_prev, ambe_decoder::synth, and ambe_subframe::w0.

Referenced by gmr1_codec_alloc().

## ◆ ambe_decode_tone()

int ambe_decode_tone | ( | struct ambe_decoder * | dec,
|  | int16_t * | audio,
|  | int | N,
|  | const uint8_t * | frame
| ) |  |

Decodes an AMBE tone frame.

Parameters

  [in] | dec | AMBE decoder state
  [out] | audio | Output audio buffer
  [in] | N | number of audio samples to produce (152..168)
  [in] | frame | Frame data (10 bytes = 80 bits). Must be tone frame !

Returns
  0 for success. -EINVAL if frame was invalid.

## ◆ ambe_fdct()

void ambe_fdct | ( | float * | out,
|  | float * | in,
|  | int | N,
|  | int | M
| ) |  |

Forward Discrete Cosine Transform (fDCT)

Parameters

  [out] | out | fDCT result buffer (freq domain, M elements)
  [in] | in | fDCT input buffer (time domain, N elements)
  [in] | N | Number of points of the DCT
  [in] | M | Limit to the number of frequency components (M <= N)

References cosf_fast(), and M_PIf.

## ◆ ambe_fdft_fc()

void ambe_fdft_fc | ( | float * | out_i,
|  | float * | out_q,
|  | float * | in,
|  | int | N,
|  | int | M
| ) |  |

Forward Discrete Fourrier Transform (float->complex)

Parameters

  [out] | out_i | Real component result buffer (freq domain, N/2+1 elements)
  [out] | out_q | Imag component result buffer (freq domain, N/2+1 elements)
  [in] | in | Input buffer (time domain, M elements)
  [in] | N | Number of points of the DFT
  [in] | M | Limit to to the number of available time domain elements

Since the input is float, the result is symmetric and so only one side is computed. The output index 0 is DC.

References cosf_fast(), M_PIf, sinf_fast(), and ts.

## ◆ ambe_frame_decode_params()

void ambe_frame_decode_params | ( | struct ambe_subframe * | sf,
|  | struct ambe_subframe * | sf_prev,
|  | struct ambe_raw_params * | rp
| ) |  |

Decodes the speech parameters for both subframes from raw params.

Parameters

  [out] | sf | Array of 2 subframes data to fill-in
  [in] | sf_prev | Previous subframe 1 data
  [in] | rp | Encoded frame raw parameters

References ambe_subframe::f0, ambe_subframe::f0log, and ambe_raw_params::pitch.

## ◆ ambe_frame_unpack_raw()

void ambe_frame_unpack_raw | ( | struct ambe_raw_params * | rp,
|  | const uint8_t * | frame
| ) |  |

Unpack a frame into its raw encoded parameters.

Parameters

  [out] | rp | Encoded frame raw parameters to unpack into
  [in] | frame | Frame data (10 bytes = 80 bits)

References ambe_raw_params::pitch.

## ◆ ambe_idct()

void ambe_idct | ( | float * | out,
|  | float * | in,
|  | int | N,
|  | int | M
| ) |  |

Inverse Discrete Cosine Transform (iDCT)

Parameters

  [out] | out | iDCT result buffer (time domain, N elements)
  [in] | in | iDCT input buffer (freq domain, M elements)
  [in] | N | Number of points of the DCT
  [in] | M | Limit to the number of frequency components (M <= N)

References cosf_fast(), and M_PIf.

## ◆ ambe_idft_cf()

void ambe_idft_cf | ( | float * | out,
|  | float * | in_i,
|  | float * | in_q,
|  | int | N,
|  | int | M
| ) |  |

Inverse Discret Fourrier Transform (complex->float)

Parameters

  [out] | out | Result buffer (time domain, M
  [in] | in_i | Real component input buffer (freq domain, N/2+1 elements)
  [in] | in_q | Imag component input buffer (freq domain, N/2+1 elements)
  [in] | N | Number of points of the DFT
  [in] | M | Limit to the number of time domain elements to generate

The input is assumed to be symmetric and so only N/2+1 inputs are needed. DC component must be input index 0.

References cosf_fast(), M_PIf, sinf_fast(), and ts.

## ◆ ambe_subframe_expand()

void ambe_subframe_expand | ( | struct ambe_subframe * | sf | ) |

Expands the decoded subframe params to prepare for synthesis.

Parameters

  [in] | sf | The subframe to expand

References ambe_subframe::f0, ambe_subframe::L, M_PIf, ambe_subframe::Ml, ambe_subframe::Mlog, ambe_subframe::v_uv, ambe_subframe::Vl, and ambe_subframe::w0.

## ◆ ambe_synth_audio()

void ambe_synth_audio | ( | struct ambe_synth * | synth,
|  | int16_t * | audio,
|  | struct ambe_subframe * | sf,
|  | struct ambe_subframe * | sf_prev
| ) |  |

Generate audio for a given subframe.

Parameters

  [in] | synth | Synthesizer state structure
  [out] | audio | Result buffer (80 samples)
  [in] | sf | Expanded subframe data for current subframe
  [in] | sf_prev | Expanded subframe data for prevous subframe

## ◆ ambe_synth_enhance()

void ambe_synth_enhance | ( | struct ambe_synth * | synth,
|  | struct ambe_subframe * | sf
| ) |  |

Apply the spectral magnitude enhancement on the subframe.

Parameters

  [in] | synth | Synthesizer state structure
  [in] | sf | Expanded subframe data for subframe to enhance

References cosf_fast(), ambe_subframe::L, M_PIf, ambe_subframe::Ml, ambe_synth::SE, and ambe_subframe::w0.

## ◆ ambe_synth_init()

void ambe_synth_init | ( | struct ambe_synth * | synth | ) |

Initialized Synthesizer state.

Parameters

  [out] | synth | The structure to reset

References ambe_synth::u_prev.

Referenced by ambe_decode_init().

## ◆ cosf_fast()

float cosf_fast | ( | float | angle | ) |

Fast Cosinus approximation using a simple table.

Parameters

  [in] | angle | The angle value

Returns
  The cosinus of the angle

References M_PIf.

Referenced by ambe_fdct(), ambe_fdft_fc(), ambe_idct(), ambe_idft_cf(), and ambe_synth_enhance().

## ◆ sinf_fast()

float sinf_fast | ( | float | angle | ) |

Fast Sinus approximation using a simple table.

Parameters

  [in] | angle | The angle value

Returns
  The sinus of the angle

References M_PIf.

Referenced by ambe_fdft_fc(), and ambe_idft_cf().

## Variable Documentation

## ◆ ambe_sf0_interp_tbl

const float ambe_sf0_interp_tbl[4]

Initial value:
= {
0.90f,
0.70f,
0.50f,
0.17f,
}

Interpolation ratios for subframe 0 magnitude prediction.

## ◆ ambe_v_uv_tbl

const uint16_t ambe_v_uv_tbl[64]

Initial value:
= {
0x0000, 0xffff, 0xc0c0, 0xe0e0, 0xf0f0, 0x8080, 0xfefe, 0x0080,
0xfcfc, 0x80c0, 0xf8f8, 0x8000, 0x00c0, 0xfffe, 0xfeff, 0xc000,
0xf0e0, 0xc0e0, 0xfbfb, 0xfcfe, 0xf8f0, 0xfdfd, 0xfffb, 0xe000,
0xe0f0, 0xfcff, 0xfdff, 0xe0c0, 0xfffc, 0xf0f8, 0xfefc, 0xfffd,
0xf8fc, 0xfcf8, 0xfcfd, 0x4000, 0xf0c0, 0xf9f9, 0xfbff, 0xefef,
0xf3f3, 0xc080, 0xf0e0, 0xfff8, 0xf0fc, 0xf1f1, 0x0040, 0xc0d0,
0xc0f0, 0xf7f7, 0xfaf8, 0xfafa, 0xfcf0, 0xfef8, 0x00e0, 0x0100,
0x1000, 0xe0e1, 0xe0f8, 0xf2f0, 0xf8ff, 0xfafe, 0xfff7, 0xdfdf,
}

V/UV decisions (subframe 0 = low byte. MSBs = low freq)