Voicetronix Programming Guide
<<< Previous |  | Next >>>

# Automated Tone Training

## Introduction

To make programming the tone detectors easier, an automated tone training application, `tonetrain`, has been developed, and is included in the vpb-driver software.

Using this application, tone training is a three step process:

1. Record a sample of the tone.

2. Run `tonetrain` to analyse the sample and determine suitable tone detector parameters.

3. Test the tone detector parameters on your recorded tone

## Compiling

First ensure you have already compiled the driver (see `README` in the root directory of vpb-driver).

`$``cd tonetrain`

`$``./configure`

`$``make`

## Tutorial

### Setup

To sample tones you will need a Voicetronix card, for example an OpenLine4 or OpenSwitch12 card. This card should be installed and tested. You will also need to connect a port of the Voicetronix card to the telephone line that you wish to train tones for. Different telephone line and PBXs tend to generate different tones. A second phone line or mobile (cell) telephone is also useful.

Make sure you have compiled, installed and tested the Voicetronix driver. You will also need to have compiled `recwav` and `tonedebug`, both located in the unittest directory.

### Sample files

There are some sample files in the tonetrain sub-directory. They are:

400-c-tone.wav - a continous tone of 400Hz
600-c-tone.wav - a continous tone of 600Hz
hs-dialtone.wav - dial tone from our PBX
hs-ringback.wav - ring back tone from our local exchange

Using these files you can run `tonetrainer` and then plug the results back into `tonedebug` (this requires a Voicetronix board)

### Dial Tone Training Example

To record a sample, perform this command from the `unittest` directory:

`$` `./recwav dialtone.wav 1 10`

This will record 10 seconds of signal on port 1 or the Voicetronix card. Before recording, `recwav` takes the line off hook, which will cause dial tone to be generated by your exchange of PBX. If your telephone line is connected to a different port, change the second argument.

It is a very good idea to check that the sample file is of good quality, and contains only the tone to be trained. You can play back the tone using `playwav`, or using a suitable command line or GUI utility.

If the sample file is of poor quality, then the automated tone training process will fail. It must contain just the tone sample to be trained, for example no human speech or other tones.

Now to determine the tone parameters, perform this command:

`$` `tonetrain/tonetrain -e -w dialtone.wav`

The `-e` option specifies the environment variable output format, the `-w WaveFile` specifies a wave file input format.

You should get a result like this:

    Environment variable format result:
    export VPB_TONE=5,C,421,100,2000

The arguments to the Environment variables are:

`export VPB_TONE=<Tone ID>,<Tone Type>,<Tone Frequency1>,<{Type dependant}...>`

Now perform this command to set the environment variable, note that we have changed the Tone ID from 5 to DIAL:

`$` `export VPB_TONE=DIAL,C,421,100,2000`

This environment variable is read by the vpb driver when it starts. The driver uses this information to configure the tone detector to recognise the tone you have just trained. For more information on the tone detector parameters (and how to set them) please see the previous section.

There are several other output formats for `tonetrain`, see the command line help for more information.

After training, you can then test the tone detector using `tonedebug`. First, disconnect your telephone line from the Voicetronix card. Then:

`$` `./tonedebug -e -w dialtone.wav`

    Using Environment...
    Note: -w option used for testing tone detector based
    on wave files echoed from tx->rx side of hybrid -
    make sure no telephone line connected to port 1!
    [00] Record fifo overflow
    [00] Tone Detect: Dial
    [00] Play End

As with `tonetrain`, `-e` specifies the environment variable output format, the `-w WaveFile` option specifies wave file input format for the sample used to test the tone detector.

### Ringback Tone Example

Ringback is the tone you hear in your telephone handset when the destination phone is ringing. It starts just after dialling and stops when the destination phone is answered.

To record a sample, you will to have a destination number that will not get answered and is not busy! Again we will use the `recwav` application:

`$` `./recwav ringback.wav 1 10 --dial ,,555`

This example assumes that the destination number you are calling is 555 (just like the movies). The commas generate a 1 second pause in the dialling, which is useful as some PBXes and exchanges like pauses before (and during dialling). You should hear the phone at the destination number (in this case 555) ringing during the record process.

If you don't hear the destination phone ringing, then there may have been a problem dialling. Investigate and correct this before proceeding.

As with the dial tone example, it is a very good idea to listen to the recorded sample to ensure it contains the correct ringback tone sample before proceeding with the training stage.

You can then process it through `tonetrain` and `tonedebug` as before:

`$` `tonetrain/tonetrain -e -w ringback.wav`

    Environment variable format result:
    export VPB_TONE=5,P,453,100,1690

`$` `export VPB_TONE=RINGBACK,P,453,100,1690`

`$` `./tonedebug -e -w ringback.wav`

    Using Environment...
    Note: -w option used for testing tone detector based
    on wave files echoed from tx->rx side of hybrid -
    make sure no telephone line connected to port 1!
    [00] Record fifo overflow
    [00] Tone Detect: Ringback
    [00] Tone Detect: Ringback
    [00] Tone Detect: Ringback
    [00] Play End

### Busy Tone Example

To record a sample, you will to have a destination number that will be busy and wont go to voice mail (you could use the number that you are calling from). Again we will use the `recwav` application:

`$` `./recwav busy.wav 1 10 --dial ,,555`

You can then run it through `tonetrain` and `tonedebug` as before:

`$` `tonetrain/tonetrain -e -w busytone.wav`

    Environment variable format result:
    export VPB_TONE=5,P2,421,100,1000

`$` `export VPB_TONE=BUSY,P2,421,100,1000`

`$` `./tonedebug -e -w busytone.wav`

    Using Environment...
    Note: -w option used for testing tone detector based
    on wave files echoed from tx->rx side of hybrid -
    make sure no telephone line connected to port 1!
    [00] Record fifo overflow
    [00] Tone Detect: Busy
    [00] Tone Detect: Busy
    [00] Tone Detect: Busy
    [00] Play End

<<< Previous | Home | Next >>>
Tone Detection |  | Timers