Bayonne2 / Common C++ 2 Framework
|
A class used to manipulate audio data. More...
#include <audio2.h>
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 AudioDevice * | getDevice (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) |
AudioCodec * | getCodec (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 |
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.
|
inherited |
|
inherited |
|
inherited |
|
inherited |
|
inherited |
|
inherited |
|
inherited |
|
inherited |
|
inherited |
|
inherited |
|
inherited |
|
inherited |
|
inherited |
|
inherited |
|
inherited |
Audio encoding formats.
|
inherited |
Audio error conditions.
|
inherited |
|
inherited |
|
inherited |
ost::AudioFile::AudioFile | ( | const char * | name, |
unsigned long | offset = 0 |
||
) |
Construct and open an existing audio file for read/write.
name | of file to open. |
offset | to start access. |
ost::AudioFile::AudioFile | ( | const char * | name, |
Info * | info, | ||
unsigned long | minimum = 0 |
||
) |
Create and open a new audio file for writing.
name | of file to create. |
info | source description for new file. |
minimum | file size to accept at close. |
|
inline |
|
virtual |
|
protectedvirtual |
Close the derived file handling system's file handle.
|
protectedvirtual |
|
protectedvirtual |
|
protectedvirtual |
Read a given number of bytes from the file, starting from the current file pointer.
May be overridden by derived classes.
data | A pointer to the buffer to copy the bytes to. |
size | The number of bytes to read. |
|
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.
pos | The position to seek to. |
|
protectedvirtual |
Write a number of bytes into the file at the current file pointer.
May be overridden by derived classes.
data | A pointer to the buffer with the bytes to write. |
size | The number of bytes to write from the buffer. |
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.
name | The name of the file to open. |
info | The type of the audio file to be created. |
exclusive | create option. |
framing | time in milliseconds. |
|
staticinherited |
Fill an audio buffer with "empty" (silent) audio data, based on the audio encoding format.
address | of data to fill. |
number | of samples to fill. |
encoding | format 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.
time_t ost::AudioFile::getAge | ( | void | ) |
Returns age since last prior access.
Used for cache computations.
|
inline |
|
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().
buffer | area to copy the samples to. |
len | The number of bytes (not samples) to copy or 0 for frame. |
Implements ost::AudioBase.
Reimplemented in ost::AudioStream.
|
protected |
|
staticinherited |
Get pathname to where loadable codec modules are stored.
|
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.
Reimplemented in ost::BayonneAudio.
|
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.
encoding | The encoding to calculate the frame sample count for. |
|
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.
device | index or 0 for default audio device. |
mode | of device; play, record, or full duplex. |
|
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.
name | of encoding or file extension. |
|
inline |
|
inline |
|
protected |
Return a human-readable error message given a numeric error code of type Audio::Error.
err | The numeric error code to translate. |
|
staticinherited |
Get the preferred file extension name to use for a given audio encoding type.
encoding | format. |
|
inline |
|
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.
encoding | The encoding type to get the frame size for. |
samples | Reserved. Use zero. |
|
staticinherited |
Return frame timing for an audio encoding format.
encoding | of frame to get timing segment for. |
timeout | of frame time segment to request. |
Return frame time for an audio source description.
info | descriptor of frame encoding to get timing segment for. |
timeout | of frame time segment to request. |
|
inlineprotected |
|
staticinherited |
Get the energey impulse level of a frame of audio data.
encoding | format of data to examine. |
buffer | of audio data to examine. |
number | of audio samples to examine. |
|
staticinherited |
Get the energey impulse level of a frame of audio data.
info | encoding source description object. |
buffer | of audio data to examine. |
number | of audio samples to examine. |
Copy the source description of the audio file into the specified object.
info | pointer to object to copy source description into. |
unsigned ost::AudioFile::getLinear | ( | Linear | buffer, |
unsigned | request = 0 |
||
) |
Retrieve and convert content to linear encoded audio data from it's original form.
buffer | to copy linear data into. |
request | number of linear samples to extract or 0 for frame. |
|
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.
data | binary 4 byte data pointer. |
|
staticinherited |
Get the mime descriptive type for a given Audio encoding description, usually retrieved from a newly opened audio file.
info | source description object |
Get the mono encoding format associated with the given format.
encoding | format. |
|
staticinherited |
Get the short ascii description used for the given audio encoding type.
encoding | format. |
|
inherited |
Get raw data and assure is in native machine endian.
data | to get. |
size | of data to get. |
|
inlineinherited |
|
staticinherited |
Get the peak (highest energy) level found in a frame of audio data.
encoding | format of data. |
buffer | of audio data. |
number | of samples to examine. |
|
staticinherited |
Get the peak (highest energy) level found in a frame of audio data.
info | description object of audio data. |
buffer | of audio data. |
number | of samples to examine. |
void ost::AudioFile::getPosition | ( | char * | timestamp, |
size_t | size | ||
) |
Return the timestamp of the current absolute file position.
timestamp | to save ascii position into. |
size | of 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.
Return default sample rate associated with the specified audio encoding format.
encoding | format. |
Return optional rate setting effect.
Many codecs are fixed rate.
encoding | format. |
requested | rate. |
|
inline |
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().
buffer | pointer to copy the samples to. |
samples | The number of samples to read or 0 for frame. |
|
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.
data | binary 2 byte data pointer. |
|
inline |
Get the stereo encoding format associated with the given format.
encoding | format being tested for stereo. |
|
protected |
|
staticinherited |
Test for the presense of a specified (indexed) audio device.
This is normally used to test for local soundcard access.
device | index or 0 for default audio device. |
|
inlinevirtual |
|
protected |
|
staticinherited |
Test if the audio encoding format must be packetized (that is, has irregular sized frames) and must be processed only through buffered codecs.
encoding | format. |
|
staticinherited |
Test if the endian byte order of the encoding format is different from the machine's native byte order.
encoding | format. |
|
staticinherited |
Test if the endian byte order of the audio source description is different from the machine's native byte order.
info | source description object. |
|
staticinherited |
Test if the audio encoding format is a linear one.
encoding | format. |
|
staticinherited |
Test if the audio encoding format is a mono format.
encoding | format. |
|
virtual |
Test if the file is opened.
bool ost::AudioFile::isSigned | ( | void | ) |
Return if the current content is signed or unsigned samples.
|
staticinherited |
Test if the audio encoding format is a stereo format.
encoding | format. |
|
staticinherited |
Load a dso plugin (codec plugin), used internally...
path | to codec. |
|
staticinherited |
Maximum framesize for a given coding that may be needed to store a result.
info | source description object. |
|
protected |
Open an audio file and associate it with this object.
Called implicitly by the two-argument version of the constructor.
name | of the file to open. Don't forget to double your backslashes for DOS-style pathnames. |
mode | to open file under. |
framing | time in milliseconds. |
Error ost::AudioFile::position | ( | const char * | timestamp | ) |
Seek a file position by timestamp.
The actual position will be rounded by framing.
timestamp | position to seek. |
|
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().
buffer | area to append the samples from. |
len | The number of bytes (not samples) to append. |
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.
buffer | to copy linear data from. |
request | Number of linear samples to save or 0 for frame. |
|
inherited |
Puts raw data and does native to refined endian swapping if needed based on encoding type and local machine endian.
data | to put. |
size | of data to 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().
buffer | pointer to append the samples from. |
samples | The number of samples (not bytes) to append. |
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.
maximum | file i/o access size sample position. |
|
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.
data | binary 4 byte data pointer. |
value | to 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.
minimum | number of samples for new file. |
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.
samples | position to seek in file. |
|
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.
data | binary 2 byte data pointer. |
value | to convert. |
Error ost::AudioFile::skip | ( | long | number | ) |
Change the file position by skipping a specified number of audio samples of audio data.
number | of samples to skip. |
Optionally swap endian of encoded audio data based on the audio encoding type, and relationship to native byte order.
info | source description of object. |
buffer | of audio data. |
number | of bytes of audio data. |
|
staticinherited |
Optionally swap endian of audio data if the encoding format endian byte order is different from the machine's native endian.
encoding | format of data. |
buffer | of audio data. |
number | of audio samples. |
|
staticinherited |
Optionally swap endian of audio data if the audio source description byte order is different from the machine's native endian byte order.
info | source description object of data. |
buffer | of audio data. |
number | of audio samples. |
|
staticinherited |
Compute the number of bytes a given number of samples in a given audio encoding will occupy.
info | encoding source description. |
number | of samples. |
|
staticinherited |
Compute the number of bytes a given number of samples in a given audio encoding will occupy.
encoding | format. |
number | of samples. |
|
staticinherited |
Convert integer power levels to dbm.
power | level. |
|
staticinherited |
Convert dbm power level to integer value (0-32768).
dbm | power level |
|
staticinherited |
Compute byte counts of audio data into number of samples based on the audio encoding format used.
encoding | format. |
bytes | of data. |
|
staticinherited |
Compute byte counts of audio data into number of samples based on the audio source description used.
info | encoding source description. |
bytes | of data. |
|
staticinherited |
Convert ascii timestamp representation to a timeout number.
timestamp | ascii data. |
|
staticinherited |
Provide ascii timestamp representation of a timeout value.
duration | timeout value |
address | for ascii data. |
size | of ascii data. |
union { ... } ost::AudioFile::file |