audio2.h

GNU ccAudio2 is a stand-alone portable C++ class framework for manipulating audio data. It has exist

	 */
	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 <[e-mail]>
 * @short process codec interface.
 */
class __EXPORT AudioCodec : public Audio
{
protected:
	static AudioCodec *first;
	AudioCodec *next;
	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);

	virtual ~AudioCodec() {};

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

	/**
	 * 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.
	 * @param loaded true to load if not already in memory.
	 */
	static AudioCodec *getCodec(Encoding encoding, const char *format = NULL, bool loaded = false);

        /**
         * 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.
         * @param loaded true to load codec if not already in memory.
         */
	static AudioCodec *getCodec(Info &info, bool loaded = false);

	/**
	 * Load a named codec set into process memory.
	 *
	 * @return true if successful.
	 * @param name of codec set to load.
	 */
	static bool load(const char *name);

	/**
	 * Find and load a codec file by it's encoding type.  Converts
	 * the type into a codec name and invokes the other loader...
	 *
	 * @return true if successful.
	 * @param encoding type for file.
	 */
	static bool load(Encoding encoding);

	/**
	 * 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 getImpulse(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 getPeak(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 isSilent(Level threashold, void *buffer, unsigned number = 0);

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

	/**
	 * 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 or bytes to buffer.
	 * @patam true if buffered mode.
	 */
	virtual unsigned decode(Linear buffer, void *source, unsigned number = 0, bool buffered = false) = 0;

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

class __EXPORT AudioDevice : public AudioBase
{
protected:
	bool enabled;

public:
	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 Info *getInfo(void)
		{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 isEnabled(void)
		{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 <[e-mail]>
 * @short telephony tone sequencing object.
 */
class __EXPORT TelTone : public AudioTone
{
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);

	/**
	 * 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 isComplete(void);


	/**
	 * 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 <[e-mail]>
 * @short Generate DTMF audio
 */
class __EXPORT DTMFTones : public AudioTone
{
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);
	bool isComplete(void);
};

/**
 * 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 <[e-mail]>
 * @short Generate MF audio
 */
class __EXPORT MFTones : public AudioTone
{
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);
	bool isComplete(void);
};


/**
 * DTMFDetect is used for detecting DTMF tones in a stream of audio.
 * It currently only supports 8000Hz input.
 */
class __EXPORT DTMFDetect : public Audio
{
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;
};

}

#endif