The v2 foundation (#4, v2.0.0) intentionally left file-format reading out of scope (see docs/requirements.md#out-of-scope). This issue tracks the follow-on spec to add it.
Motivation
Right now callers have to decode audio files into double[]/short[]/float[]/int[] themselves before handing off to DtmfDecoder. That's a reasonable boundary for the foundation — the library is pure DSP — but it means every consumer hits the same ceremony. A thin companion module that takes a file (or InputStream, or java.nio.file.Path, or URL) and yields samples in the format DtmfDecoder expects would remove that ceremony without bloating the core.
Proposed scope
A new module — provisional name dtmf-audio-io (or dtmf-io; naming TBD) — with:
WavDecoder — reads PCM WAV files (16/24/32-bit, mono/stereo, the canonical rates 8k/16k/44.1k/48k)Mp3Decoder — via a thin wrapper around an existing library (likely javazoom/jlayer or mp3spi — need to evaluate)OggDecoder — via an existing Vorbis library (optional; the 45 OGG test fixtures we kept make this easy to validate)- A uniform
AudioSource facade that hands back (double[], sampleRate, channelMode) tuples, so callers can wire directly into DtmfDecoder.decode(samples, cfg)
Dependency boundaries worth deciding upfront:
- Does the new module stay out of
dtmf-core's classpath? (Yes — dtmf-core should keep its JDK-only runtime-dep stance.)
- Does it expose a streaming interface backed by
DtmfStream.SampleSource? (Probably yes — this is exactly the shape that interface was designed to slot into.)
- Are the 45 samples at
dtmf-core/src/integrationTest/resources/samples/ the right fixtures, or should they move to the new module's src/test/resources/? (Leaning: move them. They're file-I/O fixtures, not DTMF-detection fixtures.)
Out of scope for this issue (again)
- CLI — separate follow-on
- GUI — separate follow-on
- Microphone capture — separate follow-on (may pair naturally with this one because both are about audio sources)
Definition of done
Next step
Kiro spec when ready — this issue is the parking spot, not the plan.
The v2 foundation (#4, v2.0.0) intentionally left file-format reading out of scope (see
docs/requirements.md#out-of-scope). This issue tracks the follow-on spec to add it.Motivation
Right now callers have to decode audio files into
double[]/short[]/float[]/int[]themselves before handing off toDtmfDecoder. That's a reasonable boundary for the foundation — the library is pure DSP — but it means every consumer hits the same ceremony. A thin companion module that takes a file (orInputStream, orjava.nio.file.Path, orURL) and yields samples in the formatDtmfDecoderexpects would remove that ceremony without bloating the core.Proposed scope
A new module — provisional name
dtmf-audio-io(ordtmf-io; naming TBD) — with:WavDecoder— reads PCM WAV files (16/24/32-bit, mono/stereo, the canonical rates 8k/16k/44.1k/48k)Mp3Decoder— via a thin wrapper around an existing library (likely javazoom/jlayer or mp3spi — need to evaluate)OggDecoder— via an existing Vorbis library (optional; the 45 OGG test fixtures we kept make this easy to validate)AudioSourcefacade that hands back(double[], sampleRate, channelMode)tuples, so callers can wire directly intoDtmfDecoder.decode(samples, cfg)Dependency boundaries worth deciding upfront:
dtmf-core's classpath? (Yes —dtmf-coreshould keep its JDK-only runtime-dep stance.)DtmfStream.SampleSource? (Probably yes — this is exactly the shape that interface was designed to slot into.)dtmf-core/src/integrationTest/resources/samples/the right fixtures, or should they move to the new module'ssrc/test/resources/? (Leaning: move them. They're file-I/O fixtures, not DTMF-detection fixtures.)Out of scope for this issue (again)
Definition of done
AudioSourceAPI with aDtmfStream.SampleSourceadapterdocs/requirements.mdgains a new Requirement section;docs/design.mdgains an architectural section; the module gets full JavadocNext step
Kiro spec when ready — this issue is the parking spot, not the plan.