%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

    mb_ftracker (Mustafa-Bruce Formant Tracker)

        A MATLAB program to track formant frequencies from speech signals.

By:
    Kamran Mustafa (mkamran@hotmail.com)
        and
    Ian C. Bruce (ibruce@ieee.org)

    (c) 2004-2006

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%


1. ABOUT

This package contains a MATLAB program that tracks the first four formant
frequencies of a speech signal. The algorithm is based upon a new formant
tracking technique developed by the authors (see Technical Notes).

The program estimates the first four formant frequencies of the speech signal
and plots the a narrowband spectrogram and the estimated formant frequencies.
The program also returns the formant frequency values (in Hz) as well as the
voicing information ('High' = Voiced, 'Low' = Unvoiced).

Note that the algorithm resamples all speech signals to a sampling frequency of
8 kHz.


2. INSTRUCTIONS

To run the FORMANT TRACKER:

- Change the current directory (in MATLAB) to wherever you installed the
  FORMANT TRACKER.

- Load the speech file into MATLAB (whose formant frequencies you want to
  estimate).
  Example: If you want to load a .WAV file called "sample.wav"
               [X, Fs] = wavread('sample.wav');
           If you want to load an .AU file called "sample.au"
               [X, Fs] = auread('sample.au');

- Call the FORMANT TRACKER and pass the speech signal and the sampling
  frequency to it:
      [F1, F2, F3, F4, Voice] = mb_ftracker(X,Fs);

- A progress bar will appear indicating the how much of the speech signal has
  been processed.
  After the program has completed processing the complete speech signal the
  progress bar will disappear.

- Two figures with color narrowband spectrogram will appear with the
  estimated formant frequencies and other algorithm variables plotted on them.

- The estimated formant frequencies (in Hz) will also be returned to the 'F1',
  'F2', 'F3' and 'F4' vectors.
  The 'Voice' vector will contain the voicing decisions
  ('1' = Voiced, '0' = Unvoiced).


3. FILES

The FORMANT TRACKER package contains the following files:

1 - mb_ftracker.m
2 - formant_tracker_backend.m
3 - firhilbert.m
4 - formantfilters.m
5 - gender_detector.m
6 - zp2tf_complex.m
7 - db.m
8 - rms.m
9 - readme.txt (this file)
10 - sample.au
11 - sample.wav


4. TECHNICAL REFERENCES

Primary reference:

- K. Mustafa and I. C. Bruce, "Robust formant tracking for continuous speech
  with speaker variability," IEEE Transactions on Speech and Audio Processing,
  Mar. 2006.

Additional reference:

- K. Mustafa, "Robust formant tracking for continuous speech with speaker
  variability," M.A.Sc. dissertation, Dept. Elect. and Comp. Eng. McMaster Univ.,
  Hamilton, ON, Canada, 2003.

5. CONDITIONS OF USE

Please cite the Mustafa and Bruce (2006) paper if you publish or present any
research results obtained with this code or any modified versions of this code.

No permission is required to distribute this code or modified versions, but
please retain the journal citation details and author contact details and make
comments in the code to indicate where your modifications deviate from the
original code.