Package com.tino1b2be.dtmf.internal

Class TwistEvaluator

java.lang.Object
com.tino1b2be.dtmf.internal.TwistEvaluator
public final class TwistEvaluator extends Object
Twist computation and tolerance check for a candidate DTMF tone pair.

Per ITU-T Q.24, twist is the power ratio between the high-group tone and the low-group tone of a DTMF pair, expressed in decibels: 

   twistDb = 10 * log10(highEnergy / lowEnergy)

A positive twist means the high group is louder (forward twist); a negative twist means the low group is louder (reverse twist). Standard_Twist bounds are +4 dB forward and -8 dB reverse; anything outside those bounds is rejected by DtmfConfig.forTelephony() and DtmfConfig.defaults() (Requirement 9.2). The advanced builder exposes custom bounds (Requirement 9.3).

Zero-energy handling. If lowEnergy == 0.0 the ratio is undefined and the low group contributed no signal at all; this cannot be a valid DTMF candidate regardless of the twist configuration. twistDb(double, double) returns Double.POSITIVE_INFINITY in that case so withinTolerance(double, DtmfConfig) rejects under any finite forward-twist bound (Requirement 9.4).

Although the type is public so com.tino1b2be.dtmf.internal.AnalysisPipeline in the same package and the dtmf-core tests in com.tino1b2be.dtmf.internal can call it, the convention is that com.tino1b2be.dtmf.internal.* is not part of the published API.

Since:
2.0.0

  • Method Details

    • twistDb

      public static double twistDb(double lowEnergy, double highEnergy)
      Compute the twist in decibels for a candidate DTMF pair.
      Parameters:
      lowEnergy - magnitude-squared of the picked low-group peak; non-negative
      highEnergy - magnitude-squared of the picked high-group peak; non-negative
      Returns:
      10 * log10(highEnergy / lowEnergy) when lowEnergy > 0; Double.POSITIVE_INFINITY when lowEnergy == 0 so any finite tolerance rejects

    • withinTolerance

      public static boolean withinTolerance(double twistDb, DtmfConfig cfg)
      Returns whether the given twist in dB lies within the tolerance band configured on cfg..

      Returns true when reverseDb <= twistDb <= forwardDb where reverseDb and forwardDb come from DtmfConfig.reverseTwistDb() and DtmfConfig.forwardTwistDb() respectively. A Double.POSITIVE_INFINITY or Double.NaN twist is always rejected because neither comparison can evaluate to true.

      Parameters:
      twistDb - candidate twist in dB (may be infinite)
      cfg - configuration supplying the twist bounds; non-null
      Returns:
      whether the given twist in dB lies within the tolerance band configured on cfg