filter.c

Reference Implementation of G.711 standard and other voice codecs

/*                                                           3.Dec.2004 v3.3
  ===========================================================================

  FILTER.C
  ~~~~~~~~

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

  Test program to process a given fil by one of the possible filter
  characteristic available in the STL. Multiple filterings (as
  available in firdemo.c and pcmdemo.c) can be obtained by piping
  (cascading) several runs of this program. Asynchronous tandeming
  simulation is available for some types of filter; delay of the input
  file or skipping samples from the input file is also available with
  the async operation.

  Usage:
  ~~~~~~
  $ filter [-options] Flt_type InpFile OutFile 
           [BlockSize [1stBlock [NoOfBlocks]]]

  where:
  flt_type: 	is the filter type (see list below)
  InpFile       is the name of the file to be processed;
  OutFile       is the name with the processed data;
  BlockSize     is the block size, in number of samples
  1stBlock      is the number of the first block of the input file
                to be processed;
  NoOfBlocks    is the number of blocks to be processed, starting on
                block "1stBlock"
        
  Options:
  -mod .......... uses the modified IRS characteristic instead of the
                  "regular" one.
  -down ......... filtering is downsample (for HQ2, HQ3, FLAT, IFLAT, and PCM)
  -up ........... filtering is upsample (for HQ2, HQ3, FLAT, IFLAT, and PCM)
  -async ........ asynchronization operation (disables -down) \n"))  
  -delay d ...... number of samples to delay the input signal for 
                  asynchronous tandeming simulation. For d>0, null
                  samples are inserted in the begining of the file,
                  d<0 causes samples to be dropped. Default is d=0.
  -q ............ quiet processing (no progress flag)

  Valid filter specifications:
  Flt_type Description
   IRS8     (regular) IRS weighting with factor 1:1 at 8kHz
   IRS16    (regular or modified) IRS weighting with factor 1:1 at 16kHz
   IRS48    (modified) IRS weighting with factor 1:1 at 48kHz
   HIRS16   Half-tilt IRS weighting for data sampled at 16kHz, factor 1:1
   TIRS     IRS weighting with TIA coefficients, sf=8kHz, factor 1:1
   DSM      Delta-SM filtering characteristic, 1:1
   PSO      Psophometric wheighting filter, 1:1
   HQ2      FIR (High quality) low-pass with factor 1:2 (up) or 2:1 (down)
   HQ3      FIR (High quality) low-pass with factor 1:3 (up) or 3:1 (down)
   FLAT     Linear-phase pass-band with factor 1:2 (up) or 2:1 (down)
   FLAT1    Linear-phase pass-band with factor 1:1 (no rate change)
   PCM      Standard IIR PCM quality factor 1:2 (up) or 2:1 (down)
   PCM1     Standard PCM quality with factor 1:1 at 16 kHz
   GSM1     GSM Mobile station input response w/ factor 1:1 at 16 kHz
   P341     Send-part weighting of ITU-T Rec.P.341 (Wideband telephones)
   DC       Direct-form DC-removal IIR filter (factor 1:1)
   IFLAT    Flat IIR low-pass with factor 1:3 (up) or 3:1 (down) using a 
            cascade structure
   5KBP     50-5000 Hz Flat bandpass FIR filter for fs=16kHz, 1:1
   100_5KBP	100-5000 Hz Flat bandpass FIR filter for fs=16kHz, 1:1
   14KBP	50-14000 Hz Flat bandpass FIR filter for fs=32kHz, 1:1
   LP35		low-pass filter with cut-off frequency 3.5kHz for fs=48kHz, 1:1
   LP7		low-pass filter with cut-off frequency 7kHz for fs=48kHz, 1:1
   LP10		low-pass filter with cut-off frequency 10kHz for fs=48kHz, 1:1
   RXIRS8   Receive-side Modified IRS weighting with factor 1:1 at 8kHz
   RXIRS16  Receive-side Modified IRS weighting with factor 1:1 at 16kHz


  Testing:
  ~~~~~~~~
  HPUX 10.20 gcc 2.95.2 (master)
  Dec/Ultrix 4.3 cc
  MSDOS Borland tcc++ 1.0, gcc 2.6.3/DJGPP
  Win95 gcc/Cygnus egcs.2.91.57
  SunOs 4.1 cc
   
  Original author:
  ~~~~~~~~~~~~~~~~
  Simao Ferraz de Campos Neto
  CPqD - Telebras                       Tel:    [phone]
  Rod. Mogi Mirim - Campinas Km. 118,5  Fax:    [phone]
  13.088-061 - Campinas - SP - Brazil   E-mail: [e-mail]

  History:
  ~~~~~~~~
  30.Apr.1994 v1.0  Release of 1st version <[e-mail]>
  23.Sep.1994 v2.0  Updated to accomodate changes in the name of the name and
                    splitting of module in several files, for ease of expansion.
  12.Oct.1994 v2.1  Added US-TIA IRS coefficients @ 8kHz and half-tilt IRS 
                    @16kHz. <simao>
  01.Jul.1995 v2.2  Added ITU-T P.341 send mask characteristic, cascade-form 
                    IIR 3:1/1:3 filter, direct-form DC-removal filter, and
                    asynchronization operation <[e-mail]>
  16.May.1997 v2.3  Added 50-5000 Hz band pass filter for signals sampled at
                    16 kHz, necessary for the wideband qualification tests
                    and added extension of the HQ band-pass filter to have
                    a 1:1 rate operation. Also changed the way some filter
                    type options are printed (rate change, mod.IRS,
                    FIR/IIR/...).
  02.Jan.1999 v3.0  - Added option to delay or skip samples in output file  
                      when the -async option is used. This is to
                      improve the asynchronization between input and
                      output files, in particular for the wideband case
                      when the IFLAT filter type is used. <simao>
                    - Corrected a bug to flag an error when modified
                      IRS is selected for 8 kHz sampling rate (filter
                      not available!). <simao>
                    - Found a memory leakage problem which happens for
                      downsampling operation by a factor of 3 when the
                      block size is not a multiple of 3, and fixed
                      using ceil() in the 4 places where the output
                      buffer size is calculated <simao>
  02.Jul.1999 v3.1  - Added GSM mobile station 16 kHz input high-pass
                      FIR filter 16 1:1 characteristic, after Kyrill
                      Fisher (DT/Berkom) (used in the ETSI AMR tests).
                      <simao>
  12.Jul.2000 v3.2  - Updated display_usage() for missing option. 
                    - Added hook to prevent selection of an FIR filter
                      with downsampling *and* block size N=1. In this
                      case, there is a bug in fir_downsampling_kernel() 
		      [in fir-lib.c] that causes the output file to be
                      one sample long. Until the function is
                      corrected, this operation is disabled in this
                      program <simao>.
  10.Feb.2005 v3.3  - The Bug in fir_downsampling_kernel() [in fir_lib.c]
					  has been corrected. The hook, to prevent selection of
					  an FIR filter with downsampling and block size N=1,
					  was removed.
					- Added 50-14000Hz bandpass filter
					- Added LP filters (3.5kHz, 7kHz, 10kHz) for fs=48kHz
					- Added 100-5000 Hz bandpass filter
						<Cyril Guillaum