NAME
    Audio::Analyzer::ToneDetect - Detect freq of tones in an audio file or
    stream

SYNOPSIS
      use Audio::Analyzer::ToneDetect;
      my $tone_detect = Audio::Analyzer::ToneDetect->new( source => \*STDIN );
      my $tone = $tone_detect->get_next_tone();
      say "I heard $tone!";

DESCRIPTION
    Consider this alpha software. It is still under fairly active
    development and the interface may change in incompatible ways.

    Audio::Analyzer::ToneDetect is a module for detecting single frequency
    tones in an audio stream or file. It supports mono PCM data and defaults
    to STDIN. For supporting other formats, eg MP3, you can pipe things
    through sox.

USAGE
  new (%opts)
    Takes the following named parameters:

    source \*FH or $path
        The audio source. Only Mono PCM is supported. You can pass the path
        to a WAV file or a file handle for an open file or stream. Defaults
        to STDIN.

    sample_rate 16000
        Source sample rate, results will be orders of magnitude off if set
        incorrectly. Defaults to 16000.

    chunk_size 1024
        Number of samples to analyze at once. Corresponds to dft_size in
        Audio::Analyzer. Must be a power of 2. Defaults to 1024.

    chunk_max 70
        Maximum number of chunks to process before returning. Returns false
        if it reaches this number of chunks without detecting a tone. With
        default chunk_size and sample_rate, the default of 70 equates to
        about 4.5 seconds of audio.

    min_tone_length 0.5
        Minimum durration of a tone, in seconds, before we consider it
        detected. Due to sample rate, chunk size, and integer math, with
        defaults this ends up being 0.448 seconds. The formula for actual
        seconds is int( min_length * sample_rate / chunk_size ) * chunk_size
        / sample_rate. Default to 0.5

    valid_tones undef, 'builtin', or ARRAYREF
        A list of valid (expected) tones. If supplied, the closest expected
        tone for a given detected tone is returned. Call get_next_tone() in
        list context or supply the following call back if you want both
        values. A value of 'builtin' uses a builtin list of valid classic
        Motorola Minitor tones. Defaults to unset.

    valid_error_cb
        A callback that if provided and valid_tones is set will be called
        just before get_next_tone or find_closest_valid returns. Arguments
        are the closest valid tone, the actual detected tone, the diference
        between the two in Hertz.

        Example:

          valid_error_cb => sub { printf "VF %s DF %s EF %.2f\n", @_; return }

        Return value is expected to be one of three possibilities.

        undef
            Has no effect on program flow, if you don't want your call back
            changing stuff make sure you have an explicit 'return' as the
            last line.

        0   A return value of 0 discards the tone and continues the
            get_next_tone loop.

        N   Any other value replaces the valid detected tone with the return
            value from the call back.

    rejected_freqs undef or ARRAYREF
        If specified, a reference to an array of frequencies that will be
        ignored. e.g roger beeps, repeater beeps, etc. Note, if you use
        valid tone detection, then this is the raw detected tone, not the
        closest match. Defaults to empty list.

  valid_tones
    Returns the arraref of valid tones currently being used. Optionally
    takes a reference to an array of new tones to use that will be copied to
    replace the current valid list.

  get_next_tone
    Returns the next detected tone in the stream. Will return false if we go
    through chunk_max without detecting a tone but the buffer will be
    preserved between calls if the a tone begins just before hitting
    chunk_max. If valid_tones was supplied, returns the result of passing
    the tone to find_closest_valid(), following it's list vs scalar
    semantics.

  get_next_two_tones
    Calls get next tone twice. Will return false if either tone returns
    false.

  find_closest_valid
    In scalar context, returns the closest valid tone in valid_tones. In
    list context returns the closest valid tone and the delta from detected
    tone.

AUTHOR
    Mike Greb <michael@thegrebs.com>

COPYRIGHT
    Copyright 2013 - Mike Greb

LICENSE
    This library is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself.

SEE ALSO
    Audio::Analyzer

    Math::FFT

POD ERRORS
    Hey! The above document had some coding errors, which are explained
    below:

    Around line 271:
        Expected text after =item, not a number