TwoToneDetect

TwoToneDetect – A free application for sending fire pages via text message or email

A Windows program that detects two-tone pages, records audio, and sends the recording to email or cell phones
TwoToneDetectPython

TwoToneDetect is free for personal and noncommercial use by public safety agencies and organizations.  If you’d like to use the program for commercial purposes, please contact me.

button-donate What is it?

TwoToneDetect is a Windows (or Linux) program that interfaces with a radio receiver or scanner.  It uses the computer’s sound card to listen to the received audio and detect two-tone sequential paging sequences.  This type of paging is commonly used for fire department alerting.  Upon detecting known two-tone pages, the program will record dispatch audio and email that audio to a specified email address. Multiple tone sets and email addresses are supported.

TwoToneDetect

Download the latest version (v65d) here

Download previous releases and see release notes here

For information on a Linux version that can run on the $35 Raspberry Pi single board computer, see this page.

Program Features

  • Decodes virtually unlimited numbers of user-specified two-tone and long-tone pages
  • Handles “stacked pages”
  • Upon detecting a valid tone set, records user-specified length of audio and emails it to a specified address as a  .mp3 or .amr file attachment (requires user download of ffmpeg.exe)
  • Near real-time playback of recorded audio, providing “pager-like” functionality with scanner and PC
  • Can be used to trigger external programs or scripts upon tone detection
  • Audio frequency counter to assist in finding tone frequencies with PC sound card

Disclaimer

This program should never be used as a primary alerting method for mission-critical communications.  It is meant as a secondary notification method only.  Delays in email or text messaging systems can be minutes or hours long.  Do not use this program to replace pagers, only to supplement them!

Download & Installation

After downloading the .zip file (see link at top of page), simply unzip into the folder of your choice on your computer.  There is no installer.   Simply unzip the file into a folder on the computer that will be running the program.  Inside the folder there are two executable files (.exe files).  They are “TwoToneDetect##.exe” and “TwoToneDetect##_debug.exe”.  The only difference between the two programs is that the _debug version of the program will open up a “debug” screen in addition to the main program screen.  This can be helpful to see what’s going on “behind the scenes” of the program if you encounter any problems.

On Linux, run the compiled Python file included in the ZIP package instead of the EXE:

python TwoToneDetect##.pyc

Steps to get up and running:

  1.  Download ffmpeg.exe from the internet and put it in the directory with TwoToneDetect
    Download this version.  If that version doesn’t work you can try the latest Windows 32 bit static build from here. NOTE:  Be sure to unzip the downloaded file before putting it into the TwoToneDetect directory!
  2. Run the TonesEditor program to set up your tone sets and distribution lists. See the “Editing Tone Information” section below for more information.  You can also manually edit the tones.cfg file using a text editor if you prefer.
  3. Run the program and click on the “Edit Config Info” menu. Set up the config items according to your needs.  See “Starting and Configuring the Program” section below
  4. Select the audio input and output devices you want to use from the main screen
  5. Exit the program
  6. Restart TwoToneDetect

Support & Troubleshooting

If you have problems with the program you can check this forum thread for answers or support.

Editing Tone Information

In order to tell the program what tone sets we want it to look for and act upon, we’ll use the TonesEditor program that is included in the download package:

TonesEditor

Using this GUI editor you can add new A-B tones or Long tones, and edit existing tones.  Be sure to click the “Save to tones.cfg” button before selecting a new tone to edit or changes will not be saved.  The sections below explain what the different fields mean.  If a parameter is optional, it can be left blank.

Mandatory Parameters for Two-Tone (A-B format) pages:

  • Atone – Frequency (in Hz) of the first (A) tone in the two-tone sequence
  • Btone – Frequency (in Hz) of the second (B) tone in the two-tone sequence
  • Atonelength – Duration of A tone (in seconds) that must be detected before the program will alert.
  • Btonelength – Duration of B tone (in seconds) that must be detected before the program will alert

Note: Setting Atonelength and Btonelength both to .6 should be a good starting point for most common two-tone paging formats.  Adjust as necessary.

  • Description – Description of the tone set.  Avoid using special characters such as slashes, quotation marks, or punctuation
  • mp3_Emails – This is a list of email addresses that the program will send mp3 attachments to whenever a valid page is received for this tone set.  To send to multiple email addresses, simply separate them with commas.

Mandatory Parameters for Long Tone pages:

  • Longtone – Frequency (in Hz) of the tone
  • Longtonelength – Length of the time the program must see the long tone before alerting.  Set to a value shorter than or equal to the actual tone duration.
  • Description – Description of the tone.  Avoid using special characters such as slashes, quotation marks, or punctuation
  • mp3_Emails – This is a list of email addresses that the program will send mp3 attachments to whenever a valid page is received for this tone set.

Additional Optional Parameters for either page type:

  • amr_Emails – This is a list of email addresses that the program will send AMR format audio file attachments to whenever a valid page is received for this tone set.  AMR format audio files can be played by most cellular phones when received as a text or multimedia message (MMS).
  • text_Emails - This is a list of email addresses that the program will send a text-only email to whenever a valid page is received for this tone set.  The email will not contain any information, it will just let the recipient know that a page has been received.  This email will be sent immediately upon tone detection, prior to audio recording
  • record_delay – Number of seconds that the program will wait to begin recording after a valid tone set is found
  • ignore_after – Number of seconds that the program will ignore a tone set after it has been received.  This is useful if a dispatch center normally sends multiple pages for the same call.  It can be used to prevent multiple email or text messages from being sent for the same call.
  • alert_command – This parameter can be used to point to a windows Batch file (.bat) or other executable file.  The file that is specified here will be executed whenever the specified tone set has been detected but before the audio has been recorded.  As an example, a batch file could be created that plays a pre-recorded audio file when the page is received.
  • post_email_command – This parameter can be used to point to a windows Batch file (.bat) or other executable file.  The file that is specified here will be executed whenever the specified tone set has been detected and after the audio has been recorded.  As an example, a batch file could be created that uploads the newly created audio file to an FTP server.
  • exclude_from, exclude_to, and exclude_emails parameters – These three parameters are used together to prevent emails from being sent to certain addresses when a page is received during a certain time of the day.  This can be used to prevent emails from being sent during daily test pages, or to only send pages for certain duty shifts.  When these three parameters are used, the tone sets will still be detected, but if the time of day of the page falls between exclude_from and exclude_to, the email will not be sent to the addresses in the exlude_emails parameter.  Multiple email addresses can be specified by separating them with commas.  This field will prevent emails from being sent to addresses in both the mp3_emails and amr_emails parameters.
  • playback_during_record - If set to 1, the program will play the page audio through the computer speakers (or other audio device as specified on the main program screen) while it is being recorded.  If set to 0, it will not play the audio while recording.

A note on sending pages to cell phones:

To send the page audio to a cellular phone, you must send the email to the carrier’s Multimedia Messaging Service (MMS) email address, not the normal SMS (text messaging) email address.  For some carriers these two email addresses are the same, for others, they are different.  For example, to send a normal text message to a Verizon phone via email you would address it to ##########@vtext.com, but to send a MMS message (containing a picture or audio file), you would need to address it to ##########@vzwpix.com.  A list of SMS and MMS gateways for different wireless carriers can be found here.

Also, most phones will play AMR format audio files, while only some will play MP3 format audio files, so pick whichever works best for your phone/carrier.

NEW (7/14/13):  I am now able to offer remote hosting of tones.cfg files with a web editing interface.  This system allows individual agencies to use a web interface to manage their own user distribution lists while an administrative user can edit all other information.  See this page for more details.

Note:  If you are upgrading to v59 or later from v58c or prior, you may need to change your Btonelength and Atonelength (new), as the tone detection algorithm has changed.  See this forum post for more information.  If in doubt, settings of Atonelength = .6 and Btonelength = .6 are a good place to start.

Here’s a graphic that shows how some of these parameters all fit together (click to enlarge):

RelTimeExplained.v3

Starting and Configuring the Program

  1. Start TwoToneDetect
  2. Select the Audio Input and Output devices from the drop down menus.  It’s best to use a line-in for the scanner input, but a microphone in can also work if set up properly in the Windows sound mixer.  Use Windows sound mixer to adjust the input audio level, if needed.  Note: On some newer Windows machines, an audio jack must be plugged in to the audio port before Windows will recognize the audio device.  Not having anything plugged in to your sound card may prevent TwoToneDetect from starting.
  3. Adjust the audio squelch level so that the audio level is under the threshold when no scanner audio is present, but above the threshold when scanner audio is present.  You may find that tuning the scanner to a local weather station can help quickly find an appropriate squelch level.  This can also help you adjust the sound levels in the Windows sound mixer.
  4. Check the “Playback during record” box if you want the program to play the page audio through your computer speakers as it records it.  If you want the system to be completely silent, uncheck the box.
  5. Next, click the “Edit Config Info” menu item at the top of the screen.  The following menu should appear:
EditConfigMenu

Configure the menu items as appropriate.  Here is a brief description of each of the fields:

  • Email UserID:  UserID of the email account that you will be using to send emails FROM
  • Email Password:  Password of the email account that you will be using to send emails FROM
  • Email Server:  Address of the email server that you will be using to send emails FROM
  • Email Port:  Port of the email server that you will be using to send emails FROM
  • Record Seconds:  Minimum number of seconds of audio that will be recorded after a valid page is received
  • Record Release Time: Number of seconds of silence necessary before recording will stop (dynamic record time).  Max is 60 seconds, default is 0 (which makes recording 100% based Record Seconds parameter)
  • Tone Tolerance:  Tolerance (in percentage) of the tone detection algorithm.  As an example, if a tone of 1000 Hz is specified and the tolerance is 2%, the program will detect tones from 980 Hz to 1020 Hz.  If this is set too narrow some tones may be missed.  If it is set too wide, false detections may occur.  A value of 1-2% is usually sufficient.
  • Tone Offset:  This is a “fudge factor” offset (in percentage) that is applied to all incoming audio signals.  This can be used to correct for sound card inaccuracy due to clock offset or drift.
  • Email Priority:  Sets the email priority for the message header [X-Priority].  1 = highest, 3 = normal, 5 = lowest
  • MP3 Encoding Bitrate:  Select the desired mp3 encoding bitrate from the drop down menu.  Lower bitrates result in smaller files, higher bitrates result in larger, higher quality files.
  • BCC Email Recipients:  When checked, emails will be sent as a blind carbon copy (BCC) so that email recipients don’t see the email addresses of other recipients.

A note on using Gmail as your email provider

If you use Gmail as your email provider to send messages from TwoToneDetect and you use two-step authentication, you’ll want to set up an application-specific password that TwoToneDetect can use with your Gmail account to prevent two-step authentication issues.  For details on how to set this up, see this page.

You might also need to allow “less secure” apps to access your Gmail account.

Some users have reported that Gmail sometimes blocks their messages as spam, and they have to contact Google to get the account unblocked.  Users have also found that it helps to have all of the email and SMS addresses that you’re sending to in your Google “Contacts” to help reduce the chance that it becomes marked as spam by Google.  As an alternative, Yahoo mail has been tested to work with TTD, and the email service of your internet service provider may be another option.  If you can’t find a free email service that works reliably for you, feel free to contact me about setting up an email server through twotonedetect.net for a small fee.

Program Operation

TwoToneDetect continuously checks the sound card input for audio.  If the audio level exceeds a set threshold, the program measures the most dominant tone in the audio signal (even if it is not a true “tone”).  If it sees a valid two tone or long tone page, it will start an alert thread that will record audio after the page, convert the recorded audio into AMR and MP3 format, and then send the audio as an email attachment.  The program can also trigger external programs or scripts to run upon tone set detection.

Additional Resources

Here is a pdf document that shows how to use Audacity to find tone frequencies from recorded audio files.

User Map

Using TwoToneDetect? Show us where!  Add your location to the map below by going here and signing in with your Google account.  Edit the map to add your location.  Or, just send me an email and I’ll add your location to the map!