Package com.tino1b2be.dtmf

Class DtmfConfig

java.lang.Object
com.tino1b2be.dtmf.DtmfConfig
public final class DtmfConfig extends Object
Immutable configuration for DTMF detection and generation.

DtmfConfig has two tiers. The common tier, expressed via the four static factories (defaults(), forTelephony(), forVoip(), forNoisyAudio()), covers the scenarios that most callers reach for: 8 kHz mono telephony, Q.24 Standard_Twist tolerances, conservative minimum-tone and minimum-gap durations, and a pre-picked number of confirmation frames. The advanced tier, via advanced(), adds explicit control over the window function, twist thresholds, confirmation-frame count, and the broader sample-rate domain [4000, 192000] Hz (Requirement 3.4 vs 3.2 vs 3.3).

The ten knobs exactly mirror Requirements 8.1 and 8.2. Six common knobs are: sample rate, analysis block size, minimum tone duration, minimum gap duration, detection threshold, channel mode. Four advanced knobs are: window function, forward twist in dB, reverse twist in dB, and confirmation frames.

Validation happens at construction time (Requirement 17): every numeric field is checked against its documented domain, every reference field is null-checked with Objects.requireNonNull(Object, String), and the standard factories enforce the narrow sample-rate set {8000, 16000, 44100, 48000} (Requirement 3.3). The Advanced.build() path enforces the wider domain. The analysisBlockSize is auto-derived via BlockSizer.blockSizeFor(sampleRate) when the caller does not set it explicitly.

Instances are immutable: every accessor returns the value that was baked in at construction time, and there is no setter on DtmfConfig itself. The nested Advanced builder is mutable, but exposes only fluent setters that return this and a terminal build() method.

Since:
2.0.0

  • Method Details

    • sampleRate

      public int sampleRate()
      Returns the sample rate in Hz..
      Returns:
      the sample rate in Hz

    • analysisBlockSize

      public int analysisBlockSize()
      Returns the analysis block size in samples..
      Returns:
      the analysis block size in samples

    • minimumToneDuration

      public Duration minimumToneDuration()
      Returns the minimum tone duration..
      Returns:
      the minimum tone duration

    • minimumGapDuration

      public Duration minimumGapDuration()
      Returns the minimum inter-tone gap duration..
      Returns:
      the minimum inter-tone gap duration

    • detectionThreshold

      public double detectionThreshold()
      Returns the detection-confidence threshold in [0.0, 1.0]..
      Returns:
      the detection-confidence threshold in [0.0, 1.0]

    • channelMode

      public ChannelMode channelMode()
      Returns the channel mode..
      Returns:
      the channel mode

    • windowFunction

      public WindowFunction windowFunction()
      Returns the window function applied to each analysis block..
      Returns:
      the window function applied to each analysis block

    • forwardTwistDb

      public double forwardTwistDb()
      Returns the forward-twist tolerance in dB..
      Returns:
      the forward-twist tolerance in dB

    • reverseTwistDb

      public double reverseTwistDb()
      Returns the reverse-twist tolerance in dB..
      Returns:
      the reverse-twist tolerance in dB

    • confirmationFrames

      public int confirmationFrames()
      Returns the number of consecutive analysis blocks required to confirm a tone..
      Returns:
      the number of consecutive analysis blocks required to confirm a tone

    • defaults

      public static DtmfConfig defaults()
      Returns a configuration suitable for 8 kHz mono telephony audio with Standard_Twist tolerances..

      Delegates to forTelephony().

      Returns:
      a configuration suitable for 8 kHz mono telephony audio with Standard_Twist tolerances

    • forTelephony

      public static DtmfConfig forTelephony()
      Returns a configuration tuned for ITU-T Q.24 telephony audio..

      Values:

      • sample rate: 8000 Hz
      • analysis block size: auto (160 samples at 8 kHz, 50 Hz bin)
      • minimum tone duration: 40 ms
      • minimum gap duration: 40 ms
      • detection threshold: 0.25
      • channel mode: MONO
      • window: RECTANGULAR
      • forward twist: +4 dB (Standard_Twist)
      • reverse twist: −8 dB (Standard_Twist)
      • confirmation frames: 2
      Returns:
      a configuration tuned for ITU-T Q.24 telephony audio

    • forVoip

      public static DtmfConfig forVoip()
      Returns a configuration tuned for VoIP audio..

      Identical to forTelephony() except for confirmationFrames = 3, chosen to absorb packet-loss concealment artifacts that briefly disrupt the active tone.

      Returns:
      a configuration tuned for VoIP audio

    • forNoisyAudio

      public static DtmfConfig forNoisyAudio()
      Returns a configuration tuned for noisy audio..

      Differs from forTelephony() as follows: minimum tone duration is 50 ms, detection threshold is 0.35, and confirmationFrames = 4. Other knobs match forTelephony.

      Returns:
      a configuration tuned for noisy audio

    • advanced

      public static DtmfConfig.Advanced advanced()
      Returns a new DtmfConfig.Advanced builder seeded with the values from forTelephony()..

      The returned builder accepts any integer sample rate in [4000, 192000] Hz (Requirement 3.4) and exposes every one of the ten knobs for override.

      Returns:
      a new DtmfConfig.Advanced builder seeded with the values from forTelephony()