utils/frame.h

Go to the documentation of this file.
00001 /****************************************************************************
00002  *
00003  * Programs for processing sound files in raw- or WAV-format.
00004  * -- Useful functions for parsing command line options and
00005  *    issuing errors, warnings, and chit chat.
00006  *
00007  * Name:    frame.h
00008  * Version: see frame.c
00009  * Author:  Mark Roberts <mark@manumark.de>
00010  *
00011  ****************************************************************************/
00012 /****************************************************************************
00013  *  These are useful functions that all DSP programs might find handy
00014  ****************************************************************************/
00015 
00016 /* fileswitch for parseargs:
00017 
00018    The following are masks for several different ways of opening files.
00019    --------------------------------------------------------------------
00020    Bit 0: Open infile?
00021    Bit 1: Open infile as binary (as opposed to text)
00022    Bit 2: Open outfile?
00023    Bit 3: Open outfile as binary (as opposed to text)
00024    Bit 4: Do not complain about too many file arguments
00025    Bit 5: Open one file for input AND output, binary.
00026 */
00027 #define INTEXT (1+0)
00028 #define INBIN (1+2)
00029 #define OUTTEXT (4)
00030 #define OUTBIN (4+8)
00031 #define NOFILES (0)
00032 #define NOCOMPLAIN (16)
00033 #define IOBIN (32)
00034 
00035 #ifndef FALSE
00036  #define FALSE (0==1)
00037  #define TRUE (0==0)
00038 #endif
00039 
00040 extern int samplefrequency;
00041 extern unsigned short samplewidth;
00042 extern unsigned short channels;
00043 extern int wavout;         /* TRUE iff out file is .WAV file */
00044 extern int iswav;          /* TRUE iff in file was found to be a .WAV file */
00045 extern FILE *in, *out;
00046 extern char *infilename, *outfilename;
00047 extern int verboselevel;
00048 extern char *version;      /* String to be issued as version string. Should
00049                be set by application. */
00050 extern char *usage;        /* String to be issued as usage string. Should be
00051                set by application. */
00052 
00053 #define DEFAULTFREQ 44100
00054 #define BUFFSIZE 50000   /* How many samples to read in one go (preferred) */
00055 #define MINBUFFSIZE 5000 /* How many samples to read in one go (minimum)   */
00056 
00057 /*************************************************
00058  * Types of errors handled by argerrornum()      *
00059  *************************************************/
00060 typedef enum
00061 {
00062   ME_NOINT,
00063   ME_NODOUBLE,
00064   ME_NOTIME,
00065   ME_NOVOL,
00066   ME_NOSWITCH,
00067   ME_TOOMANYFILES,
00068   ME_HEADERONTEXTFILE,
00069   ME_NOINFILE,
00070   ME_NOOUTFILE,
00071   ME_NOIOFILE,
00072   ME_NOSTDIN,
00073   ME_NOSTDOUT,
00074   ME_NOSTDIO,
00075   ME_NOTENOUGHFILES,
00076   ME_THISCANTHAPPEN
00077 } Errornum;
00078 
00079 
00080 /* -----------------------------------------------------------------------
00081    Create memory and copy 'string', returning a pointer to the copy.
00082    NULL is returned if malloc fails.
00083    -----------------------------------------------------------------------*/
00084 extern char *malloccopy( char *string);
00085 
00086 /* -----------------------------------------------------------------------
00087    Start the stopwatch and make sure the user is informed at end of program.
00088    -----------------------------------------------------------------------*/
00089 extern void startstopwatch(void);
00090 
00091 /* -----------------------------------------------------------------------
00092    Writes the number of samples to result that are yet to be read from anyin.
00093    I.e. the number of remaining bytes is divided by the number of bytes per
00094    sample value, but not by the number of channels.
00095    Return values are TRUE on success, FALSE on failure.
00096    -----------------------------------------------------------------------*/
00097 extern int getremainingfilelength( FILE *anyin, long *result);
00098 
00099 /* -----------------------------------------------------------------------
00100    Read a .pk-header from 'anyin' and printf the entries.
00101    -----------------------------------------------------------------------*/
00102 void readpkheader( FILE *anyin);
00103 
00104 /* -----------------------------------------------------------------------
00105    Read a .WAV header from 'anyin'. 
00106    If it is recognised, the data is used.
00107    Otherwise, we assume it's PCM-data and ignore the header.
00108    The global variable 'iswav' is set on success, otherwise cleared.
00109    -----------------------------------------------------------------------*/
00110 extern void readwavheader( FILE *anyin);
00111 
00112 /* -----------------------------------------------------------------------
00113    Write a .WAV header to 'out'.
00114    The filepointer is placed at the end of 'out' before operation.
00115    This should be called before any data is
00116    written, and again, when ALL the data has been written.
00117    First time, this positions the file pointer correctly; second time, the
00118    missing data can be inserted that wasn't known the first time round.
00119    -----------------------------------------------------------------------*/
00120 extern void makewavheader( void);
00121 
00122 /* --------------------------------------------------------------------
00123    Tests the character 'coal' for being a command line option character,
00124    momentarrily '/' or '-'.
00125    -------------------------------------------------------------------- */
00126 extern int isoptionchar (char coal);
00127 
00128 /* -----------------------------------------------------------------------
00129    Reads through the arguments on the lookout for an option starting
00130    with 'string'. The rest of the option is read as a time and passed
00131    to *result, where the result is meant to mean 'number of samples' in
00132    that time.
00133    On failure, *result is unchanged.
00134    return value is TRUE on success, FALSE otherwise.
00135    -----------------------------------------------------------------------*/
00136 extern int parsetimearg( int argcount, char *args[], char *string,
00137           int *result);
00138 
00139 /* -----------------------------------------------------------------------
00140    The string argument is read as a time and passed to *result, where
00141    the result is meant to mean 'number of samples' in that time.  On
00142    failure, *result is unchanged.
00143    return value is TRUE on success, FALSE otherwise.
00144    -----------------------------------------------------------------------*/
00145 int parsetime(char *string, int *result);
00146 
00147 /* -----------------------------------------------------------------------
00148    The string argument is read as a frequency and passed
00149    to *result, where the result is meant to mean 'number of samples' in
00150    one cycle of that frequency.
00151    On failure, *result is unchanged.
00152    return value is TRUE on success, FALSE otherwise.
00153    -----------------------------------------------------------------------*/
00154 int parsefreq(char *string, double *result);
00155 
00156 /* --------------------------------------------------------------------
00157    Reads through the arguments on the lookout for a switch -'string'.
00158    return value is TRUE if one exists, FALSE otherwise.
00159    If characters remain after the switch, a fatal error is issued.
00160    -------------------------------------------------------------------- */
00161 extern int parseswitcharg( int argcount, char *args[], char *string);
00162 
00163 /* --------------------------------------------------------------------
00164    Reads through the arguments on the lookout for an option starting
00165    with 'string'. The rest of the option is read as an integer and
00166    passed to &result.
00167    On failure, &result is unchanged.
00168    return value is TRUE on success, FALSE otherwise.
00169    -------------------------------------------------------------------- */
00170 extern int parseintarg( int argcount, char *args[], char *string,
00171           int *result);
00172 
00173 /* --------------------------------------------------------------------
00174    Reads through the arguments on the lookout for a filename, i.e. anything
00175    that does not start with the optionchar. The filename is copied to
00176    newly allocated memory, a pointer to which is returned.
00177    The argument is marked as used. Therefore repeated use of this function
00178    will yield a complete list of filenames on the commandline.
00179    If malloc() fails, the function does not return.
00180    -------------------------------------------------------------------- */
00181 extern char *parsefilearg( int argcount, char *args[]);
00182 
00183 /* --------------------------------------------------------------------
00184    Reads through the arguments on the lookout for an option starting
00185    with 'string'. The rest of the option is read as a double and
00186    passed to *result.
00187    On failure, *result is unchanged.
00188    return value is TRUE on success, FALSE otherwise.
00189    -------------------------------------------------------------------- */
00190 extern int parsedoublearg( int argcount, char *args[], char *string,
00191             double *result);
00192 
00193 /* --------------------------------------------------------------------
00194    Reads through the arguments on the lookout for an option starting
00195    with 'string'. The rest of the option is read as a volume, i.e.
00196    absolute, percent or db. The result is passed to *result.
00197    On failure, *result is unchanged.
00198    -------------------------------------------------------------------- */
00199 extern int parsevolarg( int argcount, char *args[], char *string,
00200           double *result);
00201 
00202 /* --------------------------------------------------------------------
00203    Reads the specified string and interprets it as a volume. The string
00204    would be of the form 1.8 or 180% or 5db.
00205    On success, the return value is the relative volume, i.e. 1.8
00206    On failure, -1 is returned.
00207    -------------------------------------------------------------------- */
00208 extern int parsevolume(char *s, double *result);
00209 
00210 /* --------------------------------------------------------------------
00211    Reads through the arguments on the lookout for a switch -'string'.
00212    return value is TRUE if one exists, FALSE otherwise.
00213    If characters remain after the switch, a fatal error is issued.
00214    -------------------------------------------------------------------- */
00215 extern int parseswitch( char *found, char *wanted);
00216 
00217 /* --------------------------------------------------------------------
00218    Reports an error due to parsing the string 's' encountered on the
00219    command line.
00220    -------------------------------------------------------------------- */
00221 extern void argerror(char *s);
00222 
00223 /* --------------------------------------------------------------------
00224    Reports an error due to parsing the string 's' encountered on the
00225    command line. 'code' indicates the type of error.
00226    -------------------------------------------------------------------- */
00227 extern void argerrornum(char *s, Errornum code);
00228 
00229 /* --------------------------------------------------------------------
00230    Reports an error due to parsing the string 's' encountered on the
00231    command line. 'message' explains the type of error.
00232    -------------------------------------------------------------------- */
00233 extern void argerrortxt(char *s, char *message);
00234 
00235 /* --------------------------------------------------------------------
00236    Check for any remaining arguments and complain about their existence.
00237    If arguments are found, this function does not return.
00238    -------------------------------------------------------------------- */
00239 extern void checknoargs( int argcount, char *args[]);
00240 
00241 /* --------------------------------------------------------------------
00242    Parses the command line arguments as represented by the function
00243    arguments. Sets the global variables 'in', 'out', 'samplefrequency'
00244    and 'samplewidth' accordingly.
00245    According to 'fileswitch', in and out files are opened or not. See
00246    above for an explanation of 'fileswitch'.
00247    -------------------------------------------------------------------- */
00248 extern void parseargs( int argcount, char *args[], int fileswitch);
00249 
00250 /* --------------------------------------------------------------------
00251    Returns the index 'i' of the first argument that IS an option, and
00252    which begins with the label 's'. If there is none, -1.
00253    We also mark that option as done with, i.e. we cross it out.
00254    -------------------------------------------------------------------- */
00255 extern int findoption( int argcount, char *args[], char *s);
00256 
00257 /* --------------------------------------------------------------------
00258    Finishes off the .WAV header (if any) and exits correctly and formerly.
00259    -------------------------------------------------------------------- */
00260 extern int myexit (int value);
00261 
00262 /* --------------------------------------------------------------------
00263    Reads the stated input file bufferwise, calls the function 'work'
00264    with the proper values, and writes the result to the stated output file.
00265    Return value: TRUE on success, FALSE otherwise.
00266    -------------------------------------------------------------------- */
00267 extern int workloop( FILE *theinfile, FILE *theoutfile,
00268            int (*work)( short *buffer, int length) );
00269 
00270 /* --------------------------------------------------------------------
00271    Five functions for printing to stderr. Depending on the level of verbose,
00272    output may be supressed. fatalerror() is like error() but does not return.
00273    fatalperror() is like the standard function perror() but does not return.
00274    -------------------------------------------------------------------- */
00275 extern int chat( const char *format, ...);
00276 extern int inform( const char *format, ...);
00277 extern int error( const char *format, ...);
00278 extern void fatalerror( const char *format, ...);
00279 extern void fatalperror( const char *string);
00280 
00281 /* --------------------------------------------------------------------
00282    And one functions for printing to stdout.
00283    -------------------------------------------------------------------- */
00284 extern int say( const char *format, ...);
00285 
00286 /* --------------------------------------------------------------------
00287    Allocate memory for it and return a pointer to a string made up of
00288    the two argument strings.
00289    -------------------------------------------------------------------- */
00290 extern char *mallocconcat( char *one, char *two);
00291 
00292 /* --------------------------------------------------------------------
00293    Convert a sample value to decibel.
00294    -------------------------------------------------------------------- */
00295 extern double double2db( double value);
00296 
00297 /* --------------------------------------------------------------------
00298    Read 'size' samples from file 'in' and lose them.
00299    -------------------------------------------------------------------- */
00300 extern void readawaysamples( FILE *in, size_t size);

Generated on Thu Apr 16 06:27:35 2015 for Asterisk - The Open Source Telephony Project by  doxygen 1.5.6