Bayonne2 / Common C++ 2 Framework
 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Public Types | Public Member Functions | Static Public Member Functions | Static Public Attributes | Protected Member Functions | Protected Attributes
ost::AudioFile Class Reference

A class used to manipulate audio data. More...

#include <audio2.h>

Inheritance diagram for ost::AudioFile:
Inheritance graph
[legend]
Collaboration diagram for ost::AudioFile:
Collaboration graph
[legend]

Public Types

enum  Rate {
  rateUnknown, rate6khz = 6000, rate8khz = 8000, rate16khz = 16000,
  rate32khz = 32000, rate44khz = 44100
}
 Audio encoding rate, samples per second. More...
 
typedef enum Rate Rate
 
enum  Mode {
  modeRead, modeReadAny, modeReadOne, modeWrite,
  modeCache, modeInfo, modeFeed, modeAppend,
  modeCreate
}
 File processing mode, whether to skip missing files, etc. More...
 
typedef enum Mode Mode
 
enum  Encoding {
  unknownEncoding = 0, 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 = speexVoice, speexWide = speexAudio, g723_4bit = g721ADPCM
}
 Audio encoding formats. More...
 
typedef enum Encoding Encoding
 
enum  Format {
  raw, snd, riff, mpeg,
  wave
}
 Audio container file format. More...
 
typedef enum Format Format
 
enum  DeviceMode { PLAY, RECORD, PLAYREC }
 Audio device access mode. More...
 
typedef enum DeviceMode DeviceMode
 
enum  Error {
  errSuccess = 0, errReadLast, errNotOpened, errEndOfFile,
  errStartOfFile, errRateInvalid, errEncodingInvalid, errReadInterrupt,
  errWriteInterrupt, errReadFailure, errWriteFailure, errReadIncomplete,
  errWriteIncomplete, errRequestInvalid, errTOCFailed, errStatFailed,
  errInvalidTrack, errPlaybackFailed, errNotPlaying, errNoCodec
}
 Audio error conditions. More...
 
typedef enum Error Error
 
typedef int16_t snd16_t
 
typedef int32_t snd32_t
 
typedef int16_t Level
 
typedef int16_t Sample
 
typedef int16_t * Linear
 
typedef unsigned long timeout_t
 
typedef unsigned char * Encoded
 

Public Member Functions

 AudioFile (const char *name, unsigned long offset=0)
 Construct and open an existing audio file for read/write. More...
 
 AudioFile (const char *name, Info *info, unsigned long minimum=0)
 Create and open a new audio file for writing. More...
 
 AudioFile ()
 Construct an audio file without attaching to the filesystem. More...
 
virtual ~AudioFile ()
 
void open (const char *name, Mode mode=modeWrite, timeout_t framing=0)
 Open an audio file and associate it with this object. More...
 
void create (const char *name, Info *info, bool exclusive=false, timeout_t framing=0)
 Create a new audio file and associate it with this object. More...
 
time_t getAge (void)
 Returns age since last prior access. More...
 
size_t getSize (void)
 Get maximum size of frame buffer for data use. More...
 
void close (void)
 Close an object associated with an open file. More...
 
void clear (void)
 Clear the AudioFile structure. More...
 
ssize_t getBuffer (Encoded buffer, size_t len=0)
 Retrieve bytes from the file into a memory buffer. More...
 
unsigned getLinear (Linear buffer, unsigned request=0)
 Retrieve and convert content to linear encoded audio data from it's original form. More...
 
ssize_t putBuffer (Encoded buffer, size_t len=0)
 Insert bytes into the file from a memory buffer. More...
 
unsigned putLinear (Linear buffer, unsigned request=0)
 Convert and store content from linear encoded audio data to the format of the audio file. More...
 
Error getSamples (void *buffer, unsigned samples=0)
 Retrieve samples from the file into a memory buffer. More...
 
Error putSamples (void *buffer, unsigned samples=0)
 Insert samples into the file from a memory buffer. More...
 
Error skip (long number)
 Change the file position by skipping a specified number of audio samples of audio data. More...
 
Error setPosition (unsigned long samples=~0l)
 Seek a file position by sample count. More...
 
Error position (const char *timestamp)
 Seek a file position by timestamp. More...
 
void getPosition (char *timestamp, size_t size)
 Return the timestamp of the current absolute file position. More...
 
Error setLimit (unsigned long maximum=0l)
 Set the maximum file position for reading and writing of audio data by samples. More...
 
Error getInfo (Info *info)
 Copy the source description of the audio file into the specified object. More...
 
Error setMinimum (unsigned long minimum)
 Set minimum file size for a created file. More...
 
unsigned long getAbsolutePosition (void)
 Get the current file pointer in bytes relative to the start of the file. More...
 
unsigned long getPosition (void)
 Get the current file pointer in samples relative to the start of the sample buffer. More...
 
virtual bool isOpen (void)
 Test if the file is opened. More...
 
virtual bool hasPositioning (void)
 Return true if underlying derived class supports direct access to file positioning. More...
 
Encoding getEncoding (void)
 Return audio encoding format for this audio file. More...
 
Format getFormat (void)
 Return base file format of containing audio file. More...
 
unsigned getSampleRate (void)
 Get audio encoding sample rate, in samples per second, for this audio file. More...
 
char * getAnnotation (void)
 Get annotation extracted from header of containing file. More...
 
Error getError (void)
 Get last error code. More...
 
bool operator! (void)
 
bool isSigned (void)
 Return if the current content is signed or unsigned samples. More...
 
ssize_t putNative (Encoded data, size_t size)
 Puts raw data and does native to refined endian swapping if needed based on encoding type and local machine endian. More...
 
ssize_t getPacket (Encoded data)
 Get's a packet of audio data. More...
 
ssize_t getNative (Encoded data, size_t size)
 Get raw data and assure is in native machine endian. More...
 

Static Public Member Functions

static Encoding getEncoding (const char *name)
 Get the audio encoding format that is specified by a short ascii name. More...
 
static Level tolevel (float dbm)
 Convert dbm power level to integer value (0-32768). More...
 
static float todbm (Level power)
 Convert integer power levels to dbm. More...
 
static bool hasDevice (unsigned device=0)
 Test for the presense of a specified (indexed) audio device. More...
 
static AudioDevicegetDevice (unsigned device=0, DeviceMode mode=PLAY)
 Get a audio device object that can be used to play or record audio. More...
 
static const char * getCodecPath (void)
 Get pathname to where loadable codec modules are stored. More...
 
static const char * getMIME (Info &info)
 Get the mime descriptive type for a given Audio encoding description, usually retrieved from a newly opened audio file. More...
 
static const char * getName (Encoding encoding)
 Get the short ascii description used for the given audio encoding type. More...
 
static const char * getExtension (Encoding encoding)
 Get the preferred file extension name to use for a given audio encoding type. More...
 
static Encoding getStereo (Encoding encoding)
 Get the stereo encoding format associated with the given format. More...
 
static Encoding getMono (Encoding encoding)
 Get the mono encoding format associated with the given format. More...
 
static bool isLinear (Encoding encoding)
 Test if the audio encoding format is a linear one. More...
 
static bool isBuffered (Encoding encoding)
 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

void initialize (void)
 
void getWaveFormat (int size)
 
void mp3info (mpeg_audio *mp3)
 
virtual bool afCreate (const char *path, bool exclusive=false)
 
virtual bool afOpen (const char *path, Mode m=modeWrite)
 
virtual bool afPeek (unsigned char *data, unsigned size)
 
AudioCodecgetCodec (void)
 
virtual int afRead (unsigned char *data, unsigned size)
 Read a given number of bytes from the file, starting from the current file pointer. More...
 
virtual int afWrite (unsigned char *data, unsigned size)
 Write a number of bytes into the file at the current file pointer. More...
 
virtual bool afSeek (unsigned long pos)
 Seek to the given position relative to the start of the file and set the file pointer. More...
 
virtual void afClose (void)
 Close the derived file handling system's file handle. More...
 
virtual char * getContinuation (void)
 This function is used to splice multiple audio files together into a single stream of continues audio data. More...
 
const char * getErrorStr (Error err)
 Return a human-readable error message given a numeric error code of type Audio::Error. More...
 
Error setError (Error err)
 
unsigned long getHeader (void)
 Get number of bytes in the file header. More...
 
unsigned short getShort (unsigned char *data)
 Convert binary 2 byte data stored in the order specified in the source description into a short variable. More...
 
void setShort (unsigned char *data, unsigned short value)
 Save a short as two byte binary data stored in the endian order specified in the source description. More...
 
unsigned long getLong (unsigned char *data)
 Convert binary 4 byte data stored in the order specified in the source description into a long variable. More...
 
void setLong (unsigned char *data, unsigned long value)
 Save a long as four byte binary data stored in the endian order specified in the source description. More...
 

Protected Attributes

char * pathname
 
Error error
 
unsigned long header
 
unsigned long minimum
 
unsigned long length
 
union {
   int   fd
 
   void *   handle
 
file
 
Mode mode
 
unsigned long iolimit
 
Info info
 

Detailed Description

A class used to manipulate audio data.

This class provides file level access to audio data stored in different formats. This class also provides the ability to write audio data into a disk file.

Author
David Sugar dyfet.nosp@m.@ost.nosp@m.el.co.nosp@m.m audio file access.

Definition at line 1042 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::AudioFile::AudioFile ( const char *  name,
unsigned long  offset = 0 
)

Construct and open an existing audio file for read/write.

Parameters
nameof file to open.
offsetto start access.
ost::AudioFile::AudioFile ( const char *  name,
Info info,
unsigned long  minimum = 0 
)

Create and open a new audio file for writing.

Parameters
nameof file to create.
infosource description for new file.
minimumfile size to accept at close.
ost::AudioFile::AudioFile ( )
inline

Construct an audio file without attaching to the filesystem.

Definition at line 1204 of file audio2.h.

virtual ost::AudioFile::~AudioFile ( )
virtual

Member Function Documentation

virtual void ost::AudioFile::afClose ( void  )
protectedvirtual

Close the derived file handling system's file handle.

virtual bool ost::AudioFile::afCreate ( const char *  path,
bool  exclusive = false 
)
protectedvirtual
virtual bool ost::AudioFile::afOpen ( const char *  path,
Mode  m = modeWrite 
)
protectedvirtual
virtual bool ost::AudioFile::afPeek ( unsigned char *  data,
unsigned  size 
)
protectedvirtual
virtual int ost::AudioFile::afRead ( unsigned char *  data,
unsigned  size 
)
protectedvirtual

Read a given number of bytes from the file, starting from the current file pointer.

May be overridden by derived classes.

Parameters
dataA pointer to the buffer to copy the bytes to.
sizeThe number of bytes to read.
Returns
The number of bytes read, or -1 if an error occurs. On UNIX platforms, use strerror(errno) to get the human-readable error string or FormatMessage(GetLastError()) on Windows platforms.
virtual bool ost::AudioFile::afSeek ( unsigned long  pos)
protectedvirtual

Seek to the given position relative to the start of the file and set the file pointer.

This does not use 64-bit clean seek functions, so seeking to positions greater than (2^32)-1 will result in undefined behavior.

Parameters
posThe position to seek to.
Returns
true if successful, false otherwise.
virtual int ost::AudioFile::afWrite ( unsigned char *  data,
unsigned  size 
)
protectedvirtual

Write a number of bytes into the file at the current file pointer.

May be overridden by derived classes.

Parameters
dataA pointer to the buffer with the bytes to write.
sizeThe number of bytes to write from the buffer.
Returns
The number of bytes written, or -1 if an error occurs. On UNIX platforms, use strerror(errno) to get the human-readable error string or FormatMessage(GetLastError()) on Windows platforms.
void ost::AudioFile::clear ( void  )

Clear the AudioFile structure.

Called by AudioFile::close(). Sets all fields to zero and deletes the dynamically allocated memory pointed to by the pathname and info.annotation members. See AudioFile::initialize() for the dynamic allocation code.

void ost::AudioFile::close ( void  )

Close an object associated with an open file.

This updates the header metadata with the file length if the file length has changed.

void ost::AudioFile::create ( const char *  name,
Info info,
bool  exclusive = false,
timeout_t  framing = 0 
)

Create a new audio file and associate it with this object.

Called implicitly by the three-argument version of the constructor.

Parameters
nameThe name of the file to open.
infoThe type of the audio file to be created.
exclusivecreate option.
framingtime in milliseconds.
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
addressof data to fill.
numberof samples to fill.
encodingformat of data.
unsigned long ost::AudioFile::getAbsolutePosition ( void  )

Get the current file pointer in bytes relative to the start of the file.

See getPosition() to determine the position relative to the start of the sample buffer.

Returns
The current file pointer in bytes relative to the start of the file. Returns 0 if the file is not open, is empty, or an error has occured.
time_t ost::AudioFile::getAge ( void  )

Returns age since last prior access.

Used for cache computations.

Returns
age in seconds.
char* ost::AudioFile::getAnnotation ( void  )
inline

Get annotation extracted from header of containing file.

Returns
annotation text if any, else NULL.

Definition at line 1476 of file audio2.h.

ssize_t ost::AudioFile::getBuffer ( Encoded  buffer,
size_t  len = 0 
)
virtual

Retrieve bytes from the file into a memory buffer.

This increments the file pointer so subsequent calls read further bytes. If you want to read a number of samples rather than bytes, use getSamples().

Parameters
bufferarea to copy the samples to.
lenThe number of bytes (not samples) to copy or 0 for frame.
Returns
The number of bytes (not samples) read. Returns -1 if no bytes are read and an error occurs.

Implements ost::AudioBase.

Reimplemented in ost::AudioStream.

AudioCodec* ost::AudioFile::getCodec ( void  )
protected
static const char* ost::Audio::getCodecPath ( void  )
staticinherited

Get pathname to where loadable codec modules are stored.

Returns
file path to loadable codecs.
virtual char* ost::AudioFile::getContinuation ( void  )
inlineprotectedvirtual

This function is used to splice multiple audio files together into a single stream of continues audio data.

The continuation method returns the next audio file to open.

Returns
next file to open or NULL when done.

Reimplemented in ost::BayonneAudio.

Definition at line 1119 of file audio2.h.

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
encodingThe 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
deviceindex or 0 for default audio device.
modeof 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
nameof encoding or file extension.
Returns
audio encoding format.
See Also
getName
Encoding ost::AudioFile::getEncoding ( void  )
inline

Return audio encoding format for this audio file.

Returns
audio encoding format.

Definition at line 1451 of file audio2.h.

Error ost::AudioFile::getError ( void  )
inline

Get last error code.

Returns
alst error code.

Definition at line 1484 of file audio2.h.

const char* ost::AudioFile::getErrorStr ( Error  err)
protected

Return a human-readable error message given a numeric error code of type Audio::Error.

Parameters
errThe numeric error code to translate.
Returns
A pointer to a character string containing the human-readable error message.
static const char* ost::Audio::getExtension ( Encoding  encoding)
staticinherited

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

Parameters
encodingformat.
Returns
ascii file extension to use.
Format ost::AudioFile::getFormat ( void  )
inline

Return base file format of containing audio file.

Returns
audio file container format.

Definition at line 1459 of file audio2.h.

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
encodingThe encoding type to get the frame size for.
samplesReserved. 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
encodingof frame to get timing segment for.
timeoutof 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
infodescriptor of frame encoding to get timing segment for.
timeoutof frame time segment to request.
unsigned long ost::AudioFile::getHeader ( void  )
inlineprotected

Get number of bytes in the file header.

Data packets will begin after this header.

Returns
number of bytes in file header.

Definition at line 1140 of file audio2.h.

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
encodingformat of data to examine.
bufferof audio data to examine.
numberof 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
infoencoding source description object.
bufferof audio data to examine.
numberof audio samples to examine.
Error ost::AudioFile::getInfo ( Info info)

Copy the source description of the audio file into the specified object.

Parameters
infopointer to object to copy source description into.
Returns
errSucess.
unsigned ost::AudioFile::getLinear ( Linear  buffer,
unsigned  request = 0 
)

Retrieve and convert content to linear encoded audio data from it's original form.

Parameters
bufferto copy linear data into.
requestnumber of linear samples to extract or 0 for frame.
Returns
number of samples retrieved, 0 if no codec or eof.
unsigned long ost::AudioFile::getLong ( unsigned char *  data)
protected

Convert binary 4 byte data stored in the order specified in the source description into a long variable.

This is often used to manipulate header data.

Returns
long value.
Parameters
databinary 4 byte data pointer.
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
infosource 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
encodingformat.
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
encodingformat.
Returns
ascii name of encoding format.
ssize_t ost::AudioBase::getNative ( Encoded  data,
size_t  size 
)
inherited

Get raw data and assure is in native machine endian.

Returns
data received in buffer.
Parameters
datato get.
sizeof data to get.
ssize_t ost::AudioBase::getPacket ( Encoded  data)
inlineinherited

Get's a packet of audio data.

Returns
count of data received.
Parameters
datato get.

Definition at line 981 of file audio2.h.

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
encodingformat of data.
bufferof audio data.
numberof 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
infodescription object of audio data.
bufferof audio data.
numberof samples to examine.
void ost::AudioFile::getPosition ( char *  timestamp,
size_t  size 
)

Return the timestamp of the current absolute file position.

Parameters
timestampto save ascii position into.
sizeof timestamp buffer.
unsigned long ost::AudioFile::getPosition ( void  )

Get the current file pointer in samples relative to the start of the sample buffer.

Note that you must multiply this result by the result of a call to toBytes(info.encoding, 1) in order to determine the offset in bytes.

Returns
the current file pointer in samples relative to the start of the sample buffer. Returns 0 if the file is not open, is empty, or an error has occured.
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
encodingformat.
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
encodingformat.
requestedrate.
unsigned ost::AudioFile::getSampleRate ( void  )
inline

Get audio encoding sample rate, in samples per second, for this audio file.

Returns
sample rate.

Definition at line 1468 of file audio2.h.

Error ost::AudioFile::getSamples ( void *  buffer,
unsigned  samples = 0 
)

Retrieve samples from the file into a memory buffer.

This increments the file pointer so subsequent calls read further samples. If a limit has been set using setLimit(), the number of samples read will be truncated to the limit position. If you want to read a certain number of bytes rather than a certain number of samples, use getBuffer().

Parameters
bufferpointer to copy the samples to.
samplesThe number of samples to read or 0 for frame.
Returns
errSuccess if successful, !errSuccess if error. Use getErrorStr() to retrieve the human-readable error string.
unsigned short ost::AudioFile::getShort ( unsigned char *  data)
protected

Convert binary 2 byte data stored in the order specified in the source description into a short variable.

This is often used to manipulate header data.

Returns
short value.
Parameters
databinary 2 byte data pointer.
size_t ost::AudioFile::getSize ( void  )
inline

Get maximum size of frame buffer for data use.

Returns
max frame size in bytes.

Definition at line 1246 of file audio2.h.

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

Get the stereo encoding format associated with the given format.

Parameters
encodingformat being tested for stereo.
Returns
associated stereo audio encoding format.
void ost::AudioFile::getWaveFormat ( int  size)
protected
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
deviceindex or 0 for default audio device.
Returns
true if device exists.
virtual bool ost::AudioFile::hasPositioning ( void  )
inlinevirtual

Return true if underlying derived class supports direct access to file positioning.

Derived classes based on URL's or fifo devices may not have this ability.

Returns
true if file positioning is supported.

Definition at line 1443 of file audio2.h.

void ost::AudioFile::initialize ( void  )
protected
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
encodingformat.
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
encodingformat.
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
infosource 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
encodingformat.
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
encodingformat.
virtual bool ost::AudioFile::isOpen ( void  )
virtual

Test if the file is opened.

Returns
true if a file is open.
bool ost::AudioFile::isSigned ( void  )

Return if the current content is signed or unsigned samples.

Returns
true if signed.
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
encodingformat.
static bool ost::Audio::loadPlugin ( const char *  path)
staticinherited

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

Returns
true if loaded.
Parameters
pathto 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
infosource description object.
Returns
maximum possible frame size to allocate for encoded data.
void ost::AudioFile::mp3info ( mpeg_audio mp3)
protected
void ost::AudioFile::open ( const char *  name,
Mode  mode = modeWrite,
timeout_t  framing = 0 
)

Open an audio file and associate it with this object.

Called implicitly by the two-argument version of the constructor.

Parameters
nameof the file to open. Don't forget to double your backslashes for DOS-style pathnames.
modeto open file under.
framingtime in milliseconds.
bool ost::AudioFile::operator! ( void  )
inline

Definition at line 1487 of file audio2.h.

Error ost::AudioFile::position ( const char *  timestamp)

Seek a file position by timestamp.

The actual position will be rounded by framing.

Returns
errSuccess if successful.
Parameters
timestampposition to seek.
ssize_t ost::AudioFile::putBuffer ( Encoded  buffer,
size_t  len = 0 
)
virtual

Insert bytes into the file from a memory buffer.

This increments the file pointer so subsequent calls append further samples. If you want to write a number of samples rather than bytes, use putSamples().

Parameters
bufferarea to append the samples from.
lenThe number of bytes (not samples) to append.
Returns
The number of bytes (not samples) read. Returns -1 if an error occurs and no bytes are written.

Implements ost::AudioBase.

unsigned ost::AudioFile::putLinear ( Linear  buffer,
unsigned  request = 0 
)

Convert and store content from linear encoded audio data to the format of the audio file.

Parameters
bufferto copy linear data from.
requestNumber of linear samples to save or 0 for frame.
Returns
number of samples saved, 0 if no codec or eof.
ssize_t ost::AudioBase::putNative ( Encoded  data,
size_t  size 
)
inherited

Puts raw data and does native to refined endian swapping if needed based on encoding type and local machine endian.

Parameters
datato put.
sizeof data to put.
Returns
number of bytes actually put.
Error ost::AudioFile::putSamples ( void *  buffer,
unsigned  samples = 0 
)

Insert samples into the file from a memory buffer.

This increments the file pointer so subsequent calls append further samples. If you want to write a certain number of bytes rather than a certain number of samples, use putBuffer().

Parameters
bufferpointer to append the samples from.
samplesThe number of samples (not bytes) to append.
Returns
errSuccess if successful, !errSuccess if error. Use getErrorStr() to retrieve the human-readable error string.
Error ost::AudioFile::setError ( Error  err)
protected
Error ost::AudioFile::setLimit ( unsigned long  maximum = 0l)

Set the maximum file position for reading and writing of audio data by samples.

If 0, then no limit is set.

Parameters
maximumfile i/o access size sample position.
Returns
errSuccess if successful.
void ost::AudioFile::setLong ( unsigned char *  data,
unsigned long  value 
)
protected

Save a long as four byte binary data stored in the endian order specified in the source description.

This is often used to manipulate header data.

Parameters
databinary 4 byte data pointer.
valueto convert.
Error ost::AudioFile::setMinimum ( unsigned long  minimum)

Set minimum file size for a created file.

If the file is closed with fewer samples than this, it will also be deleted.

Parameters
minimumnumber of samples for new file.
Returns
errSuccess if successful.
Error ost::AudioFile::setPosition ( unsigned long  samples = ~0l)

Seek a file position by sample count.

If no position specified, then seeks to end of file.

Returns
errSuccess or error condition on failure.
Parameters
samplesposition to seek in file.
void ost::AudioFile::setShort ( unsigned char *  data,
unsigned short  value 
)
protected

Save a short as two byte binary data stored in the endian order specified in the source description.

This is often used to manipulate header data.

Parameters
databinary 2 byte data pointer.
valueto convert.
Error ost::AudioFile::skip ( long  number)

Change the file position by skipping a specified number of audio samples of audio data.

Returns
errSuccess or error condition on failure.
Parameters
numberof samples to skip.
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
infosource description of object.
bufferof audio data.
numberof 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
encodingformat of data.
bufferof audio data.
numberof 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
infosource description object of data.
bufferof audio data.
numberof 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
infoencoding source description.
numberof 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
encodingformat.
numberof samples.
static float ost::Audio::todbm ( Level  power)
staticinherited

Convert integer power levels to dbm.

Parameters
powerlevel.
Returns
dbm power level.
static Level ost::Audio::tolevel ( float  dbm)
staticinherited

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

Parameters
dbmpower 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
encodingformat.
bytesof 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
infoencoding source description.
bytesof data.
static timeout_t ost::Audio::toTimeout ( const char *  timestamp)
staticinherited

Convert ascii timestamp representation to a timeout number.

Parameters
timestampascii 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
durationtimeout value
addressfor ascii data.
sizeof ascii data.

Field Documentation

Error ost::AudioFile::error
protected

Definition at line 1046 of file audio2.h.

int ost::AudioFile::fd

Definition at line 1056 of file audio2.h.

union { ... } ost::AudioFile::file
void* ost::AudioFile::handle

Definition at line 1057 of file audio2.h.

unsigned long ost::AudioFile::header
protected

Definition at line 1047 of file audio2.h.

Info ost::AudioBase::info
protectedinherited

Definition at line 911 of file audio2.h.

unsigned long ost::AudioFile::iolimit
protected

Definition at line 1061 of file audio2.h.

unsigned long ost::AudioFile::length
protected

Definition at line 1049 of file audio2.h.

unsigned long ost::AudioFile::minimum
protected

Definition at line 1048 of file audio2.h.

Mode ost::AudioFile::mode
protected

Definition at line 1060 of file audio2.h.

const unsigned ost::Audio::ndata
staticinherited

Definition at line 107 of file audio2.h.

char* ost::AudioFile::pathname
protected

Definition at line 1045 of file audio2.h.


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