ccaudio2-2.2.0/inc/ccaudio2.h

// Copyright (C) 1995-1999 David Sugar, Tycho Softworks.
// Copyright (C) 1999-2005 Open Source Telecom Corp.
// Copyright (C) 2005-2014 David Sugar, Tycho Softworks.
// Copyright (C) 2015 Cherokees of Idaho.
//
// This file is part of GNU ccAudio2.
//
// GNU ccAudio2 is free software: you can redistribute it and/or modify
// it under the terms of the GNU Lesser General Public License as published
// by the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// GNU ccAudio2 is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU Lesser General Public License for more details.
//
// You should have received a copy of the GNU Lesser General Public License
// along with GNU ccAudio2.  If not, see <http://www.gnu.org/licenses/>.

/**
 * This library holds the GNU telephonic audio library, ccAudio.  This
 * library offers support for audio transcoding, for accessing of audio
 * files, tone generation and detection, and phrasebook voice libraries.
 * @file ccaudio.h
 */

#ifndef _CCAUDIO2_H_
#define _CCAUDIO2_H_

#ifndef _UCOMMON_UCOMMON_H_
#include <ucommon/ucommon.h>
#endif

namespace ucommon {

#define AUDIO_SIGNED_LINEAR_RAW 1
#define AUDIO_LINEAR_CONVERSION 1
#define AUDIO_CODEC_MODULES 1
#define AUDIO_LINEAR_FRAMING    1
#define AUDIO_NATIVE_METHODS    1
#define AUDIO_RATE_RESAMPLER    1

class __EXPORT AudioCodec;
class __EXPORT AudioDevice;

/**
 * Generic audio class to hold master data types and various useful
 * class encapsulated friend functions as per GNU Common C++ 2 coding
 * standard.
 *
 * @author David Sugar <dyfet@ostel.com>
 * @short Master audio class.
 */
class __EXPORT Audio
{
private:
    __DELETE_COPY(Audio);

public:
    typedef int16_t snd16_t;
    typedef int32_t snd32_t;
    typedef int16_t Level;
    typedef int16_t Sample;
    typedef int16_t *Linear;

#if _MSC_VER > 1400        // windows broken dll linkage issue...
    const static unsigned ndata = (-1);
#else
    const static unsigned ndata;
#endif

    typedef struct {
    float v2;
        float v3;
        float fac;
    } goertzel_state_t;

    typedef struct {
        int hit1;
        int hit2;
        int hit3;
        int hit4;
        int mhit;

        goertzel_state_t row_out[4];
        goertzel_state_t col_out[4];
        goertzel_state_t row_out2nd[4];
        goertzel_state_t col_out2nd[4];
        goertzel_state_t fax_tone;
        goertzel_state_t fax_tone2nd;
        float energy;

        int current_sample;
        char digits[129];
        int current_digits;
        int detected_digits;
        int lost_digits;
        int digit_hits[16];
        int fax_hits;
    } dtmf_detect_state_t;

    typedef struct {
        float fac;
    } tone_detection_descriptor_t;

    typedef unsigned char *Encoded;

    /**
     * Audio encoding rate, samples per second.
     */
    enum    Rate {
        rateUnknown,
        rate6khz = 6000,
        rate8khz = 8000,
        rate11khz = 11025,
        rate16khz = 16000,
        rate22khz = 22050,
        rate32khz = 32000,
        rate44khz = 44100
    };

    typedef enum Rate Rate;

    /**
     * File processing mode, whether to skip missing files, etc.
     */
    enum    Mode {
        modeRead,
        modeReadAny,
        modeReadOne,
        modeWrite,
        modeCache,
        modeInfo,
        modeFeed,

        modeAppend, // app specific placeholders...
        modeCreate
    };

    typedef enum Mode Mode;

    /**
     * Audio encoding formats.
     */
    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,

        // Please keep the PCM types at the end of the list -
        // see the "is this PCM or not?" code in
        // AudioFile::close for why.
        cdaStereo,
        cdaMono,
        pcm8Stereo,
        pcm8Mono,
        pcm16Stereo,
        pcm16Mono,
        pcm32Stereo,
        pcm32Mono,

        // speex codecs
        speexVoice, // narrow band
        speexAudio,

        g729Audio,
        ilbcAudio,
        speexUltra,

        speexNarrow = speexVoice,
        speexWide = speexAudio,
        g723_4bit = g721ADPCM
    };
    typedef enum Encoding Encoding;

    /**
     * Audio container file format.
     */
    enum Format {
        raw,
        snd,
        riff,
        mpeg,
        wave
    };
    typedef enum Format Format;

    /**
     * Audio device access mode.
     */
    enum DeviceMode {
        PLAY,
        RECORD,
        PLAYREC
    };
    typedef enum DeviceMode DeviceMode;

    /**
     * Audio error conditions.
     */
    enum Error {
        errSuccess = 0,
        errReadLast,
        errNotOpened,
        errEndOfFile,
        errStartOfFile,
        errRateInvalid,
        errEncodingInvalid,
        errReadInterrupt,
        errWriteInterrupt,
        errReadFailure,
        errWriteFailure,
        errReadIncomplete,
        errWriteIncomplete,
        errRequestInvalid,
        errTOCFailed,
        errStatFailed,
        errInvalidTrack,
        errPlaybackFailed,
        errNotPlaying,
        errNoCodec
    };
    typedef enum Error Error;

    /**
     * Audio source description.
     */
    class __EXPORT Info
    {
    public:
        Format format;
        Encoding encoding;
        unsigned long rate;
        unsigned long bitrate;
        unsigned order;
        unsigned framesize, framecount, headersize, padding;
        timeout_t framing;
        char *annotation;

        Info();
        Info(const Info& copy);

        void clear(void);
        void set(void);
        void setFraming(timeout_t frame);
        void setRate(Rate rate);
    };

    inline Audio() {}

    /**
     * Convert dbm power level to integer value (0-32768).
     *
     * @param dbm power level
     * @return integer value.
     */
    static Level tolevel(float dbm);

    /**
     * Convert integer power levels to dbm.
     *
     * @param power level.
     * @return dbm power level.
     */
    static float todbm(Level power);

    /**
     * Test for the presense of a specified (indexed) audio device.
     * This is normally used to test for local soundcard access.
     *
     * @param device index or 0 for default audio device.
     * @return true if device exists.
     */
    static bool is_available(unsigned device = 0);

    /**
     * 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.
     *
     * @param device index or 0 for default audio device.
     * @param mode of device; play, record, or full duplex.
     * @return pointer to abstract audio device object interface class.
     */
    static AudioDevice *getDevice(unsigned device = 0, DeviceMode mode = PLAY);

    /**
     * Get the mime descriptive type for a given Audio encoding
     * description, usually retrieved from a newly opened audio file.
     *
     * @param info source description object
     * @return text of mime type to use for this audio source.
     */
    static const char *getMIME(Info &info);

    /**
     * Get the short ascii description used for the given audio
     * encoding type.
     *
     * @param encoding format.
     * @return ascii name of encoding format.
     */
    static const char *getName(Encoding encoding);

    /**
     * Get the preferred file extension name to use for a given
     * audio encoding type.
     *
     * @param encoding format.
     * @return ascii file extension to use.
     */
    static const char *getExtension(Encoding encoding);

    /**
     * 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.
     *
     * @param name of encoding or file extension.
     * @return audio encoding format.
     * @see #getName
     */
    static Encoding getEncoding(const char *name);

    /**
     * Get the stereo encoding format associated with the given format.
     *
     * @param encoding format being tested for stereo.
     * @return associated stereo audio encoding format.
     */
    static Encoding getStereo(Encoding encoding);

    /**
     * Get the mono encoding format associated with the given format.
     *
     * @param encoding format.
     * @return associated mono audio encoding format.
     */
    static Encoding getMono(Encoding encoding);

    /**
     * Test if the audio encoding format is a linear one.
     *
     * @return true if encoding format is linear audio data.
     * @param encoding format.
     */
    static bool is_linear(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.
     *
     * @return true if packetized audio.
     * @param encoding format.
     */
    static bool is_buffered(Encoding encoding);

    /**
     * Test if the audio encoding format is a mono format.
     *
     * @return true if encoding format is mono audio data.
     * @param encoding format.
     */
    static bool is_mono(Encoding encoding);

    /**
     * Test if the audio encoding format is a stereo format.
     *
     * @return true if encoding format is stereo audio data.
     * @param encoding format.
     */
    static bool is_stereo(Encoding encoding);

    /**
     * Return default sample rate associated with the specified
     * audio encoding format.
     *
     * @return sample rate for audio data.
     * @param encoding format.
     */
    static Rate getRate(Encoding encoding);

    /**
     * Return optional rate setting effect.  Many codecs are
     * fixed rate.
     *
     * @return result rate for audio date.
     * @param encoding format.
     * @param requested rate.
     */
    static Rate getRate(Encoding e, Rate request);

    /**
     * Return frame timing for an audio encoding format.
     *
     * @return frame time to use in milliseconds.
     * @param encoding of frame to get timing segment for.
     * @param timeout of frame time segment to request.
     */
    static timeout_t getFraming(Encoding encoding, timeout_t timeout = 0);

    /**
     * Return frame time for an audio source description.
     *
     * @return frame time to use in milliseconds.
     * @param info descriptor of frame encoding to get timing segment for.
     * @param timeout of frame time segment to request.
     */
    static timeout_t getFraming(Info &info, timeout_t timeout = 0);

    /**
     * Test if the endian byte order of the encoding format is
     * different from the machine's native byte order.
     *
     * @return true if endian format is different.
     * @param encoding format.
     */
    static bool is_endian(Encoding encoding);

    /**
     * Test if the endian byte order of the audio source description
     * is different from the machine's native byte order.
     *
     * @return true if endian format is different.
     * @param info source description object.
     */
    static bool is_endian(Info &info);

    /**
     * Optionally swap endian of audio data if the encoding format
     * endian byte order is different from the machine's native endian.
     *
     * @return true if endian format was different.
     * @param encoding format of data.
     * @param buffer of audio data.
     * @param number of audio samples.
     */
    static bool swapEndian(Encoding encoding, void *buffer, unsigned number);

    /**
     * Optionally swap endian of encoded audio data based on the
     * audio encoding type, and relationship to native byte order.
     *
     * @param info source description of object.
     * @param buffer of audio data.
     * @param number of bytes of audio data.
     */
    static void swapEncoded(Info &info, Encoded data, size_t bytes);

       /**
     * Optionally swap endian of audio data if the audio source
     * description byte order is different from the machine's native
     * endian byte order.
     *
     * @return true if endian format was different.
     * @param info source description object of data.
     * @param buffer of audio data.
     * @param number of audio samples.
     */
    static bool swapEndian(Info &info, void *buffer, unsigned number);

    static const char *getPluginPath(void);

    /**
     * Get the energey impulse level of a frame of audio data.
     *
     * @return impulse energy level of audio data.
     * @param encoding format of data to examine.
     * @param buffer of audio data to examine.
     * @param number of audio samples to examine.
     */
    static Level impulse(Encoding encoding, void *buffer, unsigned number);

    /**
     * Get the energey impulse level of a frame of audio data.
     *
     * @return impulse energy level of audio data.
     * @param info encoding source description object.
     * @param buffer of audio data to examine.
     * @param number of audio samples to examine.
     */
    static Level impulse(Info &info, void *buffer, unsigned number = 0);

    /**
     * Get the peak (highest energy) level found in a frame of audio
     * data.
     *
     * @return peak energy level found in data.
     * @param encoding format of data.
     * @param buffer of audio data.
     * @param number of samples to examine.
     */
    static Level peak(Encoding encoding, void *buffer, unsigned number);

    /**
     * Get the peak (highest energy) level found in a frame of audio
     * data.
     *
     * @return peak energy level found in data.
     * @param info description object of audio data.
     * @param buffer of audio data.
     * @param number of samples to examine.
     */
    static Level peak(Info &info, void *buffer, unsigned number = 0);

    /**
     * Provide ascii timestamp representation of a timeout value.
     *
     * @param duration timeout value
     * @param address for ascii data.
     * @param size of ascii data.
     */
    static void toTimestamp(timeout_t duration, char *address, size_t size);

    /**
     * Convert ascii timestamp representation to a timeout number.
     *
     * @param timestamp ascii data.
     * @return timeout_t duration from data.
     */
    static timeout_t toTimeout(const char *timestamp);

    /**
     * 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.
     *
     * @param encoding The encoding type to get the frame size for.
     * @param samples Reserved.  Use zero.
     *
     * @return The number of bytes in a frame for the given encoding.
     */
    static int getFrame(Encoding encoding, int samples = 0);

    /**
     * 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.
     *
     * @param encoding The encoding to calculate the frame sample count for.
     * @return samples The number of samples in a frame of the given encoding.
     */
    static int getCount(Encoding encoding);

    /**
     * Compute byte counts of audio data into number of samples
     * based on the audio encoding format used.
     *
     * @return number of audio samples in specified data.
     * @param encoding format.
     * @param bytes of data.
     */
    static unsigned long toSamples(Encoding encoding, size_t bytes);

    /**
     * Compute byte counts of audio data into number of samples
     * based on the audio source description used.
     *
     * @return number of audio samples in specified data.
     * @param info encoding source description.
     * @param bytes of data.
     */
    static unsigned long toSamples(Info &info, size_t bytes);

    /**
     * Compute the number of bytes a given number of samples in
     * a given audio encoding will occupy.
     *
     * @return number of bytes samples will occupy.
     * @param info encoding source description.
     * @param number of samples.
     */
    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.
     *
     * @return number of bytes samples will occupy.
     * @param encoding format.
     * @param number of samples.
     */
    static size_t toBytes(Encoding encoding, unsigned long number);

    /**
     * Fill an audio buffer with "empty" (silent) audio data, based
     * on the audio encoding format.
     *
     * @param address of data to fill.
     * @param number of samples to fill.
     * @param encoding format of data.
     */
    static void fill(unsigned char *address, int number, Encoding encoding);

    /**
     * Maximum framesize for a given coding that may be needed to
     * store a result.
     *
     * @param info source description object.
     * @return maximum possible frame size to allocate for encoded data.
     */
    static size_t maxFramesize(Info &info);

    /**
     * Initialize by loading any plugins.
     */
    static void init(void);
};

/**
 * The AudioResample class is used to manage linear intropolation
 * buffering for rate conversions.
 *
 * @author David Sugar <dyfet@ostel.com>
 * @short linear intropolation and rate conversion.
 */
class __EXPORT AudioResample : public Audio
{
private:
    __DELETE_DEFAULTS(AudioResample);

protected:
    unsigned mfact, dfact, max;
    unsigned gpos, ppos;
    Sample last;
    Linear buffer;

public:
    AudioResample(Rate mul, Rate div);
    ~AudioResample();

    size_t process(Linear from, Linear to, size_t count);
    size_t estimate(size_t count);
};

/**
 * The AudioTone class is used to create a frame of audio encoded single or
 * dualtones.  The frame will be iterated for each request, so a
 * continual tone can be extracted by frame.
 *
 * @author David Sugar <dyfet@ostel.com>
 * @short audio tone generator class.
 */
class __EXPORT AudioTone : public Audio
{
private:
    __DELETE_COPY(AudioTone);

protected:
    Rate rate;
    unsigned samples;
    Linear frame;
    double df1, df2, p1, p2;
    Level m1, m2;
    bool silencer;

    /**
     * Set the frame to silent.
     */
    void silence(void);

    /**
     * Reset the tone generator completely.  Produces silence.,
     */
    void reset(void);

    /**
     * Cleanup for virtual destructors to use.
     */
    void cleanup(void);

    /**
     * Set frame to generate single tone...
     *
     * @param freq of tone.
     * @param level of tone.
     */
    void single(unsigned freq, Level level);

    /**
     * Set frame to generate dual tone...
     *
     * @param f1 frequency of tone 1
     * @param f2 frequency of tone 2
     * @param l1 level of tone 1
     * @param l2 level of tone 2
     */
    void dual(unsigned f1, unsigned f2, Level l1, Level l2);

public:
    /**
     * Get the sample encoding rate being used for the tone generator
     *
     * @return sample rate in samples per second.
     */
    inline Rate getRate(void) const
        {return rate;}

    /**
     * Get the frame size for the number of audio samples generated.
     *
     * @return number of samples processed in frame.
     */
    inline size_t getSamples(void) const
        {return samples;}

    /**
     * Test if the tone generator is currently set to silence.
     *
     * @return true if generator set for silence.
     */
    bool is_silent(void);

    /**
     * Iterate the tone frame, and extract linear samples in
     * native frame.  If endian flag passed, then convert for
     * standard endian representation (byte swap) if needed.
     *
     * @return pointer to samples.
     */
    virtual Linear getFrame(void);

    /**
     * This is used to copy one or more pages of framed audio
     * quickly to an external buffer.
     *
     * @return number of frames copied.
     * @param buffer to copy into.
     * @param number of frames requested.
     */
    unsigned getFrames(Linear buffer, unsigned number);

    /**
     * See if at end of tone.  This is used for non-continues audio
     * tones, or to detect "break" events.
     *
     * @return true if end of data.
     */
    virtual bool is_complete(void);

    /**
     * Construct a silent tone generator of specific frame size.
     *
     * @param duration of frame in milliseconds.
     * @param rate of samples.
     */
    AudioTone(timeout_t duration = 20, Rate rate = rate8khz);

    /**
     * Construct a dual tone frame generator.
     *
     * @param f1 frequency of tone 1.
     * @param f2 frequency of tone 2.
     * @param l1 level of tone 1.
     * @param l2 level of tone 2.
     * @param duration of frame in milliseconds.
     * @param sample rate being generated.
     */
    AudioTone(unsigned f1, unsigned f2, Level l1, Level l2,
        timeout_t duration = 20, Rate sample = rate8khz);

    /**
     * Construct a single tone frame generator.
     *
     * @param freq of tone.
     * @param level of tone.
     * @param duration of frame in milliseconds.
     * @param sample rate being generated.
     */
    AudioTone(unsigned freq, Level level, timeout_t duration = 20, Rate sample = rate8khz);

    virtual ~AudioTone();
};

/**
 * AudioBase base class for many other audio classes which stream
 * data.
 *
 * @short common audio stream base.
 */
class __EXPORT AudioBase : public Audio
{
private:
    __DELETE_COPY(AudioBase);

protected:
    Info info;

    /**
     * Abstract interface to get raw data.
     *
     * @return data received in buffer.
     * @param data to get.
     * @param size of data to get.
     */
    virtual ssize_t getBuffer(Encoded data, size_t size) = 0;

public:
    /**
     * Create audio base object with no info.
     */
    AudioBase();

    /**
     * Create audio base object with audio source description.
     *
     * @param info source description.
     */
    AudioBase(Info *info);

    /**
     * Destroy an audio base object.
     */
    virtual ~AudioBase();

    /**
     * Generic get encoding.
     *
     * @return audio encoding of this object.
     */
    inline Encoding getEncoding(void) const
        {return info.encoding;}

    /**
     * Generic sample rate.
     *
     * @return audio sample rate of this object.
     */
    inline unsigned getSampleRate(void) const
        {return info.rate;}

    /**
     * Abstract interface to put raw data.
     *
     * @param data to put.
     * @param size of data to put.
     * @return number of bytes actually put.
     */
    virtual ssize_t putBuffer(Encoded data, size_t size) = 0;

    /**
     * Puts raw data and does native to refined endian swapping
     * if needed based on encoding type and local machine endian.
     *
     * @param data to put.
     * @param size of data to put.
     * @return number of bytes actually put.
     */
    ssize_t putNative(Encoded data, size_t size);

    /**
     * Get's a packet of audio data.
     *
     * @return count of data received.
     * @param data to get.
     */
    inline ssize_t getPacket(Encoded data)
        {return getBuffer(data, 0);}

    /**
     * Get raw data and assure is in native machine endian.
     *
     * @return data received in buffer.
     * @param data to get.
     * @param size of data to get.
     */
    ssize_t getNative(Encoded data, size_t size);
};

/**
 * The AudioBuffer class is for mixing one-to-one
 * soft joins.
 *
 * @author Mark Lipscombe <markl@gasupnow.com>
 * @short audio buffer mixer class
 */
class __EXPORT AudioBuffer : public AudioBase
{
private:
    __DELETE_DEFAULTS(AudioBuffer);

public:
    AudioBuffer(Info *info, size_t size = 4096);
    virtual ~AudioBuffer();

    /**
     * save audio data from buffer data.
     *
     * @return number of bytes actually saved.
     * @param data save buffer.
     * @param number of bytes to save.
     */
    ssize_t get(Encoded data, size_t number);

    /**
     * Put data into the audio buffer.
     *
     * @return number of bytes actually put.
     * @param data of data to load.
     * @param number of bytes to load.
     */
    ssize_t put(Encoded data, size_t number);

private:
    char *buf;
    size_t size, start, len;
    mutex_t mutex;
};

/**
 * 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@ostel.com>
 * @short audio file access.
 */
class __EXPORT AudioFile: public AudioBase
{
private:
    __DELETE_COPY(AudioFile);

protected:
    char *pathname;
    Error error;
    unsigned long header;       // offset to start of audio
    unsigned long minimum;      // minimum sample size required
    unsigned long length;           // current size of file, including header

    void initialize(void);
    void getWaveFormat(int size);

    union {
        int fd;
        void *handle;
    } file;

    Mode mode;
    unsigned long iolimit;

    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);

    /**
     * Read a given number of bytes from the file, starting from
     * the current file pointer.  May be overridden by derived
     * classes.
     *
     * @param data A pointer to the buffer to copy the bytes to.
     * @param size The number of bytes to read.
     * @return 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 int afRead(unsigned char *data, unsigned size);

    /**
     * Write a number of bytes into the file at the current file
     * pointer.  May be overridden by derived classes.
     *
     * @param data A pointer to the buffer with the bytes to write.
     * @param size The number of bytes to write from the buffer.
     * @return 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.
     */
    virtual int afWrite(unsigned char *data, unsigned size);

    /**
     * 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.
     *
     * @param pos The position to seek to.
     * @return true if successful, false otherwise.
     */
    virtual bool afSeek(unsigned long pos);

    /**
     * Close the derived file handling system's file handle.
     */
    virtual void afClose(void);

    /**
     * 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.
     *
     * @return next file to open or NULL when done.
     */
    virtual char *getContinuation(void)
        {return NULL;}

    /**
     * Return a human-readable error message given a numeric error
     * code of type Audio::Error.
     *
     * @param err The numeric error code to translate.
     * @return A pointer to a character string containing the
     * human-readable error message.
     */
    const char *getErrorStr(Error err) const;

    Error setError(Error err);

    /**
     * Get number of bytes in the file header.  Data packets will
     * begin after this header.
     *
     * @return number of bytes in file header.
     */
    inline unsigned long getHeader(void) const
        {return header;}

    /**
     * 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.  The info type of the
     * object is used to determine the endian format.
     *
     * @return short value.
     * @param data binary 2 byte data pointer.
     */
    unsigned short getShort(unsigned char *data) const;

    /**
     * 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.
     *
     * @param data binary 2 byte data pointer.
     * @param value to convert.
     */
    void setShort(unsigned char *data, unsigned short value);

    /**
     * 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.  The object's info
     * order is used to determine the endian.
     *
     * @return long value.
     * @param data binary 4 byte data pointer.
     */
    unsigned long getLong(unsigned char *data) const;

    /**
     * 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.
     *
     * @param data binary 4 byte data pointer.
     * @param value to convert.
     */
    void setLong(unsigned char *data, unsigned long value);

public:
    /**
     * Construct and open an existing audio file for read/write.
     *
     * @param name of file to open.
     * @param offset to start access.
     */
    AudioFile(const char *name, unsigned long offset = 0);

    /**
     * Create and open a new audio file for writing.
     *
     * @param name of file to create.
     * @param info source description for new file.
     * @param minimum file size to accept at close.
     */
    AudioFile(const char *name, Info *info, unsigned long minimum = 0);

    /**
     * Construct an audio file without attaching to the filesystem.
     */
    inline AudioFile()
        {initialize();}

    virtual ~AudioFile();

    /**
     * Open an audio file and associate it with this object.
     * Called implicitly by the two-argument version of the
     * constructor.
     *
     * @param name of the file to open.  Don't forget to
     * double your backslashes for DOS-style pathnames.
     * @param mode to open file under.
     * @param framing time in milliseconds.
     */
    void open(const char *name, Mode mode = modeWrite, 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.
     *
     * @param name The name of the file to open.
     * @param info The type of the audio file to be created.
     * @param exclusive create option.
     * @param framing time in milliseconds.
     */
    void create(const char *name, Info *info, bool exclusive = false, timeout_t framing = 0);

    /**
     * Returns age since last prior access.  Used for cache
     * computations.
     *
     * @return age in seconds.
     */
    time_t age(void);

    /**
     * Get maximum size of frame buffer for data use.
     *
     * @return max frame size in bytes.
     */
    inline size_t getSize(void)
        {return maxFramesize(info);}

    /**
     * Close an object associated with an open file.  This
     * updates the header metadata with the file length if the
     * file length has changed.
     */
    void close(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 clear(void);

    /**
     * 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().
     *
     * @param buffer area to copy the samples to.
     * @param len The number of bytes (not samples) to copy or 0 for frame.
     * @return The number of bytes (not samples) read.  Returns -1
     * if no bytes are read and an error occurs.
     */
    ssize_t getBuffer(Encoded buffer, size_t len = 0);

    /**
     * Retrieve and convert content to linear encoded audio data
     * from it's original form.
     *
     * @param buffer to copy linear data into.
     * @param request number of linear samples to extract or 0 for frame.
     * @return number of samples retrieved, 0 if no codec or eof.
     */
    unsigned getLinear(Linear buffer, unsigned request = 0);

    /**
     * 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().
     *
     * @param buffer area to append the samples from.
     * @param len The number of bytes (not samples) to append.
     * @return The number of bytes (not samples) read.  Returns -1
     * if an error occurs and no bytes are written.
     */
    ssize_t putBuffer(Encoded buffer, size_t len = 0);

    /**
     * Convert and store content from linear encoded audio data
     * to the format of the audio file.
     *
     * @param buffer to copy linear data from.
     * @param request Number of linear samples to save or 0 for frame.
     * @return number of samples saved, 0 if no codec or eof.
     */
    unsigned putLinear(Linear buffer, unsigned request = 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().
     *
     * @param buffer pointer to copy the samples to.
     * @param samples The number of samples to read or 0 for frame.
     * @return errSuccess if successful, !errSuccess if
     * error.  Use getErrorStr() to retrieve the human-readable
     * error string.
     */
    Error getSamples(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().
     *
     * @param buffer pointer to append the samples from.
     * @param samples The number of samples (not bytes) to append.
     * @return errSuccess if successful, !errSuccess if
     * error.  Use getErrorStr() to retrieve the human-readable
     * error string.
     */
    Error putSamples(void *buffer, unsigned samples = 0);

    /**
     * Change the file position by skipping a specified number
     * of audio samples of audio data.
     *
     * @return errSuccess or error condition on failure.
     * @param number of samples to skip.
     */
    Error skip(long number);

    /**
     * Seek a file position by sample count.  If no position
     * specified, then seeks to end of file.
     *
     * @return errSuccess or error condition on failure.
     * @param samples position to seek in file.
     */
    Error setPosition(unsigned long samples = ~0l);

    /**
     * Seek a file position by timestamp.  The actual position
     * will be rounded by framing.
     *
     * @return errSuccess if successful.
     * @param timestamp position to seek.
     */
    Error position(const char *timestamp);

    /**
     * Return the timestamp of the current absolute file position.
     *
     * @param timestamp to save ascii position into.
     * @param size of timestamp buffer.
     */
    void getPosition(char *timestamp, size_t size);

    /**
     * Set the maximum file position for reading and writing of
     * audio data by samples.  If 0, then no limit is set.
     *
     * @param maximum file i/o access size sample position.
     * @return errSuccess if successful.
     */
    Error setLimit(unsigned long maximum = 0l);

    /**
     * Copy the source description of the audio file into the
     * specified object.  Can set error state of object if fails.
     *
     * @param info pointer to object to copy source description into.
     * @return errSucess.
     */
    Error getInfo(Info *info);

    /**
     * Set minimum file size for a created file.  If the file
     * is closed with fewer samples than this, it will also be
     * deleted.
     *
     * @param minimum number of samples for new file.
     * @return errSuccess if successful.
     */
    Error setMinimum(unsigned long minimum);

    /**
     * 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.
     *
     * @return 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.
     */
    unsigned long getAbsolutePosition(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 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.
     */
    unsigned long getPosition(void);

    /**
     * Test if the file is opened.
     *
     * @return true if a file is open.
     */
    virtual bool is_open(void) const;

    /**
     * Return audio encoding format for this audio file.
     *
     * @return audio encoding format.
     */
    inline Encoding getEncoding(void) const
        {return info.encoding;}

    /**
     * Return base file format of containing audio file.
     *
     * @return audio file container format.
     */
    inline Format getFormat(void) const
        {return info.format;}

    /**
     * Get audio encoding sample rate, in samples per second, for
     * this audio file.
     *
     * @return sample rate.
     */
    inline unsigned getSampleRate(void) const
        {return info.rate;}

    /**
     * Get annotation extracted from header of containing file.
     *
     * @return annotation text if any, else NULL.
     */
    inline char *getAnnotation(void) const
        {return info.annotation;}

    /**
     * Get last error code.
     *
     * @return alst error code.
     */
    inline Error getError(void) const
        {return error;}

    inline operator bool() const
        {return is_open();}

    inline bool operator!(void) const
        {return (bool)!is_open();}

    /**
     * Return if the current content is signed or unsigned samples.
     *
     * @return true if signed.
     */
    bool is_signed(void) const;
};

/**
 * AudioStream accesses AudioFile base class content as fixed frames
 * of streaming linear samples.  If a codec must be assigned to perform
 * conversion to/from linear data, AudioStream will handle conversion
 * automatically.  AudioStream will also convert between mono and stereo
 * audio content.  AudioStream uses linear samples in the native
 * machine endian format and perform endian byte swapping as needed.
 *
 * @author David Sugar <dyfet@ostel.com>
 * @short Audio Streaming with Linear Conversion
 */
class __EXPORT AudioStream : public AudioFile
{
private:
    __DELETE_COPY(AudioStream);

protected:
    AudioCodec *codec;  // if needed
    Encoded framebuf;
    bool streamable;
    Linear bufferFrame;
    unsigned bufferPosition;
    unsigned bufferChannels;
    Linear encBuffer, decBuffer;
    unsigned encSize, decSize;

    unsigned bufAudio(Linear samples, unsigned count, unsigned size);

public:
    /**
     * Create a new audiostream object.
     */
    AudioStream();

    /**
     * Create an audio stream object and open an existing audio file.
     *
     * @param name of file to open.
     * @param mode of file access.
     * @param framing time in milliseconds.
     */
    AudioStream(const char *name, Mode mode = modeRead, timeout_t framing = 0);

    /**
     * Create an audio stream object and a new audio file.
     *
     * @param name of file to open.
     * @param info source description for properties of new file.
     * @param exclusive access if true.
     * @param framing time in milliseconds.
     */
    AudioStream(const char *name, Info *info, bool exclusive = false, timeout_t framing = 0);

    virtual ~AudioStream();

    /**
     * Virtual for packet i/o intercept.
     *
     * @return bytes read.
     * @param data encoding buffer.
     * @param count requested.
     */
    ssize_t getBuffer(Encoded data, size_t count);

    /**
     * Open existing audio file for streaming.
     *
     * @param name of file to open.
     * @param mode to use file.
     * @param framing timer in milliseconds.
     */
    void open(const char *name, Mode mode = modeRead, timeout_t framing = 0);

    /**
     * Create a new audio file for streaming.
     *
     * @param name of file to create.
     * @param info source description for file properties.
     * @param exclusive true for exclusive access.
     * @param framing timing in milliseconds.
     */
    void create(const char *name, Info *info, bool exclusive = false, timeout_t framing = 0);

    /**
     * Close the currently open audio file for streaming.
     */
    void close(void);

    /**
     * flush any unsaved buffered data to disk.
     */
    void flush(void);

    /**
     * Check if the audio file may be streamed.  Files can be
     * streamed if a codec is available or if they are linear.
     *
     * @return true if streamable.
     */
    bool is_streamable(void);

    /**
     * Get the number of samples expected in a frame.
     */
    unsigned getCount(void);    // frame count

    /**
     * Stream audio data from the file and convert into an alternate
     * encoding based on the codec supplied.
     *
     * @param codec to apply before saving.
     * @param address of data to save.
     * @param frames to stream by the codec.
     * @return number of frames processed.
     */
    unsigned getEncoded(AudioCodec *codec, Encoded address, unsigned frames = 1);

    /**
     * Stream audio data in an alternate codec into the currently
     * opened file.
     *
     * @param codec to convert incoming data from.
     * @param address of data to convert and stream.
     * @param frames of audio to stream.
     * @return number of frames processed.
     */
    unsigned putEncoded(AudioCodec *codec, Encoded address, unsigned frames = 1);

    /**
     * Get data from the streamed file in it's native encoding.
     *
     * @param address to save encoded audio.
     * @param frames of audio to load.
     * @return number of frames read.
     */
    unsigned getEncoded(Encoded address, unsigned frames = 1);

    /**
     * Put data encoded in the native format of the stream file.
     *
     * @param address to load encoded audio.
     * @param frames of audio to save.
     * @return number of frames written.
     */
    unsigned putEncoded(Encoded address, unsigned frames = 1);

    /**
     * Get a packet of data from the file.  This uses the codec
     * to determine what a true packet boundry is.
     *
     * @param buffer to save encoded data.
     * @return number of bytes read as packet.
     */
    ssize_t getPacket(Encoded data);

    /**
     * Get and automatically convert audio file data into
     * mono linear audio samples.
     *
     * @param buffer to save linear audio into.
     * @param frames of audio to read.
     * @return number of frames read from file.
     */
    unsigned getMono(Linear buffer, unsigned frames = 1);

    /**
     * Get and automatically convert audio file data into
     * stereo (two channel) linear audio samples.
     *
     * @param buffer to save linear audio into.
     * @param frames of audio to read.
     * @return number of frames read from file.
     */
    unsigned getStereo(Linear buffer, unsigned frames = 1);

    /**
     * Automatically convert and put mono linear audio data into
     * the audio file.  Convert to stereo as needed by file format.
     *
     * @param buffer to save linear audio from.
     * @param frames of audio to write.
     * @return number of frames written to file.
     */
    unsigned putMono(Linear buffer, unsigned frames = 1);

    /**
     * Automatically convert and put stereo linear audio data into
     * the audio file.  Convert to mono as needed by file format.
     *
     * @param buffer to save linear audio from.
     * @param frames of audio to write.
     * @return number of frames written to file.
     */
    unsigned putStereo(Linear buffer, unsigned frames = 1);

    /**
     * Automatically convert and put arbitrary linear mono data
     * into the audio file.  Convert to stereo and buffer incomplete
     * frames as needed by the streaming file.
     *
     * @param buffer to save linear audio from.
     * @param count of linear audio to write.
     * @return number of linear audio samples written to file.
     */
    unsigned bufMono(Linear buffer, unsigned count);

    /**
     * Automatically convert and put arbitrary linear stereo data
     * into the audio file.  Convert to mono and buffer incomplete
     * frames as needed by the streaming file.
     *
     * @param buffer to save linear audio from.
     * @param count of linear audio to write.
     * @return number of linear audio samples written to file.
     */
    unsigned bufStereo(Linear buffer, unsigned count);

    /**
     * Return the codec being used if there is one.
     *
     * @return codec used.
     */
    inline AudioCodec *getCodec(void)
        {return codec;}
};

/**
 * 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@ostel.com>
 * @short process codec interface.
 */
class __EXPORT AudioCodec : public Audio, public LinkedObject
{
private:
    __DELETE_COPY(AudioCodec);

protected:
    Encoding encoding;
    const char *name;
    Info info;

    AudioCodec();

    /**
     * often used to create a "new" codec of a subtype based on
     * encoding format, default returns the current codec entity.
     *
     * @return pointer to an active codec or NULL if not found.
     * @param format name from spd.
     */
    virtual AudioCodec *getByFormat(const char *format)
        {return this;}

    /**
     * get a codec by audio source info descriptor.
     *
     * @return pointer to an active codec or NULL if not found.
     * @param info audio source descriptor.
     */
    virtual AudioCodec *getByInfo(Info &info)
        {return this;}

public:
    /**
     * Base for codecs, create a named coded of a specific encoding.
     *
     * @param name of codec.
     * @param encoding type of codec.
     */
    AudioCodec(const char *name, Encoding encoding);

    inline const char *getName(void) const
        {return name;}

    inline const char *getDescription(void) const
        {return info.annotation;}

    virtual ~AudioCodec() {}

    /**
     * End use of a requested codec.  If constructed then will be
     * deleted.
     *
     * @param codec pointer to getCodec returned coded pointer.
     */
    static void release(AudioCodec *codec);

    static AudioCodec *begin(void);

    /**
     * Get the codec base class for accessing a specific derived
     * codec identified by encoding type and optional spd info.
     *
     * @return pointer to codec for processing.
     * @param encoding format requested.
     * @param format spd options to pass to codec being created.
     */
    static AudioCodec *get(Encoding encoding, const char *format = NULL);

    /**
     * Get the codec base class for accessing a specific derived
     * codec identified by audio source descriptor.
     *
     * @return pointer to codec for processing.
     * @param info source descriptor for codec being requested.
     */
    static AudioCodec *get(Info &info);

    /**
     * Get the impulse energy level of a frame of X samples in
     * the specified codec format.
     *
     * @return average impulse energy of frame (sumnation).
     * @param buffer of encoded samples.
     * @param number of encoded samples.
     */
    virtual Level impulse(void *buffer, unsigned number = 0);

    /**
     * Get the peak energy level within the frame of X samples.
     *
     * @return peak energy impulse in frame (largest).
     * @param buffer of encoded samples.
     * @param number of encoded samples.
     */
    virtual Level peak(void *buffer, unsigned number = 0);

    /**
     * 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.
     *
     * @return true if silent
     * @param threashold to use if not signaled.
     * @param buffer of encoded samples.
     * @param number of encoded samples.
     */
    virtual bool is_silent(Level threashold, void *buffer, unsigned number = 0);

    /**
     * Encode a linear sample frame into the codec sample buffer.
     *
     * @return number of bytes written.
     * @param buffer linear sample buffer to use.
     * @param dest buffer to store encoded results.
     * @param number of samples.
     */
    virtual unsigned encode(Linear buffer, void *dest, unsigned number = 0) = 0;

    /**
     * Encode linear samples buffered into the coded.
     *
     * @return number of bytes written or 0 if incomplete.
     * @param buffer linear samples to post.
     * @param destination of encoded audio.
     * @param number of samples being buffered.
     */
    virtual unsigned encodeBuffered(Linear Buffer, Encoded dest, unsigned number);

    /**
     * Decode the sample frame into linear samples.
     *
     * @return number of bytes scanned or returned
     * @param buffer sample buffer to save linear samples into.
     * @param source for encoded data.
     * @param number of samples to extract.
     */
    virtual unsigned decode(Linear buffer, void *source, unsigned number = 0) = 0;

    /**
     * Buffer and decode data into linear samples.  This is needed
     * for audio formats that have irregular packet sizes.
     *
     * @return number of samples actually decoded.
     * @param destination for decoded data.
     * @param source for encoded data.
     * @param number of bytes being sent.
     */
    virtual unsigned decodeBuffered(Linear buffer, Encoded source, unsigned len);

    /**
     * Get estimated data required for buffered operations.
     *
     * @return estimated number of bytes required for decode.
     */
    virtual unsigned getEstimated(void);

    /**
     * get required samples for encoding.
     *
     * @return required number of samples for encoder buffer.
     */
    virtual unsigned getRequired(void);

    /**
     * Get a packet of data rather than decode.  This is tied with
     * getEstimated.
     *
     * @return size of data packet or 0 if not complete.
     * @param destination to save.
     * @param data to push into buffer.
     * @param number of bytes to push.
     */
    virtual unsigned getPacket(Encoded destination, Encoded data, unsigned size);

    /**
     * Get an info description for this codec.
     *
     * @return info.
     */
    inline Info getInfo(void) const
        {return info;}
};

class __EXPORT AudioDevice : public AudioBase
{
private:
    __DELETE_COPY(AudioDevice);

protected:
    bool enabled;

public:
    inline AudioDevice() {}

    virtual ~AudioDevice() {}

    /**
     * Copy linear samples to an audio device through its virtual.
     *
     * @param buffer to linear audio data to play.
     * @param count of audio samples to play.
     * @return number of audio samples played.
     */
    virtual unsigned putSamples(Linear buffer, unsigned count) = 0;

    /**
     * Copy linear samples from an audio device through its virtual.
     *
     * @param buffer for recording.
     * @param count of audio samples to record.
     * @return number of audio samples recorded.
     */
    virtual unsigned getSamples(Linear buffer, unsigned count) = 0;

    /**
     * Copy audio encoded in the currently selected encoding for
     * the audio device.
     *
     * @param data pointer to encoded data to play.
     * @param count of encoded bytes to play.
     * @return number of encoded bytes played.
     */
    virtual ssize_t putBuffer(Encoded data, size_t count);

    /**
     * Record audio encoded in the currently selected encoding for
     * the audio device.
     *
     * @param data buffer for recording encoded audio.
     * @param count of encoded bytes to record.
     * @return number of encoded bytes recorded.
     */
    virtual ssize_t getBuffer(Encoded data, size_t count);

    /**
     * Use encoding source descriptor to select the audio encoding
     * format the audio device should be using.
     *
     * @return false if encoding format specified is unsupported by device
     * @param info source description for device settings.
     */
    virtual bool setEncoded(Info &info)
        {return false;}

    /**
     * Set properties for audio device.
     *
     * @param rate of audio samples device should operate at.
     * @param stereo flag.
     * @param framing timer for default i/o framing for device.
     * @return false if settings not supported by device.
     */
    virtual bool setAudio(Rate rate = rate8khz, bool stereo = false, timeout_t framing = 20) = 0;

    /**
     * Synchronize timing for audio device to next audio frame.
     * this is needed for audio devices which do not block i/o to
     * assure one does not push too much data before the device
     * can handle it.
     */
    virtual void sync(void)
        {return;}

    /**
     * Flush any pending buffered samples in audio device.
     */
    virtual void flush(void) = 0;

    /**
     * Process linear mono audio and automatically convert to the
     * encoding format the audio device is currently using.
     * If needed, automatically convert from mono to stereo.
     *
     * @return number of samples played.
     * @param buffer to linear mono audio data to play.
     * @param count of linear mono audio samples to play.
     */
    unsigned bufMono(Linear buffer, unsigned count);

    /**
     * Process linear stereo audio and automatically convert to the
     * encoding format the audio device is currently using.
     * If needed, automatically convert from stereo to mono.
     *
     * @return number of samples played.
     * @param buffer to linear stereo audio data to play.
     * @param count of linear stereo audio samples to play.
     */
    unsigned bufStereo(Linear buffer, unsigned count);

    /**
     * Get audio device source descriptor in effect for the device.
     *
     * @return audio device descriptor.
     */
    inline const Info *getInfo(void) const
        {return &info;}

    /**
     * Whether device is currently enabled.  If invalid audio
     * settings are selected, it will be disabled until supported
     * values are supplied.
     *
     * @return enable state.
     * @see #setAudio #setInfo
     */
    inline bool is_enabled(void) const
        {return enabled;}
};

/**
 * An object that is used to sequence and extract telephony tones
 * based on a telephony tone descriptor retrieved from the parsed
 * international telephony tone database.
 *
 * @author David Sugar <dyfet@ostel.com>
 * @short telephony tone sequencing object.
 */
class __EXPORT TelTone : public AudioTone
{
private:
    __DELETE_DEFAULTS(TelTone);

public:
    typedef struct _tonedef {
        struct _tonedef *next;
        timeout_t duration, silence;
        unsigned count;
        unsigned short f1, f2;
    } tonedef_t;

    typedef struct _tonekey {
        struct _tonekey *next;
        struct _tonedef *first;
        struct _tonedef *last;
        char id[1];
    } tonekey_t;

    /**
     * Create a tone sequencing object for a specific telephony tone
     * key id.
     *
     * @param key for telephony tone.
     * @param level for generated tones.
     * @param frame timing to use in processing.
     */
    TelTone(tonekey_t *key, Level level, timeout_t frame = 20);
    ~TelTone();

    /**
     * Generate and retrieve one frame of linear audio data for
     * the telephony tone sequence being created.
     *
     * @return pointer to samples generated.
     */
    Linear getFrame(void) __OVERRIDE;

    /**
     * Check if all audio frames for this tone has been created.
     * Some telephony tones, such as dialtone, may be infinite...
     *
     * @return true if audio is complete.
     */
    bool is_complete(void) __OVERRIDE;


    /**
     * Load a teltones database file into memory.
     *
     * @return true if successful
     * @param pathname of file to load.
     * @param locale to optionally load.
     */
    static bool load(const char *pathname, const char *locale = NULL);

    /**
     * find an entry in the teltones database.
     *
     * @return key of tone list if found, else NULL
     * @param tone name
     * @param locale to optionally search under
     */
    static tonekey_t *find(const char *tone, const char *locale = NULL);

protected:
    tonekey_t *tone;
    tonedef_t *def;
    unsigned remaining, silent, count;
    timeout_t framing;
    Level level;
    bool complete;
};

/**
 * DTMFTones is used to generate a series of dtmf audio data from a
 * "telephone" number passed as an ASCII string.  Each time getFrame()
 * is called, the next audio frame of dtmf audio will be created
 * and pulled.
 *
 * @author David Sugar <dyfet@ostel.com>
 * @short Generate DTMF audio
 */
class __EXPORT DTMFTones : public AudioTone
{
private:
    __DELETE_DEFAULTS(DTMFTones);

protected:
    unsigned remaining, dtmfframes;
    timeout_t frametime;
    const char *digits;
    Level level;
    bool complete;

public:
    /**
     * Generate a dtmf dialer for a specified dialing string.
     *
     * @param digits to generate tone dialing for.
     * @param level for dtmf.
     * @param duration timing for generated audio.
     * @param interdigit timing, should be multiple of frame.
     */
    DTMFTones(const char *digits, Level level, timeout_t duration = 20, timeout_t interdigit = 60);

    ~DTMFTones();

    Linear getFrame(void) __OVERRIDE;
    bool is_complete(void) __OVERRIDE;
};

/**
 * MFTones is used to generate a series of mf audio data from a
 * "telephone" number passed as an ASCII string.  Each time getFrame()
 * is called, the next audio frame of dtmf audio will be created
 * and pulled.
 *
 * @author David Sugar <dyfet@ostel.com>
 * @short Generate MF audio
 */
class __EXPORT MFTones : public AudioTone
{
private:
    __DELETE_DEFAULTS(MFTones);

protected:
    unsigned remaining, mfframes;
    timeout_t frametime;
    const char *digits;
    Level level;
    bool complete, kflag;

public:
    /**
     * Generate a mf dialer for a specified dialing string.
     *
     * @param digits to generate tone dialing for.
     * @param level for mf.
     * @param duration timing for generated audio.
     * @param interdigit timing, should be multiple of frame.
     */
    MFTones(const char *digits, Level level, timeout_t duration = 20, timeout_t interdigit = 60);

    ~MFTones();

    Linear getFrame(void) __OVERRIDE;
    bool is_complete(void) __OVERRIDE;
};


/**
 * DTMFDetect is used for detecting DTMF tones in a stream of audio.
 * It currently only supports 8000Hz input.
 */
class __EXPORT DTMFDetect : public Audio
{
private:
    __DELETE_COPY(DTMFDetect);

public:
    DTMFDetect();
    ~DTMFDetect();

    /**
     * This routine is used to push linear audio data into the
     * dtmf tone detection analysizer.  It may be called multiple
     * times and results fetched later.
     *
     * @param buffer of audio data in native machine endian to analysize.
     * @param count of samples to analysize from buffer.
     */
    int putSamples(Linear buffer, int count);

    /**
     * Copy detected dtmf results into a data buffer.
     *
     * @param data buffer to copy into.
     * @param size of data buffer to copy into.
     */
    int getResult(char *data, int size);

protected:
    void goertzelInit(goertzel_state_t *s, tone_detection_descriptor_t *t);
    void goertzelUpdate(goertzel_state_t *s, Sample x[], int samples);
    float goertzelResult(goertzel_state_t *s);

private:
    dtmf_detect_state_t *state;
    tone_detection_descriptor_t dtmf_detect_row[4];
    tone_detection_descriptor_t dtmf_detect_col[4];
    tone_detection_descriptor_t dtmf_detect_row_2nd[4];
    tone_detection_descriptor_t dtmf_detect_col_2nd[4];
    tone_detection_descriptor_t fax_detect;
    tone_detection_descriptor_t fax_detect_2nd;
};

} // namespace ucommon

#endif