/**********************************************************************
Audio i/o module

$Id: audio.h,v 1.7 2003/01/19 23:17:09 purnhage Exp $

Header file: audio.h

(c) Heiko Purnhagen 1996-2003
e-mail: purnhage@tnt.uni-hannover.de
WWW:    http://www.tnt.uni-hannover.de/~purnhage/

This module is available under the terms of the GNU Lesser General
Public License. See file COPYING-LGPL for further details. All usual
disclaimers apply!

Required libraries (if USE_AFSP is defined):
libtsp.a		AFsp audio file library

Required modules:
common.o		common module
austream.o		audio i/o streams (.au format)

Authors:
HP    Heiko Purnhagen, Uni Hannover <purnhage@tnt.uni-hannover.de>

Changes:
21-jan-96   HP    born (using AFsp-V2R2)
19-feb-97   HP    made internal data structures invisible
30-dec-98   HP    uses austream for stdin/stdout, evaluates USE_AFSP
07-jan-99   HP    AFsp-v4r1 (AFsp-V3R2 still supported)
31-Aug-2000 HP/RS added INT24 output format support
22-Jul-2001 HP    added interleaved multichannel data i/o
                  AudioReadDataIntlvd(), AudioWriteDataIntlvd()
**********************************************************************/


/**********************************************************************

The audio i/o module provides an interface to the basic functions for
PCM audio data stream input and output.

The current implementation of the audio i/o module is based on the
AFsp audio library. If USE_AFSP is undefined, only 16 bit .au files
are supported using the austream module. Audio i/o on stdin/stdout
(only 16 bit .au) is also based on the austream module.

NOTE: For multi channel audio files, the number of samples per channel
      (numSample) is used as parameter!!! The total number of samples
      (numSample*numChannel) is not used here.

NOTE: Only for AudioReadDataIntlvd() and AudioWriteDataIntlvd():
        Multi channel data is interleaved: l0 r0 l1 r1 ...
        Total number of samples (over all channels) is used.

**********************************************************************/


#ifndef _audio_h_
#define _audio_h_


/* ---------- declarations ---------- */

typedef struct AudioFileStruct AudioFile;	/* audio file handle */


/* ---------- functions ---------- */

#ifdef __cplusplus
extern "C" {
#endif


/* AudioInit() */
/* Init audio i/o module. */
/* formatString options: see AFsp documentation */

void AudioInit (
  char *formatString,		/* in: input format for headerless files */
				/*     or NULL for AFsetNHpar() defaults */
  int writeInt24,		/* in: output format resolution */
				/*     0=16bit(default)  1=24bit */
  int debugLevel);		/* in: debug level */
				/*     0=off(default)  1=basic  2=full */


/* AudioOpenRead() */
/* Open audio file for reading. */
/* For headerless files, the format can be specified using AudioInit(). */

AudioFile *AudioOpenRead (
  char *fileName,		/* in: file name */
				/*     "-": stdin (only 16 bit .au) */
  int *numChannel,		/* out: number of channels */
  float *fSample,		/* out: sampling frequency [Hz] */
  long *numSample);		/* out: number of samples in file */
				/*      (samples per channel!) */
				/*      or -1 if unknown */
				/* returns: */
				/*  audio file (handle) */
				/*  or NULL if error */


/* AudioOpenWrite() */
/* Open audio file for writing. */
/* Sample format: 16 bit twos complement, uniform quantisation */
/*                or 24 bit if specified using AudioInit() */
/* Supported file formats: (matching substring of format) */
/*  au, snd:  Sun (AFsp) audio file */
/*  wav:      RIFF WAVE file */
/*  aif:      AIFF-C audio file */
/*  raw:      headerless (raw) audio file (native byte order) */

AudioFile *AudioOpenWrite (
  char *fileName,		/* in: file name */
				/*     "-": stdout (only 16 bit .au) */
  char *format,			/* in: file format (ignored if stdout) */
				/*     (au, snd, wav, aif, raw) */
  int numChannel,		/* in: number of channels */
  float fSample);		/* in: sampling frequency [Hz] */
				/* returns: */
				/*  audio file (handle) */
				/*  or NULL if error */


/* AudioReadDataIntlvd() */
/* Read data from audio file (channels interleaved). */
/* Requested samples that could not be read from the file are set to 0. */

long AudioReadDataIntlvd (
  AudioFile *file,		/* in: audio file (handle) */
  float *data,			/* out: data[sample] */
				/*      (range [-32768 .. 32767]) */
				/*      (interleaved: l0 r0 l1 r1 ...) */
  long numSample);		/* in: total number of samples to be read */
				/* returns: */
				/*  total number of samples read */


/* AudioWriteDataIntlvd() */
/* Write data to audio file (channels interleaved). */

void AudioWriteDataIntlvd (
  AudioFile *file,		/* in: audio file (handle) */
  float *data,			/* in: data[sample] */
				/*     (range [-32768 .. 32767]) */
				/*     (interleaved: l0 r0 l1 r1 ...) */
  long numSample);		/* in: total number of samples to be written */


/* AudioReadData() */
/* Read data from audio file. */
/* Requested samples that could not be read from the file are set to 0. */

long AudioReadData (
  AudioFile *file,		/* in: audio file (handle) */
  float **data,			/* out: data[channel][sample] */
				/*      (range [-32768 .. 32767]) */
  long numSample);		/* in: number of samples to be read */
				/*     (samples per channel!) */
				/* returns: */
				/*  number of samples read */
				/*  (samples per channel!) */


/* AudioWriteData() */
/* Write data to audio file. */

void AudioWriteData (
  AudioFile *file,		/* in: audio file (handle) */
  float **data,			/* in: data[channel][sample] */
				/*     (range [-32768 .. 32767]) */
  long numSample);		/* in: number of samples to be written */
				/*     (samples per channel!) */


/* AudioSeek() */
/* Set position in audio file to curSample. */
/* (Beginning of file: curSample=0) */
/* NOTE: It is not possible to seek backwards in a output file if */
/*       any samples were already written to the file. */

void AudioSeek (
  AudioFile *file,		/* in: audio file (handle) */
  long curSample);		/* in: new position [samples] */
				/*     (samples per channel!) */


/* AudioTell() */
/* Get current position in audio file. */
/* (Beginning of file: AudioTell=0) */

long AudioTell (
  AudioFile *file);		/* in: audio file (handle) */
				/* returns: */
				/*  current position [samples] */
				/*  (samples per channel!) */


/* AudioSize() */
/* Get size of audio file. */
  /* (i.e. numSample as returned by AudioOpenRead) */

long AudioSize (
  AudioFile *file);		/* in: audio file (handle) */
				/* returns: */
				/*  number of samples in file */
				/*  (samples per channel!) */
				/*  or -1 if unknown or write-mode */


/* AudioClose() */
/* Close audio file.*/

void AudioClose (
  AudioFile *file);		/* in: audio file (handle) */


#ifdef __cplusplus
}
#endif

#endif	/* #ifndef _audio_h_ */

/* end of audio.h */

