audio2.h

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

// Copyright (C) 1999-2005 Open Source Telecom Corporation.
//  
// This program is free software; you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation; either version 2 of the License, or
// (at your option) any later version.
// 
// This program 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 General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with this program; if not, write to the Free Software 
// Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
//
// As a special exception, you may use this file as part of a free software
// library without restriction.  Specifically, if other files instantiate
// templates or use macros or inline functions from this file, or you compile
// this file and link it with other files to produce an executable, this
// file does not by itself cause the resulting executable to be covered by
// the GNU General Public License.  This exception does not however    
// invalidate any other reasons why the executable file might be covered by
// the GNU General Public License.    
//
// This exception applies only to the code released under the name GNU
// ccAudio.  If you copy code from other releases into a copy of GNU
// ccAudio, as the General Public License permits, the exception does
// not apply to the code that you add in this way.  To avoid misleading
// anyone as to the status of such modified files, you must delete
// this exception notice from them.
//
// If you write modifications of your own for GNU ccAudio, it is your choice
// whether to permit this exception to apply to your modifications.
// If you do not wish that, delete this exception notice.
//

/**
 * @file audio2.h
 * @short Framework for portable audio processing and file handling classes.
 **/


#ifndef	CCXX_AUDIO_H_
#define	CCXX_AUDIO_H_

#ifndef	CCXX_PACKING
#if defined(__GNUC__)
#define CCXX_PACKED
#elif !defined(__hpux) && !defined(_AIX)
#define CCXX_PACKED
#endif 
#endif

#ifndef	W32
#if defined(_WIN32) && defined(_MSC_VER)
#define	W32
#endif
#if defined(__BORLANDC__) && defined(__Windows)
#define	W32
#endif
#endif

#if !defined(__EXPORT) && defined(W32)
#define	__EXPORT __declspec(dllimport)
#endif

#ifndef	__EXPORT
#define	__EXPORT
#endif

#ifdef	W32
#include <windows.h>
#ifndef	ssize_t
#define	ssize_t	int
#endif
#else
#include <cstddef>
#include <cstdlib>
#include <sys/types.h>
#include <netinet/in.h>
#endif

#include <ctime>

namespace ost {

#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

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 <[e-mail]>
 * @short Master audio class.
 */
class __EXPORT Audio
{
public:
#ifdef	W32
	typedef	short	Sample;
	typedef	short	*Linear;
	typedef	short	Level;
	typedef	DWORD	timeout_t;
	typedef	WORD	snd16_t;
	typedef	DWORD	snd32_t;
#else
	typedef	int16_t snd16_t;
	typedef	int32_t	snd32_t;
	typedef	int16_t	Level;
	typedef	int16_t	Sample;
	typedef	int16_t	*Linear;
	typedef	unsigned long	timeout_t;
#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,
		rate16khz = 16000,
		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
	};
	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;


#ifdef	CCXX_PACKED
#pragma pack(1)
#endif

	typedef	struct 
	{
#if	__BYTE_ORDER == __LITTLE_ENDIAN
		unsigned char mp_sync1 : 8;
		unsigned char mp_crc   : 1;
		unsigned char mp_layer : 2;
		unsigned char mp_ver   : 2;
		unsigned char mp_sync2 : 3;

		unsigned char mp_priv  : 1;
		unsigned char mp_pad   : 1;
		unsigned char mp_srate : 2;
		unsigned char mp_brate : 4;

		unsigned char mp_emp   : 2;
		unsigned char mp_original : 1;
		unsigned char mp_copyright: 1;
		unsigned char mp_extend   : 2;
		unsigned char mp_channels : 2;

#else
                unsigned char mp_sync1 : 8;

                unsigned char mp_sync2 : 3;
                unsigned char mp_ver   : 2;
                unsigned char mp_layer : 2;
                unsigned char mp_crc   : 1;

                unsigned char mp_brate : 4;
                unsigned char mp_srate : 2;
                unsigned char mp_pad   : 1;
                unsigned char mp_priv  : 1;

                unsigned char mp_channels : 2;
                unsigned char mp_extend   : 2;
                unsigned char mp_copyright : 1;
                unsigned char mp_original : 1;
                unsigned char mp_emp : 2;
#endif
	}	mpeg_audio;

	typedef struct
	{
		char tag_id[3];
		char tag_title[30];
		char tag_artist[30];
		char tag_album[30];
		char tag_year[4];
		char tag_note[30];
		unsigned char genre;
	}	mpeg_tagv1;

#ifdef	CCXX_PACKED
#pragma pack()
#endif

	/**
	 * 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();
		void clear(void);
		void set(void);
		void setFraming(timeout_t frame);
	};

	/**
	 * 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 hasDevice(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 pathname to where loadable codec modules are stored.
	 *
	 * @return file path to loadable codecs.
	 */
	static const char *getCodecPath(void);

	/**
	 * 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 isLinear(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 isBuffered(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 isMono(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 isStereo(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 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 isEndian(Encoding encoding);