firdemo.c

Reference Implementation of G.711 standard and other voice codecs

/*                                                            03.Dec.04 v2.4
  ============================================================================

        FIRDEMO.C
        ~~~~~~~~~

        Description:
        ~~~~~~~~~~~~

        This test program carries out a series of 5 filterings
        by feeding ("piping") the output of a filtering stage to the input
        of the next one. This stages are, in order of implementation:

          1st. filter:  IRS Weighting Filter (none,8k,16k,16kMod,48kMod,16kHT)
          Intermediate: Delta-SM filtering (yes/no)
          2nd. filter:  Up-Sampling Filter   (factor 1, 2, 2b or 3)
          3rd. filter:  Up-Sampling Filter   (factor 1, 2, 2b, or 3)
          4th. filter:  Down-Sampling Filter (factor 1, 2, 2b, or 3)
          5th. filter:  Down-Sampling Filter (factor 1, 2, 2b, or 3)

          (NOTE: factor 1 means that no filtering is carried out)


        Usage:
        ~~~~~~
        $ firdemo !(---> HELP text is printed to screen)
        or
        $ firdemo [-options] ifile 
                      [ ofile irs delta_sm up1 up2 down1 down2 [lseg]]
                 (---> filtering is carried out, as specified)

        Where:
        ifile: .. input file with short data (binary files)
        ofile: .. output file with short data (binary files)

        irs: .... IRS filtering option (filtering #1):
                   0: no IRS filter
                   8: IRS-8kHz filter
                  16: IRS-16kHz (original|modified|half-tilt) filter
                  48: IRS-48kHz (modified) characteristic filter

        delta_sm: Delta-SM filtering option (complement to IRS):
                   0: skip Delta-SM filtering
                   1: cascade Delta-SM filtering
                   
        up1: .... upsampling option for filtering #2
                  1: no upsampling
                  2: upsampling by 2 
                 -2: upsampling by 2 using band-pass filter
                  3: upsampling by 3

        up2: .... upsampling option for filtering #3
                  1: no upsampling
                  2: upsampling by 2
                 -2: upsampling by 2 using band-pass filter
                  3: upsampling by 3

        down1: .. down-sampling option for filtering #4
                  1: no downsampling
                  2: downsampling by 2
                 -2: downsampling by 2 using band-pass filter
                  3: downsampling by 3

        down2: .. down-sampling option for filtering #5
                  1: no downsampling
                  2: downsampling by 2
                 -2: downsampling by 2 using band-pass filter
                  3: downsampling by 3

        lseg: ... number of samples per processing block
	          (default is 65)

	Options:
	~~~~~~~~
        -mod .... uses the modified IRS characteristic instead of the
                  "regular" one (if IRS was selected).
        -ht ..... uses the half-tilt IRS (if IRS was selected)
        -lseg ... changes the segment (block) length (default:LSEG0=256)
        -q ...... quiet processing (no progress flag)


        Compilation:
        ~~~~~~~~~~~~

        The test program is implemented for segment-wise filtering. To
        test the  dependency of the segment length, the user must enter
        a value for the  segment length (from 1 ... LSEGMAX). Examples
        follows:

        VAX/VMS:
                 $ CC firdemo
                 $ link firdemo
                 $ firdemo :== $firdemo_Disk:[firdemo_Dir]firdemo

        Turbo-C, Turbo-C++:
                 > tcc firdemo


        HighC (MetaWare, version R2.32):
                 > hc386 -stack 16384 firdemo.c

                 In our test some C-implementations have shown errors,
                 which can be eliminated by increasing the stack size
                 (at compile time).

        SunC (BSD Unix)
                 # cc -o firdemo firdemo.c
                 # firdemo


        Applications:
        ~~~~~~~~~~~~~

        1. Converting a file sampled at 16 kHz with a high-quality
        filtering and A/D system, to 8 KHz bandwidth, but making IRS
        weighting before downsampling: (eg, on the VAX)

                $ firdemo ifile ofile 16 1 1 1 2 133

                   The data from file "ifile" are processed in the
                 following way:
                 1) segments with 133 samples are read from file "ifile"
                 2) each segment is at first filtered with IRS send part
                    filter (coefficients for 16 kHz sampling frequency)
                 3) the output of the IRS-filter is passed through the
                    first up-sampling filter without filtering.
                 4) the output of the first up-sampling filter is passed
                    through the second up-sampling filter without filtering
                 5) the output of the second up-sampling filter is passed
                    through the first down-sampling filter without
                    filtering.
                 6) the output of the first down-sampling filter is fed
                    into the second down-sampling filter, which carries
                    out the down-sampling by a factor of 2.

        2. Dummy processing: upsamples by a factor of 6 times
        (8->48kHz), and downsamples back to 8 kHz: (eg, tcc)

                > firdemo ifile ofile 0 0 2 3 2 3 1024

                   The data from file "ifile" are processed in the
                 following way:
                 1) segments with 1024 samples are read from file "ifile"
                 2) the IRS send-part filter and Delta-SM are switched off.
                 3) the signal is then up-sampled by a factor of 2 in the
                    first up-sampling filter.
                 4) the output of the first up-sampling filter then up-
                    sampled by a factor of 3 in the second up-sampl. filter
                    -> total up-sampling factor = 6
                 5) the output of the second up-sampling filter is then
                    down-sampled by factor 2 in the first down-sampling
                    filter.
                 6) the output of the first down-sampling filter is fed
                    into the second down-sampling filter, which carries
                    out a down-sampling by a factor of 3.

        3. Upsampling a processed file from 8 kHz to 16 kHz, for
        listening purposes: (eg, using HighC)
                > run386 firdemo ifile ofile 0 0 2 0 0 0 256

        4. Upsampling a processed file from 8 kHz to 48 kHz, for
        recording in a DAT: (eg, using SunC)
                # firdemo ifile ofile 0 0 2 3 0 0 256

        5. Digitizing speech material recorded in a DAT, at 48 kHz,
        passing by the IRS at 16 kHz, and downsamplig to 8kHz:
                $ firdemo ifile tmpfile  0 0 0 0 0 3 256 ! tmpfile is at 16kHz
                $ firdemo tmpfile ofile 16 0 0 0 0 2 256 ! ofile is at 8kHz


        Original author:
        ~~~~~~~~~~~~~~~~

                Rudolf Hofmann
                Advanced Development Digital Signal Processing
                PHILIPS KOMMUNIKATIONS INDUSTRIE AG
                Kommunikationssysteme

        History:
        ~~~~~~~~
        16.Oct.91 v0.0 Release of beta version to UGST. <[e-mail]>
        26.Feb.92 v1.0 (ILS-files removed). <[e-mail]>
        18.May.92 v1.1 Use of sh2fl_16bit w/ file normalization.
                       <[e-mail]>
        20.Apr.94 v1.2 Added new filtering options: modified IRS at 16kHz and 
                       48kHz, Delta-SM filtering, and band-pass (G.712-like)
                       2:1 and 1:2 filtering. <[e-mail]>
        30.Sep.94 v2.0 Changes in the code/documentation to encompass changes
                       and spliting into several files of the old-name hq 
		       module, now FIRFLT. <[e-mail]>
        30.Oct.94 v2.1 Incorporated half-tilt IRS. <[e-mail]>
        06.Feb.96 v2.2 Corrected help message, included header string.h
		06.Jul.99 v2.3 Inserted conditional compilation for CYGWIN and 
                       MS Visual C compiler.
  ============================================================================
*/

/*
 * ......... INCLUDES .........
 */

/* Generic Includes */
#include <stdio.h>		  /* UNIX Standard I/O Definitions */
#include <stdlib.h>		  /* for atoi(), atol() */
#include <string.h>		  /* for str...() */
#include "ugstdemo.h"		  /* private defines for user interface */
#include "ugst-utl.h"		  /* conversion from float -> short */
#include "firflt.h"		  /* definitions for high quality filter */


/* Specific Includes */
#if defined(unix)
#include <malloc.h>		  /* For calloc() */
#elif defined(VMS) || defined (__STDC__)
#include <stdlib.h>
#elif defined(MSDOS) && ! defined(_MSC_VER)
#include <alloc.h>
#endif

/*
 * ......... LOCAL DEFINITIONS .........
 */

#define LSEG0    256		  /* default block length for segment-wise
				   * filtering */
#define LSEGMAX 2048		  /* max. number of samples to be proc. */


/*
  ============================================================================

        void display_usage (void);
        ~~~~~~~~~~~~~~~~~~

        Description:
        ~~~~~~~~~~~~

        Display usage of this demo program and exit;

        Return value:
        ~~~~~~~~~~~~~
        Returns the number of longs read.

        Author: <[e-mail]>
        ~~~~~~~

        History:
        ~~~~~~~~
        26.Feb.92 v1.0 Release of 1st version <[e-mail]>

 ============================================================================
*/
#define P(x) printf x
void            display_usage()
{
  P(("\n Six filters are running in cascade: \n"));
  P(("\t1st. Filter:  IRS Send Part Filter (none, 8 kHz, 16, or 48 kHz)\n"));
  P(("\t2nd. Filter:  Delta-SM (16kHz only)\n"));
  P(("\t3rd. Filter:  Up-Sampling Filter   (factor 1, 2 or 3)\n"));
  P(("\t4th. Filter:  Up-Sampling Filter   (factor 1, 2 or 3)\n"));
  P(("\t5th. Filter:  Down-Sampling Filter (factor 1, 2 or 3)\n"));
  P(("\t6th. Filter:  Down-Sampling Filter (factor 1, 2 or 3)\n\n"));

  P((" Usage: $ FIRDEMO [-options] ifile [ofile irs dsm up1 up2 down1 down2 [lseg]]\n"));

  P(("   ifile:  INPUT  FILE with short data (binary files)\n"));
  P(("   ofile:  OUTPUT FILE with short data (binary files)\n\n"));

  P(("%s%s", "   irs  :  0: short cut\t 8: IRS-8kHz filter  \t ",
	 "16: IRS-16kHz filter\n          48: IRS-48kHz\n"));
  P(("%s",   "   dsm  :  0: short cut\t 1: use 16kHz Delta-SM filter\n"));
  P(("%s%s", "   up1  :  0: short cut\t 2: upsampling   by 2\t ",
	 "3:  upsampling by 3 \n"));
  P(("%s%s", "   up2  :  0: short cut\t 2: upsampling   by 2\t ",
	 "3:  upsampling by 3 \n"));
  P(("%s%s", "   down1:  0: short cut\t 2: downsampling by 2\t ",
	 "3:  downsampling by 3 \n"));
  P(("%s%s", "   down2:  0: short cut\t 2: downsampling by 2\t ",
	 "3:  downsampling by 3 \n"));
  P(("   lseg:   number of samples per processing block (default is %d)\n",
	 LSEG0));
  P(("   NOTE: if up?/down? above is -2, the filter used is the bandpass \n"));
  P(("         FIR filter (instead of the \"default\" lowpass FIR)\n"));

  P((" Options:\n"));
  P(("  -mod ....... uses the modified IRS characteristic instead of the\n"));
  P(("               \"regular\" one. For 16 and 48kHz.\n"));
  P(("  -ht ........ uses the half-tilt for 16 kHz IRS, if IRS filtering is selected\n"));
  P(("  -q ......... quiet processing (no progress flag)\n"));
  P(("  -lseg ...... changes the segment (block) length (default:%d)\n",LSEG0));

  /* Quit program */
  exit(-128);
}
#undef P
/* ...................... End of display_usage() ........................... */



/* ......................... Begin of main() .............................. */
/*