audio2.h

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

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

	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)
		{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.
	 *
	 * @return short value.
	 * @param data binary 2 byte data pointer.
	 */
	unsigned short getShort(unsigned char *data);

	/**
	 * 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.
         *
         * @return long value.
         * @param data binary 4 byte data pointer.
         */
	unsigned long getLong(unsigned char *data);

        /**
         * 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 getAge(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.
	 *
	 * @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 isOpen(void);

	/**
	 * Return true if underlying derived class supports direct
	 * access to file positioning.  Derived classes based on URL's
	 * or fifo devices may not have this ability.
	 *
	 * @return true if file positioning is supported.
	 */
	virtual bool hasPositioning(void)
		{return true;};

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

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

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

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

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

	inline bool operator!(void)
		{return (bool)!isOpen();};

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

/**
 * 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 <[e-mail]>
 * @short Audio Streaming with Linear Conversion
 */
class __EXPORT AudioStream : public AudioFile
{
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();

	/**
	 * 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 isStreamable(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 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.