audio2.h

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

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

	/**
	 * 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 getImpulse(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 getImpulse(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 getPeak(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 getPeak(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);

	/**
	 * Load a dso plugin (codec plugin), used internally...
	 *
	 * @return true if loaded.
	 * @param path to codec.
	 */
	static bool loadPlugin(const char *path);

	/**
	 * 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);
};

/**
 * 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 <[e-mail]>
 * @short audio tone generator class.
 */
class __EXPORT AudioTone : public Audio
{
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)
		{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)
		{return samples;};

	/**
	 * Test if the tone generator is currently set to silence.
	 *
	 * @return true if generator set for silence.
	 */
	bool isSilent(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 isComplete(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
{
protected:
	Info info;

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)
        	{return info.encoding;};

	/**
	 * Generic sample rate.
	 *
	 * @return audio sample rate of this object.
	 */
	inline unsigned getSampleRate(void)
        	{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);

        /**
         * 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;

	/**
	 * 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 <[e-mail]>
 * @short audio buffer mixer class
 */
class __EXPORT AudioBuffer : public AudioBase
{
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 getBuffer(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 putBuffer(Encoded data, size_t number);

private:
        char *buf;
        size_t size, start, len;
	void *mutexObject;

	void enter(void);
	void leave(void);
};

/**
 * 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 <[e-mail]>
 * @short audio file access.
 */
class __EXPORT AudioFile: public AudioBase
{
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);
	void mp3info(mpeg_audio *mp3);

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

	/**