utils/frame.h

   1 /****************************************************************************
   2  *
   3  * Programs for processing sound files in raw- or WAV-format.
   4  * -- Useful functions for parsing command line options and
   5  *    issuing errors, warnings, and chit chat.
   6  *
   7  * Name:    frame.h
   8  * Version: see frame.c
   9  * Author:  Mark Roberts <mark@manumark.de>
  10  *
  11  ****************************************************************************/
  12 /****************************************************************************
  13  *  These are useful functions that all DSP programs might find handy
  14  ****************************************************************************/
  15
  16 /* fileswitch for parseargs:
  17
  18    The following are masks for several different ways of opening files.
  19    --------------------------------------------------------------------
  20    Bit 0: Open infile?
  21    Bit 1: Open infile as binary (as opposed to text)
  22    Bit 2: Open outfile?
  23    Bit 3: Open outfile as binary (as opposed to text)
  24    Bit 4: Do not complain about too many file arguments
  25    Bit 5: Open one file for input AND output, binary.
  26 */
  27 #define INTEXT (1+0)
  28 #define INBIN (1+2)
  29 #define OUTTEXT (4)
  30 #define OUTBIN (4+8)
  31 #define NOFILES (0)
  32 #define NOCOMPLAIN (16)
  33 #define IOBIN (32)
  34
  35 #ifndef FALSE
  36  #define FALSE (0==1)
  37  #define TRUE (0==0)
  38 #endif
  39
  40 extern int samplefrequency;
  41 extern unsigned short samplewidth;
  42 extern unsigned short channels;
  43 extern int wavout;         /* TRUE iff out file is .WAV file */
  44 extern int iswav;          /* TRUE iff in file was found to be a .WAV file */
  45 extern FILE *in, *out;
  46 extern char *infilename, *outfilename;
  47 extern int verboselevel;
  48 extern char *version;      /* String to be issued as version string. Should
  49                               be set by application. */
  50 extern char *usage;        /* String to be issued as usage string. Should be
  51                               set by application. */
  52
  53 #define DEFAULTFREQ 44100
  54 #define BUFFSIZE 50000   /* How many samples to read in one go (preferred) */
  55 #define MINBUFFSIZE 5000 /* How many samples to read in one go (minimum)   */
  56
  57 /*************************************************
  58  * Types of errors handled by argerrornum()      *
  59  *************************************************/
  60 typedef enum
  61 {
  62   ME_NOINT,
  63   ME_NODOUBLE,
  64   ME_NOTIME,
  65   ME_NOVOL,
  66   ME_NOSWITCH,
  67   ME_TOOMANYFILES,
  68   ME_HEADERONTEXTFILE,
  69   ME_NOINFILE,
  70   ME_NOOUTFILE,
  71   ME_NOIOFILE,
  72   ME_NOSTDIN,
  73   ME_NOSTDOUT,
  74   ME_NOSTDIO,
  75   ME_NOTENOUGHFILES,
  76   ME_THISCANTHAPPEN
  77 } Errornum;
  78
  79
  80 /* -----------------------------------------------------------------------
  81    Create memory and copy 'string', returning a pointer to the copy.
  82    NULL is returned if malloc fails.
  83    -----------------------------------------------------------------------*/
  84 extern char *malloccopy( char *string);
  85
  86 /* -----------------------------------------------------------------------
  87    Start the stopwatch and make sure the user is informed at end of program.
  88    -----------------------------------------------------------------------*/
  89 extern void startstopwatch(void);
  90
  91 /* -----------------------------------------------------------------------
  92    Writes the number of samples to result that are yet to be read from anyin.
  93    I.e. the number of remaining bytes is divided by the number of bytes per
  94    sample value, but not by the number of channels.
  95    Return values are TRUE on success, FALSE on failure.
  96    -----------------------------------------------------------------------*/
  97 extern int getremainingfilelength( FILE *anyin, long *result);
  98
  99 /* -----------------------------------------------------------------------
 100    Read a .pk-header from 'anyin' and printf the entries.
 101    -----------------------------------------------------------------------*/
 102 void readpkheader( FILE *anyin);
 103
 104 /* -----------------------------------------------------------------------
 105    Read a .WAV header from 'anyin'.
 106    If it is recognised, the data is used.
 107    Otherwise, we assume it's PCM-data and ignore the header.
 108    The global variable 'iswav' is set on success, otherwise cleared.
 109    -----------------------------------------------------------------------*/
 110 extern void readwavheader( FILE *anyin);
 111
 112 /* -----------------------------------------------------------------------
 113    Write a .WAV header to 'out'.
 114    The filepointer is placed at the end of 'out' before operation.
 115    This should be called before any data is
 116    written, and again, when ALL the data has been written.
 117    First time, this positions the file pointer correctly; second time, the
 118    missing data can be inserted that wasn't known the first time round.
 119    -----------------------------------------------------------------------*/
 120 extern void makewavheader( void);
 121
 122 /* --------------------------------------------------------------------
 123    Tests the character 'coal' for being a command line option character,
 124    momentarrily '/' or '-'.
 125    -------------------------------------------------------------------- */
 126 extern int isoptionchar (char coal);
 127
 128 /* -----------------------------------------------------------------------
 129    Reads through the arguments on the lookout for an option starting
 130    with 'string'. The rest of the option is read as a time and passed
 131    to *result, where the result is meant to mean 'number of samples' in
 132    that time.
 133    On failure, *result is unchanged.
 134    return value is TRUE on success, FALSE otherwise.
 135    -----------------------------------------------------------------------*/
 136 extern int parsetimearg( int argcount, char *args[], char *string,
 137                          int *result);
 138
 139 /* -----------------------------------------------------------------------
 140    The string argument is read as a time and passed to *result, where
 141    the result is meant to mean 'number of samples' in that time.  On
 142    failure, *result is unchanged.
 143    return value is TRUE on success, FALSE otherwise.
 144    -----------------------------------------------------------------------*/
 145 int parsetime(char *string, int *result);
 146
 147 /* -----------------------------------------------------------------------
 148    The string argument is read as a frequency and passed
 149    to *result, where the result is meant to mean 'number of samples' in
 150    one cycle of that frequency.
 151    On failure, *result is unchanged.
 152    return value is TRUE on success, FALSE otherwise.
 153    -----------------------------------------------------------------------*/
 154 int parsefreq(char *string, double *result);
 155
 156 /* --------------------------------------------------------------------
 157    Reads through the arguments on the lookout for a switch -'string'.
 158    return value is TRUE if one exists, FALSE otherwise.
 159    If characters remain after the switch, a fatal error is issued.
 160    -------------------------------------------------------------------- */
 161 extern int parseswitcharg( int argcount, char *args[], char *string);
 162
 163 /* --------------------------------------------------------------------
 164    Reads through the arguments on the lookout for an option starting
 165    with 'string'. The rest of the option is read as an integer and
 166    passed to &result.
 167    On failure, &result is unchanged.
 168    return value is TRUE on success, FALSE otherwise.
 169    -------------------------------------------------------------------- */
 170 extern int parseintarg( int argcount, char *args[], char *string,
 171                          int *result);
 172
 173 /* --------------------------------------------------------------------
 174    Reads through the arguments on the lookout for a filename, i.e. anything
 175    that does not start with the optionchar. The filename is copied to
 176    newly allocated memory, a pointer to which is returned.
 177    The argument is marked as used. Therefore repeated use of this function
 178    will yield a complete list of filenames on the commandline.
 179    If malloc() fails, the function does not return.
 180    -------------------------------------------------------------------- */
 181 extern char *parsefilearg( int argcount, char *args[]);
 182
 183 /* --------------------------------------------------------------------
 184    Reads through the arguments on the lookout for an option starting
 185    with 'string'. The rest of the option is read as a double and
 186    passed to *result.
 187    On failure, *result is unchanged.
 188    return value is TRUE on success, FALSE otherwise.
 189    -------------------------------------------------------------------- */
 190 extern int parsedoublearg( int argcount, char *args[], char *string,
 191                            double *result);
 192
 193 /* --------------------------------------------------------------------
 194    Reads through the arguments on the lookout for an option starting
 195    with 'string'. The rest of the option is read as a volume, i.e.
 196    absolute, percent or db. The result is passed to *result.
 197    On failure, *result is unchanged.
 198    -------------------------------------------------------------------- */
 199 extern int parsevolarg( int argcount, char *args[], char *string,
 200                          double *result);
 201
 202 /* --------------------------------------------------------------------
 203    Reads the specified string and interprets it as a volume. The string
 204    would be of the form 1.8 or 180% or 5db.
 205    On success, the return value is the relative volume, i.e. 1.8
 206    On failure, -1 is returned.
 207    -------------------------------------------------------------------- */
 208 extern int parsevolume(char *s, double *result);
 209
 210 /* --------------------------------------------------------------------
 211    Reads through the arguments on the lookout for a switch -'string'.
 212    return value is TRUE if one exists, FALSE otherwise.
 213    If characters remain after the switch, a fatal error is issued.
 214    -------------------------------------------------------------------- */
 215 extern int parseswitch( char *found, char *wanted);
 216
 217 /* --------------------------------------------------------------------
 218    Reports an error due to parsing the string 's' encountered on the
 219    command line.
 220    -------------------------------------------------------------------- */
 221 extern void argerror(char *s);
 222
 223 /* --------------------------------------------------------------------
 224    Reports an error due to parsing the string 's' encountered on the
 225    command line. 'code' indicates the type of error.
 226    -------------------------------------------------------------------- */
 227 extern void argerrornum(char *s, Errornum code);
 228
 229 /* --------------------------------------------------------------------
 230    Reports an error due to parsing the string 's' encountered on the
 231    command line. 'message' explains the type of error.
 232    -------------------------------------------------------------------- */
 233 extern void argerrortxt(char *s, char *message);
 234
 235 /* --------------------------------------------------------------------
 236    Check for any remaining arguments and complain about their existence.
 237    If arguments are found, this function does not return.
 238    -------------------------------------------------------------------- */
 239 extern void checknoargs( int argcount, char *args[]);
 240
 241 /* --------------------------------------------------------------------
 242    Parses the command line arguments as represented by the function
 243    arguments. Sets the global variables 'in', 'out', 'samplefrequency'
 244    and 'samplewidth' accordingly.
 245    According to 'fileswitch', in and out files are opened or not. See
 246    above for an explanation of 'fileswitch'.
 247    -------------------------------------------------------------------- */
 248 extern void parseargs( int argcount, char *args[], int fileswitch);
 249
 250 /* --------------------------------------------------------------------
 251    Returns the index 'i' of the first argument that IS an option, and
 252    which begins with the label 's'. If there is none, -1.
 253    We also mark that option as done with, i.e. we cross it out.
 254    -------------------------------------------------------------------- */
 255 extern int findoption( int argcount, char *args[], char *s);
 256
 257 /* --------------------------------------------------------------------
 258    Finishes off the .WAV header (if any) and exits correctly and formerly.
 259    -------------------------------------------------------------------- */
 260 extern int myexit (int value);
 261
 262 /* --------------------------------------------------------------------
 263    Reads the stated input file bufferwise, calls the function 'work'
 264    with the proper values, and writes the result to the stated output file.
 265    Return value: TRUE on success, FALSE otherwise.
 266    -------------------------------------------------------------------- */
 267 extern int workloop( FILE *theinfile, FILE *theoutfile,
 268                      int (*work)( short *buffer, int length) );
 269
 270 /* --------------------------------------------------------------------
 271    Five functions for printing to stderr. Depending on the level of verbose,
 272    output may be supressed. fatalerror() is like error() but does not return.
 273    fatalperror() is like the standard function perror() but does not return.
 274    -------------------------------------------------------------------- */
 275 extern int chat( const char *format, ...);
 276 extern int inform( const char *format, ...);
 277 extern int error( const char *format, ...);
 278 extern void fatalerror( const char *format, ...);
 279 extern void fatalperror( const char *string);
 280
 281 /* --------------------------------------------------------------------
 282    And one functions for printing to stdout.
 283    -------------------------------------------------------------------- */
 284 extern int say( const char *format, ...);
 285
 286 /* --------------------------------------------------------------------
 287    Allocate memory for it and return a pointer to a string made up of
 288    the two argument strings.
 289    -------------------------------------------------------------------- */
 290 extern char *mallocconcat( char *one, char *two);
 291
 292 /* --------------------------------------------------------------------
 293    Convert a sample value to decibel.
 294    -------------------------------------------------------------------- */
 295 extern double double2db( double value);
 296
 297 /* --------------------------------------------------------------------
 298    Read 'size' samples from file 'in' and lose them.
 299    -------------------------------------------------------------------- */
 300 extern void readawaysamples( FILE *in, size_t size);