aconvert(3)							  aconvert(3)



NAME
  AConvertError, AConvertAllocInit, AConvertInit, AConvertFiles, AConvert,
  AConvertStats, AConvertClose - callable audio	conversion library


SYNTAX

       #include	<aconvert.h>

       char* AConvertError();

       AConvertCtxt* AConvertAlloc();

       AConvertCtxt* AConvertAllocInit(AEncodeType eInpType, int iInpFreq,
	int iInpChans, AEncodeType eOutType, int iOutFreq, int iOutChans);

       int AConvertInit(AConvertCtxt* tpACC, char* cpName, char* cpVal);

       int AConvertFiles(int argc, char** argv);

       int AConvert(AConvertCtxt* tpACC, int iCnt, void* vpSrc,	void* vppDst);

       void AConvertStats(AConvertCtxt*	tpACC);

       void AConvertClose(AConvertCtxt*	tpACC);


ARGUMENTS

  eInpType	  Type of input	as defined in audio.h

  iInpFreq	  Input	frequency in samples/second

  iInpChans	  Number of input channels

  eOutType	  Type of output as defined in audio.h

  iOutFreq	  Output frequency in samples/second

  iOutChans	  Number of output channels

  tpACC		  Current aconvert context

  cpName	  Name of init parameter to set

  cpVal		  Value	of init	parameter to set

  argc		  Command line arg count

  argv		  Command line argument	array

  iCnt		  Number of input units

  vpSrc		  Input	data buffer

  vppDst	  Returned output data buffer pointer



DESCRIPTION
  The libaconvert routines are used to convert between different audio data
  formats, sampling rates and sample sizes.

  The AConvertError routine returns a pointer to a libaconvert error message.
  It should be called after one	of the library routines	returns	an error
  status.

  The AConvertAlloc routine creates a new aconvert context (initialized	with
  all standard default values) and returns the value.

  The AConvertAllocInit	routine	creates	a new aconvert context and initial-
  izes it according to the specified parameters. The resulting context is
  then returned.

  The AConvertInit routine allows individual parameters	of an aconvert con-
  text to be set. Legal	parameters are:

       lfI lfI l l.  Parameter	     Value agc	   "1" or "0"
       byteSwap	       "1" or "0" base	  "base-input-frequency" copy	 "1"
       or "0" filter  "size-of-filter" gain    "gain.multipler"
       input   "name[,opt...]" jump    "bytes-to-skip-in-header"
       max     "max-input-count" output	 "name[,opt...]" stats	 "1" or	"0"
       vox     "1" or "0"

  The AConvertFiles routine is used to parse a command line and	execute	the
  commands found therein.

  The AConvert routine is called with an aconvert context and a	buffer to
  convert. The size of the buffer is in	units (which is	the smallest common
  multiple of bits/sample and 8). The returned output buffer is	only good
  until	the next call to AConvert. AConvert returns the	actual number of
  units	in the output buffer if	the conversion was successful.

  The AConvertStats routine prints out statistics (on stderr) about the	com-
  pleted conversion (provided that the stats flag was previously set).

  The AConvertClose routine closes the current aconvert	context	and deallo-
  cates	all buffers.


DIAGNOSTICS

  All routines return NULL or -1 on error (depending on	whether	they return a
  pointer or an	integer	value).	In addition AConvert returns 0 when EOF	or
  max-input is reached.


EXAMPLES

  Convert 8 bit, 8khz input to 16 bit, 16khz output:

       #include	<stdio.h>
       #include	<aconvert.h>

       static void Leave() {
	 fprintf(stderr,"0***ERROR: %s0,AConvertError());
	 exit(1);
       }

       main(int	argc,char** argv) {
	 int	       iUnits;
	 u_char	       ucaBuf[1024];
	 short*	       spBuf;
	 AConvertCtxt* tpACC = AConvertAllocInit(
				  MU255,8000,1,LIN16,16000,1);

	 if (!tpACC) Leave();

	 while ((iUnits	= fread(ucaBuf,sizeof(u_char),1024,stdin)) > 0)	{
	   if (AConvert(tpACC,iUnits,ucaBuf,&spBuf) != iUnits *	2) Leave();
	   fwrite(spBuf,sizeof(short),iUnits * 2,stdout);
	 }
	 AConvertClose(tpACC);
	 exit(0);
       }

  Perform file to file conversion:

       main(int	argc,char** argv) {
	 if (AConvertFiles(argc,argv)) Leave();
	 exit(0);
       }


SEE ALSO

  aconvert(1) AF(1)

BUGS
  melcep and cepstrum have not been implemented	yet.

  If you encounter a reproducible bug, please submit a problem report to
  (af-bugs@crl.dec.com).


COPYRIGHT
  Copyright 1993, Digital Equipment Corporation.
  See AF(1) for	a full statement of rights and permissions.

AUTHORS
  Dave Wecker, Cambridge Research Lab, Digital Equipment Corporation.