Audio
Source Coding Module

## Classes

class | itpp::Audio_Stream_Description
| Description of audio stream. More...
class | itpp::SND_In_File
| Class to read audio data from au file. More...
class | itpp::SND_Out_File
| A class to write SND-files (the .au format) More...
class | itpp::SND_IO_File
| A class for doing both input and output of audio samples. More...
class | itpp::Audio_Sample< Audio_Encoding >
| Generic template class for Audio samples. More...
class | itpp::Audio_Sample< enc_mulaw8 >
| uLaw-encoded Audio samples. More...
class | itpp::Audio_Sample< enc_linear8 >
| 8-bit PCM encoded audio samples. More...
class | itpp::Audio_Sample< enc_linear16 >
| 16-bit PCM encoded audio samples More...
class | itpp::Audio_Sample< enc_linear24 >
| 24-bit PCM encoded audio samples. More...
class | itpp::Audio_Sample< enc_linear32 >
| 32-bit PCM encoded audio samples. More...
class | itpp::Audio_Sample< enc_float >
| Audio samples encoded as floats. More...
class | itpp::Audio_Sample< enc_double >
| Audio samples encoded as doubles. More...
class | itpp::Audio_Sample< enc_alaw8 >
| aLaw-encoded Audio samples. More...

## Enumerations

enum | itpp::Audio_Encoding { enc_unknown = 0 , enc_mulaw8 = 1 , enc_alaw8 = 27 , enc_linear8 = 2 , enc_linear16 = 3 , enc_linear24 = 4 , enc_linear32 = 5 , enc_float = 6 , enc_double = 7 }
| Supported encoding types for audio samples. More...

## Functions

vec | itpp::snd_read_channel (const char *fname, int ch=0)
| Read audio channel.
vec | itpp::snd_read_channel (const char *fname, int ch, int len, std::streamoff beg=0)
| Read len audio channel samples starting at position beg.
mat | itpp::snd_read (const char *fname)
| Read audio data.
mat | itpp::snd_read (const char *fname, int len, std::streamoff beg=0)
| Read len audio samples starting at position beg.
bool | itpp::snd_write_channel (const char *fname, const Audio_Stream_Description &descr, const vec &s, int ch=0)
| Write audio channel from vector s using stream description descr.
bool | itpp::snd_write (const char *fname, const Audio_Stream_Description &descr, const mat &s)
| Write audio data.
template<typename T , T max_abs>
T | itpp::limit_audio_sample (double s)
| Helper function for scaling and limiting of audio samples.
template<typename T , T down_scaling>
double | itpp::audio_sample_to_double (T s)
| Helper function for scaling and limiting of audio samples.
std::pair< int16_t, int16_t > | itpp::ulaw_range ()
| G.711 u-Law compressor input range. Returns (min,max) input values in std::pair.
uint8_t | itpp::ulaw_compress (int16_t s)
| G.711 u-Law compression function. Returns encoded value for sample s.
int16_t | itpp::ulaw_expand (uint8_t s)
| G.711 u-Law expansion function. Returns decoded value for previously compressed sample s.Expansion is performed by the table look up.
std::pair< int16_t, int16_t > | itpp::alaw_range ()
| G.711 a-Law compressor input range. Returns (min,max) input values in std::pair.
uint8_t | itpp::alaw_compress (int16_t s)
| G.711 a-Law compression function. Returns encoded value for sample s.
int16_t | itpp::alaw_expand (uint8_t s)
| G.711 u-Law expansion function. Returns decoded value for previously compressed sample s.Expansion is performed by the table look up.

## Detailed Description

# Audio Streams.

Audio streams are used to handle audio files in Sun/NeXT format (the .au format). SND file consists of header followed by the audio samples. Number of channels, samples encoding and sampling rate are stored inside the file header. Header can also contain annotation of variable length describing the stream contents. Library provides Audio_Stream_Description class to describe the audio stream and SND_In_File/SND_Out_File/SND_InOut_File classes to support handling of SND files.

# Representaion of Audio samples.

ITPP supports various types of representation for audio samples:

- 8/16/32-bit PCM encoding formats
- IEEE 754 Floating point formats with single and double precision
- G.711 u-law and A-law encoded samples

# G.711 audio codecs

ITU-T G.711 defines two logarithmic codecs used for PCM audio data. Both codecs are widely used for 64 kbps serial transmission in telephone networks.

Codec algorithms are based on the perceptual properties of the human ear - weak signals are masked by strong ones, so only the MSBs of the original sample can be kept without significant loss of quality.

u-law compression encodes 14-bit input sample as floating point value with 1 bit of sign, 3 bits of exponent and 4 bits of mantissa, representing the MSBs of the magnitude of the original sample.

a-law compression generates output in the same format but operates on 13-bit samples, providing somewhat higher output dynamic range at the expense of larger quantization error [SPRA634].

Codecs differ in particular details of mantissa and exponent encoding (see [G.711] for details). G.191 specification provides reference implementation and test vectors for G.711 codecs.

# G.711 references

- [G711] G.711 : Pulse code modulation (PCM) of voice frequencies; ITU-T Recommendation (11/1988)
- [G191] G.191 : Software tools for speech and audio coding; ITU-T Recommendation (03/2010)
- [SPRA634] Mark A. Castellano, Todd Hiers, Rebecca Ma TMS320C6000 u-Law and A-Law Companding with Software or the McBSP. Application report, Texas Instruments, April 2000.

## Enumeration Type Documentation

## Audio_Encoding

enum itpp::Audio_Encoding

Supported encoding types for audio samples.

Numerical values of these constants correspond to the encoding type identifier in snd file format, introduced by Sun Microsystems.

Definition at line 58 of file audiosample.h.

## Function Documentation

## snd_read_channel() [1/2]

vec itpp::snd_read_channel | ( | const char * | fname,
|  | int | ch = `0`
| ) |  |

inline

Read audio channel.

Definition at line 615 of file audiofile.h.

References itpp::SND_In_File::num_samples(), and itpp::SND_In_File::read_channel().

## snd_read_channel() [2/2]

vec itpp::snd_read_channel | ( | const char * | fname,
|  | int | ch,
|  | int | len,
|  | std::streamoff | beg = `0`
| ) |  |

inline

Read len audio channel samples starting at position beg.

Definition at line 622 of file audiofile.h.

References itpp::SND_In_File::read_channel(), and itpp::SND_In_File::seek_read().

## snd_read() [1/2]

mat itpp::snd_read | ( | const char * | fname | ) |

inline

Read audio data.

Definition at line 630 of file audiofile.h.

References itpp::SND_In_File::num_samples(), and itpp::SND_In_File::read().

## snd_read() [2/2]

mat itpp::snd_read | ( | const char * | fname,
|  | int | len,
|  | std::streamoff | beg = `0`
| ) |  |

inline

Read len audio samples starting at position beg.

Definition at line 637 of file audiofile.h.

References itpp::SND_In_File::read(), and itpp::SND_In_File::seek_read().

## snd_write_channel()

bool itpp::snd_write_channel | ( | const char * | fname,
|  | const Audio_Stream_Description & | descr,
|  | const vec & | s,
|  | int | ch = `0`
| ) |  |

inline

Write audio channel from vector s using stream description descr.

Definition at line 646 of file audiofile.h.

References itpp::SND_Out_File::write_channel().

## snd_write()

bool itpp::snd_write | ( | const char * | fname,
|  | const Audio_Stream_Description & | descr,
|  | const mat & | s
| ) |  |

inline

Write audio data.

Definition at line 653 of file audiofile.h.

References itpp::SND_Out_File::write().

## limit_audio_sample()

template<typename T , T max_abs>

T itpp::limit_audio_sample | ( | double | s | ) |

Helper function for scaling and limiting of audio samples.

This function maps [-1.0, 1.0] doubles to [-max_abs, max_abs] values of type T. Input values are limited before mapping.

Definition at line 71 of file audiosample.h.

## audio_sample_to_double()

template<typename T , T down_scaling>

double itpp::audio_sample_to_double | ( | T | s | ) |

Helper function for scaling and limiting of audio samples.

This function maps [-max_abs, max_abs] values of type T to doubles in [-1.0,1.0] interval

Definition at line 85 of file audiosample.h.

## ulaw_range()

std::pair< int16_t, int16_t > itpp::ulaw_range | ( |  | ) |

inline

G.711 u-Law compressor input range. Returns (min,max) input values in std::pair.

Definition at line 132 of file g711.h.

## ulaw_compress()

uint8_t itpp::ulaw_compress | ( | int16_t | s | ) |

inline

G.711 u-Law compression function. Returns encoded value for sample s.

Definition at line 143 of file g711.h.

References itpp::sign().

## ulaw_expand()

int16_t itpp::ulaw_expand | ( | uint8_t | s | ) |

inline

G.711 u-Law expansion function. Returns decoded value for previously compressed sample s.Expansion is performed by the table look up.

Definition at line 176 of file g711.h.

## alaw_range()

std::pair< int16_t, int16_t > itpp::alaw_range | ( |  | ) |

inline

G.711 a-Law compressor input range. Returns (min,max) input values in std::pair.

Definition at line 182 of file g711.h.

## alaw_compress()

uint8_t itpp::alaw_compress | ( | int16_t | s | ) |

inline

G.711 a-Law compression function. Returns encoded value for sample s.

Definition at line 192 of file g711.h.

References itpp::sign().

## alaw_expand()

int16_t itpp::alaw_expand | ( | uint8_t | s | ) |

inline

G.711 u-Law expansion function. Returns decoded value for previously compressed sample s.Expansion is performed by the table look up.

Definition at line 226 of file g711.h.

Generated on Mon Jun 10 2024 11:49:31 for IT++ by Doxygen 1.9.8