Bayonne2 / Common C++ 2 Framework: ost::AudioCodec Class Reference

Test if the audio encoding format must be packetized (that is, has irregular sized frames) and must be processed only through buffered codecs. More...

static bool isMono (Encoding encoding)

Test if the audio encoding format is a mono format. More...

static bool isStereo (Encoding encoding)

Test if the audio encoding format is a stereo format. More...

static Rate getRate (Encoding encoding)

Return default sample rate associated with the specified audio encoding format. More...

static Rate getRate (Encoding e, Rate request)

Return optional rate setting effect. More...

static timeout_t getFraming (Encoding encoding, timeout_t timeout=0)

Return frame timing for an audio encoding format. More...

static timeout_t getFraming (Info &info, timeout_t timeout=0)

Return frame time for an audio source description. More...

static bool isEndian (Encoding encoding)

Test if the endian byte order of the encoding format is different from the machine's native byte order. More...

static bool isEndian (Info &info)

Test if the endian byte order of the audio source description is different from the machine's native byte order. More...

static bool swapEndian (Encoding encoding, void *buffer, unsigned number)

Optionally swap endian of audio data if the encoding format endian byte order is different from the machine's native endian. More...

static bool swapEndian (Info &info, void *buffer, unsigned number)

Optionally swap endian of audio data if the audio source description byte order is different from the machine's native endian byte order. More...

static void swapEncoded (Info &info, Encoded data, size_t bytes)

Optionally swap endian of encoded audio data based on the audio encoding type, and relationship to native byte order. More...

static Level getImpulse (Encoding encoding, void *buffer, unsigned number)

Get the energey impulse level of a frame of audio data. More...

static Level getImpulse (Info &info, void *buffer, unsigned number=0)

Get the energey impulse level of a frame of audio data. More...

static Level getPeak (Encoding encoding, void *buffer, unsigned number)

Get the peak (highest energy) level found in a frame of audio data. More...

static Level getPeak (Info &info, void *buffer, unsigned number=0)

Get the peak (highest energy) level found in a frame of audio data. More...

static void toTimestamp (timeout_t duration, char *address, size_t size)

Provide ascii timestamp representation of a timeout value. More...

static timeout_t toTimeout (const char *timestamp)

Convert ascii timestamp representation to a timeout number. More...

static int getFrame (Encoding encoding, int samples=0)

Returns the number of bytes in a sample frame for the given encoding type, rounded up to the nearest integer. More...

static int getCount (Encoding encoding)

Returns the number of samples in all channels for a frame in the given encoding. More...

static unsigned long toSamples (Encoding encoding, size_t bytes)

Compute byte counts of audio data into number of samples based on the audio encoding format used. More...

static unsigned long toSamples (Info &info, size_t bytes)

Compute byte counts of audio data into number of samples based on the audio source description used. More...

static size_t toBytes (Info &info, unsigned long number)

Compute the number of bytes a given number of samples in a given audio encoding will occupy. More...

static size_t toBytes (Encoding encoding, unsigned long number)

Compute the number of bytes a given number of samples in a given audio encoding will occupy. More...

static void fill (unsigned char *address, int number, Encoding encoding)

Fill an audio buffer with "empty" (silent) audio data, based on the audio encoding format. More...

static bool loadPlugin (const char *path)

Load a dso plugin (codec plugin), used internally... More...

static size_t maxFramesize (Info &info)

Maximum framesize for a given coding that may be needed to store a result. More...

Static Public Attributes

static const unsigned ndata

Protected Member Functions

AudioCodec ()

virtual AudioCodec * getByFormat (const char *format)

often used to create a "new" codec of a subtype based on encoding format, default returns the current codec entity. More...

virtual AudioCodec * getByInfo (Info &info)

get a codec by audio source info descriptor. More...

Protected Attributes

AudioCodec * next

Encoding encoding

const char * name

Info info

Static Protected Attributes

static AudioCodec * first

Detailed Description

The codec class is a virtual used for transcoding audio samples between linear frames (or other known format) and an encoded "sample" buffer.

This class is only abstract and describes the core interface for loadable codec modules. This class is normally merged with AudioSample. A derived AudioCodecXXX will typically include a AudioRegisterXXX static class to automatically initialize and register the codec with the codec registry.

Author: David Sugar dyfet.nosp@m.@ost.nosp@m.el.co.nosp@m.m process codec interface.

Definition at line 1733 of file audio2.h.

Member Typedef Documentation

typedef enum DeviceMode ost::Audio::DeviceMode

inherited

Definition at line 247 of file audio2.h.

typedef unsigned char* ost::Audio::Encoded

inherited

Definition at line 143 of file audio2.h.

typedef enum Encoding ost::Audio::Encoding

inherited

Definition at line 225 of file audio2.h.

typedef enum Error ost::Audio::Error

inherited

Definition at line 274 of file audio2.h.

typedef enum Format ost::Audio::Format

inherited

Definition at line 237 of file audio2.h.

typedef int16_t ost::Audio::Level

inherited

Definition at line 101 of file audio2.h.

typedef int16_t* ost::Audio::Linear

inherited

Definition at line 103 of file audio2.h.

typedef enum Mode ost::Audio::Mode

inherited

Definition at line 175 of file audio2.h.

typedef enum Rate ost::Audio::Rate

inherited

Definition at line 157 of file audio2.h.

typedef int16_t ost::Audio::Sample

inherited

Definition at line 102 of file audio2.h.

typedef int16_t ost::Audio::snd16_t

inherited

Definition at line 99 of file audio2.h.

typedef int32_t ost::Audio::snd32_t

inherited

Definition at line 100 of file audio2.h.

typedef unsigned long ost::Audio::timeout_t

inherited

Definition at line 104 of file audio2.h.

Member Enumeration Documentation

enum ost::Audio::DeviceMode

inherited

Audio device access mode.

Enumerator
PLAY
RECORD
PLAYREC

Definition at line 242 of file audio2.h.

enum ost::Audio::Encoding

inherited

Audio encoding formats.

Enumerator
unknownEncoding
g721ADPCM
g722Audio
g722_7bit
g722_6bit
g723_2bit
g723_3bit
g723_5bit
gsmVoice
msgsmVoice
mulawAudio
alawAudio
mp1Audio
mp2Audio
mp3Audio
okiADPCM
voxADPCM
sx73Voice
sx96Voice
cdaStereo
cdaMono
pcm8Stereo
pcm8Mono
pcm16Stereo
pcm16Mono
pcm32Stereo
pcm32Mono
speexVoice
speexAudio
g729Audio
ilbcAudio
speexUltra
speexNarrow
speexWide
g723_4bit

Definition at line 180 of file audio2.h.

enum ost::Audio::Error

inherited

Audio error conditions.

Enumerator
errSuccess
errReadLast
errNotOpened
errEndOfFile
errStartOfFile
errRateInvalid
errEncodingInvalid
errReadInterrupt
errWriteInterrupt
errReadFailure
errWriteFailure
errReadIncomplete
errWriteIncomplete
errRequestInvalid
errTOCFailed
errStatFailed
errInvalidTrack
errPlaybackFailed
errNotPlaying
errNoCodec

Definition at line 252 of file audio2.h.

enum ost::Audio::Format

inherited

Audio container file format.

Enumerator
raw
snd
riff
mpeg
wave

Definition at line 230 of file audio2.h.

enum ost::Audio::Mode

inherited

File processing mode, whether to skip missing files, etc.

Enumerator
modeRead
modeReadAny
modeReadOne
modeWrite
modeCache
modeInfo
modeFeed
modeAppend
modeCreate

Definition at line 162 of file audio2.h.

enum ost::Audio::Rate

inherited

Audio encoding rate, samples per second.

Enumerator
rateUnknown
rate6khz
rate8khz
rate16khz
rate32khz
rate44khz

Definition at line 148 of file audio2.h.

Constructor & Destructor Documentation

ost::AudioCodec::AudioCodec ( )

protected

ost::AudioCodec::AudioCodec ( const char * name,

Encoding encoding

)

Base for codecs, create a named coded of a specific encoding.

Parameters: name of codec.

encoding type of codec.

virtual ost::AudioCodec::~AudioCodec ( )

inlinevirtual

Definition at line 1772 of file audio2.h.

Member Function Documentation

virtual unsigned ost::AudioCodec::decode ( Linear buffer,

void * source,

unsigned number = 0

)

pure virtual

Decode the sample frame into linear samples.

Returns: number of bytes scanned or returned

Parameters: buffer sample buffer to save linear samples into.

source for encoded data.

number of samples to extract.

virtual unsigned ost::AudioCodec::decodeBuffered ( Linear buffer,

Encoded source,

unsigned len

)

virtual

Buffer and decode data into linear samples.

This is needed for audio formats that have irregular packet sizes.

Returns: number of samples actually decoded.

Parameters: destination for decoded data.

source for encoded data.

number of bytes being sent.

virtual unsigned ost::AudioCodec::encode ( Linear buffer,

void * dest,

unsigned number = 0

)

pure virtual

Encode a linear sample frame into the codec sample buffer.

Returns: number of bytes written.

Parameters: buffer linear sample buffer to use.

dest buffer to store encoded results.

number of samples.

virtual unsigned ost::AudioCodec::encodeBuffered ( Linear Buffer,

Encoded dest,

unsigned number

)

virtual

Encode linear samples buffered into the coded.

Returns: number of bytes written or 0 if incomplete.

Parameters: buffer linear samples to post.

destination of encoded audio.

number of samples being buffered.

static void ost::AudioCodec::endCodec ( AudioCodec * codec )

static

End use of a requested codec.

If constructed then will be deleted.

Parameters: codec pointer to getCodec returned coded pointer.

static void ost::Audio::fill ( unsigned char * address,

int number,

Encoding encoding

)

staticinherited

Fill an audio buffer with "empty" (silent) audio data, based on the audio encoding format.

Parameters: address of data to fill.

number of samples to fill.

encoding format of data.

virtual AudioCodec* ost::AudioCodec::getByFormat ( const char * format )

inlineprotectedvirtual

often used to create a "new" codec of a subtype based on encoding format, default returns the current codec entity.

Returns: pointer to an active codec or NULL if not found.

Parameters: format name from spd.

Definition at line 1751 of file audio2.h.

virtual AudioCodec* ost::AudioCodec::getByInfo ( Info & info )

inlineprotectedvirtual

get a codec by audio source info descriptor.

Returns: pointer to an active codec or NULL if not found.

Parameters: info audio source descriptor.

Definition at line 1760 of file audio2.h.

static AudioCodec* ost::AudioCodec::getCodec ( Encoding encoding,

const char * format = NULL,

bool loaded = false

)

static

Get the codec base class for accessing a specific derived codec identified by encoding type and optional spd info.

Returns: pointer to codec for processing.

Parameters: encoding format requested.

format spd options to pass to codec being created.

loaded true to load if not already in memory.

static AudioCodec* ost::AudioCodec::getCodec ( Info & info,

bool loaded = false

)

static

Get the codec base class for accessing a specific derived codec identified by audio source descriptor.

Returns: pointer to codec for processing.

Parameters: info source descriptor for codec being requested.

loaded true to load codec if not already in memory.

static const char* ost::Audio::getCodecPath ( void )

staticinherited

Get pathname to where loadable codec modules are stored.

Returns: file path to loadable codecs.

static int ost::Audio::getCount ( Encoding encoding )

staticinherited

Returns the number of samples in all channels for a frame in the given encoding.

For example, pcm32Stereo has a frame size of 8 bytes: Note that different codecs have different definitions of a frame - for example, compressed encodings have a rather large frame size relative to the sample size due to the way bytes are fed to the decompression engine.

Parameters: encoding The encoding to calculate the frame sample count for.

Returns: samples The number of samples in a frame of the given encoding.

static AudioDevice* ost::Audio::getDevice ( unsigned device = 0,

DeviceMode mode = PLAY

)

staticinherited

Get a audio device object that can be used to play or record audio.

This is normally a local soundcard, though an abstract base class is returned, so the underlying device may be different.

Parameters: device index or 0 for default audio device.

mode of device; play, record, or full duplex.

Returns: pointer to abstract audio device object interface class.

static Encoding ost::Audio::getEncoding ( const char * name )

staticinherited

Get the audio encoding format that is specified by a short ascii name.

This will either accept names like those returned from getName(), or .xxx file extensions, and return the audio encoding type associated with the name or extension.

Parameters: name of encoding or file extension.

Returns: audio encoding format.

See Also: getName

virtual unsigned ost::AudioCodec::getEstimated ( void )

virtual

Get estimated data required for buffered operations.

Returns: estimated number of bytes required for decode.

static const char* ost::Audio::getExtension ( Encoding encoding )

staticinherited

Get the preferred file extension name to use for a given audio encoding type.

Parameters: encoding format.

Returns: ascii file extension to use.

static int ost::Audio::getFrame ( Encoding encoding,

int samples = 0

)

staticinherited

Returns the number of bytes in a sample frame for the given encoding type, rounded up to the nearest integer.

A frame is defined as the minimum number of bytes necessary to create a point or points in the output waveform for all output channels. For example, 16-bit mono PCM has a frame size of two (because those two bytes constitute a point in the output waveform). GSM has it's own definition of a frame which involves decompressing a sequence of bytes to determine the final points on the output waveform. The minimum number of bytes you can feed to the decompression engine is 32.5 (260 bits), so this function will return 33 (because we round up) given an encoding type of GSM. Other compressed encodings will return similar results. Be prepared to deal with nonintuitive return values for rare encodings.

Parameters: encoding The encoding type to get the frame size for.

samples Reserved. Use zero.

Returns: The number of bytes in a frame for the given encoding.

static timeout_t ost::Audio::getFraming ( Encoding encoding,

timeout_t timeout = 0

)

staticinherited

Return frame timing for an audio encoding format.

Returns: frame time to use in milliseconds.

Parameters: encoding of frame to get timing segment for.

timeout of frame time segment to request.

static timeout_t ost::Audio::getFraming ( Info & info,

timeout_t timeout = 0

)

staticinherited

Return frame time for an audio source description.

Returns: frame time to use in milliseconds.

Parameters: info descriptor of frame encoding to get timing segment for.

timeout of frame time segment to request.

static Level ost::Audio::getImpulse ( Encoding encoding,

void * buffer,

unsigned number

)

staticinherited

Get the energey impulse level of a frame of audio data.

Returns: impulse energy level of audio data.

Parameters: encoding format of data to examine.

buffer of audio data to examine.

number of audio samples to examine.

static Level ost::Audio::getImpulse ( Info & info,

void * buffer,

unsigned number = 0

)

staticinherited

Get the energey impulse level of a frame of audio data.

Returns: impulse energy level of audio data.

Parameters: info encoding source description object.

buffer of audio data to examine.

number of audio samples to examine.

virtual Level ost::AudioCodec::getImpulse ( void * buffer,

unsigned number = 0

)

virtual

Get the impulse energy level of a frame of X samples in the specified codec format.

Returns: average impulse energy of frame (sumnation).

Parameters: buffer of encoded samples.

number of encoded samples.

Info ost::AudioCodec::getInfo ( void )

inline

Get an info description for this codec.

Returns: info.

Definition at line 1922 of file audio2.h.

static const char* ost::Audio::getMIME ( Info & info )

staticinherited

Get the mime descriptive type for a given Audio encoding description, usually retrieved from a newly opened audio file.

Parameters: info source description object

Returns: text of mime type to use for this audio source.

static Encoding ost::Audio::getMono ( Encoding encoding )

staticinherited

Get the mono encoding format associated with the given format.

Parameters: encoding format.

Returns: associated mono audio encoding format.

static const char* ost::Audio::getName ( Encoding encoding )

staticinherited

Get the short ascii description used for the given audio encoding type.

Parameters: encoding format.

Returns: ascii name of encoding format.

virtual unsigned ost::AudioCodec::getPacket ( Encoded destination,

Encoded data,

unsigned size

)

virtual

Get a packet of data rather than decode.

This is tied with getEstimated.

Returns: size of data packet or 0 if not complete.

Parameters: destination to save.

data to push into buffer.

number of bytes to push.

static Level ost::Audio::getPeak ( Encoding encoding,

void * buffer,

unsigned number

)

staticinherited

Get the peak (highest energy) level found in a frame of audio data.

Returns: peak energy level found in data.

Parameters: encoding format of data.

buffer of audio data.

number of samples to examine.

static Level ost::Audio::getPeak ( Info & info,

void * buffer,

unsigned number = 0

)

staticinherited

Get the peak (highest energy) level found in a frame of audio data.

Returns: peak energy level found in data.

Parameters: info description object of audio data.

buffer of audio data.

number of samples to examine.

virtual Level ost::AudioCodec::getPeak ( void * buffer,

unsigned number = 0

)

virtual

Get the peak energy level within the frame of X samples.

Returns: peak energy impulse in frame (largest).

Parameters: buffer of encoded samples.

number of encoded samples.

static Rate ost::Audio::getRate ( Encoding encoding )

staticinherited

Return default sample rate associated with the specified audio encoding format.

Returns: sample rate for audio data.

Parameters: encoding format.

static Rate ost::Audio::getRate ( Encoding e,

Rate request

)

staticinherited

Return optional rate setting effect.

Many codecs are fixed rate.

Returns: result rate for audio date.

Parameters: encoding format.

requested rate.

virtual unsigned ost::AudioCodec::getRequired ( void )

virtual

get required samples for encoding.

Returns: required number of samples for encoder buffer.

static Encoding ost::Audio::getStereo ( Encoding encoding )

staticinherited

Get the stereo encoding format associated with the given format.

Parameters: encoding format being tested for stereo.

Returns: associated stereo audio encoding format.

static bool ost::Audio::hasDevice ( unsigned device = 0 )

staticinherited

Test for the presense of a specified (indexed) audio device.

This is normally used to test for local soundcard access.

Parameters: device index or 0 for default audio device.

Returns: true if device exists.

static bool ost::Audio::isBuffered ( Encoding encoding )

staticinherited

Test if the audio encoding format must be packetized (that is, has irregular sized frames) and must be processed only through buffered codecs.

Returns: true if packetized audio.

Parameters: encoding format.

static bool ost::Audio::isEndian ( Encoding encoding )

staticinherited

Test if the endian byte order of the encoding format is different from the machine's native byte order.

Returns: true if endian format is different.

Parameters: encoding format.

static bool ost::Audio::isEndian ( Info & info )

staticinherited

Test if the endian byte order of the audio source description is different from the machine's native byte order.

Returns: true if endian format is different.

Parameters: info source description object.

static bool ost::Audio::isLinear ( Encoding encoding )

staticinherited

Test if the audio encoding format is a linear one.

Returns: true if encoding format is linear audio data.

Parameters: encoding format.

static bool ost::Audio::isMono ( Encoding encoding )

staticinherited

Test if the audio encoding format is a mono format.

Returns: true if encoding format is mono audio data.

Parameters: encoding format.

virtual bool ost::AudioCodec::isSilent ( Level threashold,

void * buffer,

unsigned number = 0

)

virtual

Signal if the current audio frame is silent.

This can be deterimed either by an impulse computation, or, in some cases, some codecs may signal and flag silent packets.

Returns: true if silent

Parameters: threashold to use if not signaled.

buffer of encoded samples.

number of encoded samples.

static bool ost::Audio::isStereo ( Encoding encoding )

staticinherited

Test if the audio encoding format is a stereo format.

Returns: true if encoding format is stereo audio data.

Parameters: encoding format.

static bool ost::AudioCodec::load ( const char * name )

static

Load a named codec set into process memory.

Returns: true if successful.

Parameters: name of codec set to load.

static bool ost::AudioCodec::load ( Encoding encoding )

static

Find and load a codec file by it's encoding type.

Converts the type into a codec name and invokes the other loader...

Returns: true if successful.

Parameters: encoding type for file.

static bool ost::Audio::loadPlugin ( const char * path )

staticinherited

Load a dso plugin (codec plugin), used internally...

Returns: true if loaded.

Parameters: path to codec.

static size_t ost::Audio::maxFramesize ( Info & info )

staticinherited

Maximum framesize for a given coding that may be needed to store a result.

Parameters: info source description object.

Returns: maximum possible frame size to allocate for encoded data.

static void ost::Audio::swapEncoded ( Info & info,

Encoded data,

size_t bytes

)

staticinherited

Optionally swap endian of encoded audio data based on the audio encoding type, and relationship to native byte order.

Parameters: info source description of object.

buffer of audio data.

number of bytes of audio data.

static bool ost::Audio::swapEndian ( Encoding encoding,

void * buffer,

unsigned number

)

staticinherited

Optionally swap endian of audio data if the encoding format endian byte order is different from the machine's native endian.

Returns: true if endian format was different.

Parameters: encoding format of data.

buffer of audio data.

number of audio samples.

static bool ost::Audio::swapEndian ( Info & info,

void * buffer,

unsigned number

)

staticinherited

Optionally swap endian of audio data if the audio source description byte order is different from the machine's native endian byte order.

Returns: true if endian format was different.

Parameters: info source description object of data.

buffer of audio data.

number of audio samples.

static size_t ost::Audio::toBytes ( Info & info,

unsigned long number

)

staticinherited

Compute the number of bytes a given number of samples in a given audio encoding will occupy.

Returns: number of bytes samples will occupy.

Parameters: info encoding source description.

number of samples.

static size_t ost::Audio::toBytes ( Encoding encoding,

unsigned long number

)

staticinherited

Compute the number of bytes a given number of samples in a given audio encoding will occupy.

Returns: number of bytes samples will occupy.

Parameters: encoding format.

number of samples.

static float ost::Audio::todbm ( Level power )

staticinherited

Convert integer power levels to dbm.

Parameters: power level.

Returns: dbm power level.

static Level ost::Audio::tolevel ( float dbm )

staticinherited

Convert dbm power level to integer value (0-32768).

Parameters: dbm power level

Returns: integer value.

static unsigned long ost::Audio::toSamples ( Encoding encoding,

size_t bytes

)

staticinherited

Compute byte counts of audio data into number of samples based on the audio encoding format used.

Returns: number of audio samples in specified data.

Parameters: encoding format.

bytes of data.

static unsigned long ost::Audio::toSamples ( Info & info,

size_t bytes

)

staticinherited

Compute byte counts of audio data into number of samples based on the audio source description used.

Returns: number of audio samples in specified data.

Parameters: info encoding source description.

bytes of data.

static timeout_t ost::Audio::toTimeout ( const char * timestamp )

staticinherited

Convert ascii timestamp representation to a timeout number.

Parameters: timestamp ascii data.

Returns: timeout_t duration from data.

static void ost::Audio::toTimestamp ( timeout_t duration,

char * address,

size_t size

)

staticinherited

Provide ascii timestamp representation of a timeout value.

Parameters: duration timeout value

address for ascii data.

size of ascii data.

Field Documentation

Encoding ost::AudioCodec::encoding

protected

Definition at line 1738 of file audio2.h.

AudioCodec* ost::AudioCodec::first

staticprotected

Definition at line 1736 of file audio2.h.

Info ost::AudioCodec::info

protected

Definition at line 1740 of file audio2.h.

const char* ost::AudioCodec::name

protected

Definition at line 1739 of file audio2.h.

const unsigned ost::Audio::ndata

staticinherited

Definition at line 107 of file audio2.h.

AudioCodec* ost::AudioCodec::next

protected

Definition at line 1737 of file audio2.h.

The documentation for this class was generated from the following file:

audio2.h

Generated on Dec 21, 2017 for commoncpp2-1.8.1, ccrtp-1.7.2, libzrtpcpp-2.3.4, ccscript3-1.1.7, ccaudio2-1.0.0 and bayonne2-2.3.2 (after installation in /usr/local/) by doxygen 1.8.6