Package com.tino1b2be.dtmf.internal

Class SampleConverter

java.lang.Object
com.tino1b2be.dtmf.internal.SampleConverter
public final class SampleConverter extends Object
Sample-format normalization for the DTMF detection pipeline.

Every public entry point of DtmfDecoder and DtmfDetector that accepts non-double PCM — short[] PCM16, float[] normalized float, int[] PCM32, or int[] packed PCM24 — funnels through this class before the shared analysis pipeline sees a sample. Concentrating the conversion formulas in one place is how we guarantee Requirements 4.5, 4.6, and 4.7 hold identically on both the batch path (DtmfDecoder) and the push path (DtmfDetector).

Two flavours are provided for every input type:

Conversion formulas (Requirements 4.5, 4.6, 4.7):

  • short → double: divide by 32768.0 (that is 2^15). Chosen so Short.MIN_VALUE maps exactly to -1.0 and Short.MAX_VALUE maps to 32767/32768 ≈ 0.99996948. The alternative divisor 32767.0 would shift the zero-crossing and break the symmetry of the negative and positive extremes.
  • float → double: direct widening cast, no scaling. Callers supply values already normalized to [-1.0, 1.0]. Special values (NaN, ±Infinity) are preserved bit-exactly by Java's widening conversion.
  • int → double: divide by 2147483648.0 (that is 2^31). Chosen so Integer.MIN_VALUE maps exactly to -1.0; Integer.MAX_VALUE maps to 2147483647/2147483648.
  • PCM24 packed in int: the low 24 bits of each input carry a signed 24-bit value. Sign-extend from bit 23 (shift left 8, then arithmetic-shift right 8) so values in [0x800000, 0xFFFFFF] become negative, then divide by 8388608.0 (that is 2^23). After sign extension 0x800000 is -8388608 and maps exactly to -1.0; 0x7FFFFF is 8388607 and maps to 8388607/8388608.

Null and size handling: Every allocating variant rejects null input with NullPointerException via Objects.requireNonNull(Object, String) so the parameter name appears in the message (Requirement 17.1). The *Into variants additionally reject a destination shorter than the source with IllegalArgumentException naming both lengths (Requirement 17.2).

Although the type is public so com.tino1b2be.dtmf.DtmfDecoder in the sibling package can call it, the convention is that com.tino1b2be.dtmf.internal.* is not part of the published API. Callers go through DtmfDecoder or DtmfDetector instead.

  • Method Summary

    Modifier and Type
    Method
    Description
    static double[]
    fromFloat(float[] src)
    Convert normalized float samples to double in a new array via direct widening.
    static void
    fromFloatInto(float[] src, double[] dst)
    Copy normalized float samples into a caller-supplied double[] destination via direct widening, starting at index 0.
    static double[]
    fromInt(int[] src)
    Convert signed PCM32 samples to normalized double in a new array.
    static void
    fromIntInto(int[] src, double[] dst)
    Convert signed PCM32 samples into a caller-supplied destination starting at index 0.
    static double[]
    fromPcm24(int[] src)
    Convert signed PCM24 samples packed into the low 24 bits of each int to normalized double in a new array.
    static double[]
    fromShort(short[] src)
    Convert signed PCM16 samples to normalized double in a new array.
    static void
    fromShortInto(short[] src, double[] dst)
    Convert signed PCM16 samples into a caller-supplied destination starting at index 0.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Method Details

    • fromShort

      public static double[] fromShort(short[] src)
      Convert signed PCM16 samples to normalized double in a new array.
      Parameters:
      src - PCM16 input; must be non-null
      Returns:
      a new double[] of the same length with dst[i] = src[i] / 32768.0
      Throws:
      NullPointerException - if src is null

    • fromFloat

      public static double[] fromFloat(float[] src)
      Convert normalized float samples to double in a new array via direct widening.
      Parameters:
      src - float input; must be non-null
      Returns:
      a new double[] of the same length with dst[i] = (double) src[i] (exact widening, no scaling)
      Throws:
      NullPointerException - if src is null

    • fromInt

      public static double[] fromInt(int[] src)
      Convert signed PCM32 samples to normalized double in a new array.
      Parameters:
      src - PCM32 input; must be non-null
      Returns:
      a new double[] of the same length with dst[i] = src[i] / 2147483648.0
      Throws:
      NullPointerException - if src is null

    • fromPcm24

      public static double[] fromPcm24(int[] src)
      Convert signed PCM24 samples packed into the low 24 bits of each int to normalized double in a new array.

      Sign-extends each input from bit 23 before scaling, so the full two's-complement 24-bit range [-8388608, 8388607] is handled and values whose bit-23 is set round-trip to negative output.

      Parameters:
      src - PCM24-packed input; must be non-null
      Returns:
      a new double[] of the same length with dst[i] = signExtend24(src[i]) / 8388608.0
      Throws:
      NullPointerException - if src is null

    • fromShortInto

      public static void fromShortInto(short[] src, double[] dst)
      Convert signed PCM16 samples into a caller-supplied destination starting at index 0.
      Parameters:
      src - PCM16 input; must be non-null
      dst - destination buffer; must be non-null and have dst.length >= src.length
      Throws:
      NullPointerException - if either argument is null
      IllegalArgumentException - if dst.length < src.length

    • fromFloatInto

      public static void fromFloatInto(float[] src, double[] dst)
      Copy normalized float samples into a caller-supplied double[] destination via direct widening, starting at index 0.
      Parameters:
      src - float input; must be non-null
      dst - destination buffer; must be non-null and have dst.length >= src.length
      Throws:
      NullPointerException - if either argument is null
      IllegalArgumentException - if dst.length < src.length

    • fromIntInto

      public static void fromIntInto(int[] src, double[] dst)
      Convert signed PCM32 samples into a caller-supplied destination starting at index 0.
      Parameters:
      src - PCM32 input; must be non-null
      dst - destination buffer; must be non-null and have dst.length >= src.length
      Throws:
      NullPointerException - if either argument is null
      IllegalArgumentException - if dst.length < src.length