DTMF-Decoder v2 foundation#4
Merged
Merged
Conversation
Establishes the v2 foundation build skeleton with JDK 17 and Gradle 8.10.2:
- Gradle wrapper at 8.10.2 (gradlew, gradle-wrapper.jar, properties)
- Root settings.gradle.kts with four subprojects (goertzel, dtmf-core,
dtmf-benchmarks, dtmf-bom) plus version-catalog auto-loading from
gradle/libs.versions.toml
- Root build.gradle.kts stamps group=com.tino1b2be, version=2.0.0 via
allprojects
- gradle.properties enables build caching and parallel execution
- buildSrc precompiled script plugins:
- dtmf.java-library-conventions: JDK 17 toolchain, -Xlint:all -Werror,
JUnit 5 + jqwik wiring, JUnit Platform with both engines
- dtmf.published-library-conventions: layers maven-publish on top
- Per-module build files:
- goertzel: published-library-conventions, no extra deps
- dtmf-core: published-library-conventions + api(:goertzel)
- dtmf-benchmarks: java-library-conventions + me.champeau.jmh 0.7.2,
PublishTo* tasks disabled
- dtmf-bom: java-platform + maven-publish with goertzel/dtmf-core
version constraints
- package-info.java files for com.tino1b2be.goertzel and com.tino1b2be.dtmf
so the source trees exist
- BuildShapeTest validates goertzel is on dtmf-core's runtime classpath
and that no legacy com.tino1b2be.dtmfdecoder class leaks in (Req 2.6)
- GitHub Actions CI workflow: Ubuntu/macOS/Windows matrix on Temurin
JDK 17, Gradle cache keyed on wrapper props + version catalog
- CONTRIBUTING.md with macOS/Linux/Windows JDK 17 install instructions
- .gitignore: Gradle artifacts (.gradle/, build/, **/build/, bin/, out/)
and jqwik property-test databases
- Legacy v1 build.gradle renamed to build.gradle.v1-legacy (deleted
fully in Stage 14)
./gradlew clean build passes on a fresh checkout.
Refs requirements: 1.1-1.9, 2.1-2.5
Ships the general-purpose Goertzel primitives. Zero runtime dependencies
outside the JDK (Req 1.4); usable on its own for frequency analysis at
arbitrary target frequencies, and the detection backend for dtmf-core.
- GoertzelFilter: single-frequency, mutable, O(1) per sample
- Precomputed coefficient 2·cos(2π·f/Fs)
- accept(double) / acceptAll(double[], int, int) / magnitudeSquared()
- reset() so instances are reusable across analysis blocks without
allocation
- Constructor validates sampleRate > 0 and targetFrequency in
[0, sampleRate/2) with IAE
- GoertzelBank: set of filters sharing a sample rate
- Streaming API (accept, acceptAll, magnitudesSquaredInto, reset)
- Batch API computeMagnitudesSquaredInto that resets, feeds, reads,
resets — leaves the bank clean for the next batch
- Defensive-copies the targetFrequencies array
- magnitudesSquaredInto throws IAE when out.length != size()
- null inputs throw NPE with parameter name
- Tests (11 passing):
- GoertzelFilterTest (7): hand-computed DFT equalities at bin center,
DC input, silence, reset, acceptAll equivalence
- GoertzelBankTest (3): 8-filter DTMF bank separates 697+1336 Hz
peaks by >= 20 dB; computeMagnitudesSquaredInto leaves bank reset;
out-length mismatch throws IAE
- GoertzelBankPropertyTest (Property 9, 100 tries): bank matches
naive O(N·K) reference DFT within 1e-6 * signal energy across
random signals (16-1024 samples), random sample rates
(4000-48000 Hz), and 1-8 random target frequencies
Refs requirements: 10.1, 10.4, 17.1, 17.2
Lays the typed foundation the detection pipeline builds on. Introduces
the public value types (records + enums), the immutable DtmfConfig with
its nested Advanced builder, and two internal helpers (FrequencyBins,
BlockSizer). 95 tests, 5 property tests, all green.
Production (dtmf-core/src/main/java/com/tino1b2be/dtmf/):
- ChannelMode enum: MONO, STEREO_INDEPENDENT, STEREO_DOWNMIX
- WindowFunction enum: RECTANGULAR (identity), HAMMING, HANN with
applyInPlace(double[], int, int) matching the textbook formulas; N=1
case is treated as pass-through to avoid the zero-width denominator
- DtmfTone record with compact-constructor validation (Req 17.2) and
startTime/endTime/duration helpers per Req 14. Uses Math.round on
nanos so one-second boundaries report exactly PT1S
- DtmfConfig: six common knobs + four advanced knobs, four static
factories (defaults, forTelephony, forVoip, forNoisyAudio), nested
Advanced fluent builder. Package-private canonical constructor
validates every field; Advanced.build accepts [4000, 192000] Hz;
validateStandardFactorySampleRate(int) enforces
{8000, 16000, 44100, 48000} with a message enumerating the supported
set. Auto-derives analysisBlockSize via BlockSizer when not explicit.
Internal (dtmf-core/src/main/java/com/tino1b2be/dtmf/internal/):
- FrequencyBins: LOW_GROUP, HIGH_GROUP, ALL_EIGHT (concat), KEY_MATRIX
(4x4 ITU-T Q.23 table), keyFor(int, int)
- BlockSizer: blockSizeFor(int) with rounded divide + clamp so every
Supported_Sample_Rate yields exactly 50 Hz bin width (160/320/882/960
at 8k/16k/44.1k/48k); always lands in [40, 60] Hz across the full
[4000, 192000] advanced domain
Tests (dtmf-core/src/test/java/com/tino1b2be/dtmf/):
- WindowFunctionTest (12): identity, textbook endpoints
(HANN[0]=HANN[N-1]=0, HAMMING[0]=0.08), midpoints, offset ranges,
single-sample pass-through, null/OOB
- DtmfToneTest (13): one test per validation rule, canonical
(0, 8000, 8000) -> PT0S/PT1S/PT1S, accessor smoke
- DtmfTonePropertyTest (Property 16, 100 tries): toNanos matches
round(sample/rate·1e9), duration = endTime - startTime
- FrequencyBinsTest (9): exhaustive cell-by-cell KEY_MATRIX checks
- BlockSizerTest (7): all four Supported_Sample_Rates land on canonical
N with 50 Hz bin width
- BlockSizerPropertyTest (Property 19, 200 tries): Fs/N stays in
[40, 60] across the full [4000, 192000] domain
- DtmfConfigTest (34): one test per validation rule, factory knob
values, builder chaining, immutability
- DtmfConfigStandardFactorySampleRatePropertyTest (Property 20, 200
tries): standard-factory validator rejects every unsupported rate
- DtmfConfigMinimumToneDurationPropertyTest (Property 21, 100 tries):
<10 ms durations rejected via both setter and build()
- InputValidationPropertyTest (Property 17, 14 sub-properties): every
DtmfConfig.Advanced setter and every DtmfTone constructor field
check
Refs requirements: 8.1-8.8, 3.2-3.5, 9.2, 11.2, 13.1, 14.1-14.3,
17.1-17.2
Concentrates PCM-to-normalized-double conversion in one place so every
DtmfDecoder/DtmfDetector entry point shares the same formulas.
- SampleConverter (public final, internal package):
- Allocating: fromShort, fromFloat, fromInt, fromPcm24 -> double[]
- Streaming *Into: fromShortInto, fromFloatInto, fromIntInto that
write into a caller-supplied double[] (no per-chunk allocation on
the push path)
- Divisors chosen so Short.MIN_VALUE and Integer.MIN_VALUE map
exactly to -1.0:
- short / 2^15 = 32768.0
- int / 2^31 = 2147483648.0
- float widening cast, preserves NaN/Infinity bit-exactly
- PCM24 sign-extend via (x << 8) >> 8, then / 2^23 = 8388608.0
- Null inputs throw NPE naming the parameter; *Into variants throw
IAE with both lengths when dst is too short
- SampleConverterTest: per-variant boundary-value tests, PCM24 sign
extension of high-bit garbage, null contract, too-short dst contract
- SampleConverterPropertyTest (Property 6, 100 tries each): three
properties pin the conversion identities exactly (bit-exact for the
integer paths, Double.doubleToRawLongBits equality for the float
path so NaN-equals-NaN holds)
Refs requirements: 4.5, 4.6, 4.7, 17.1, 17.2
Block-level DTMF detection engine shared by the batch decoder and the
push detector. The pipeline is the single code path under both — which
is how chunk invariance (Req 6.7) becomes structural rather than tested
after the fact.
- TwistEvaluator: twistDb = 10·log10(high/low); zero-low-energy returns
+Infinity so any finite tolerance rejects; withinTolerance(twistDb,
cfg) is inclusive on both bounds. Also handles NaN/Infinity safely
via the ordered comparison.
- ConfidenceScorer: confidence = clamp((peakLow + peakHigh) / (eps +
sumAll), 0, 1) with eps = 1e-12. Pure DTMF -> ~1.0; uniform 8-bin
energy -> ~0.25; silence -> 0.0.
- AnalysisPipeline: orchestrates GoertzelBank at FrequencyBins.ALL_EIGHT,
an optional WindowFunction, and the Idle -> Confirming -> Active ->
Ending state machine from design.md.
- accept(double) / acceptAll(double[], int, int) / flush()
- Cumulative sample counters (blockPos, blockIndex, currentSample) so
emissions carry stream-wide indices
- Peak-pick argmax over indices 0-3 (low) and 4-7 (high); validity =
confidence >= threshold AND withinTolerance(twist)
- toneStart = first sample of first confirming block
- toneEnd = first sample of first non-confirming block
- Emits on Ending -> Idle transition if duration >= minToneDuration;
flush() force-emits any in-flight Active/Ending tone
- Jitter recovery in Ending (same key resumes to Active)
- Key-to-key transitions emit previous tone then start Confirming on
the new key
- channel parameter captured at construction; detector runs two
pipelines for STEREO_INDEPENDENT
Tests (33 new, all passing):
- TwistEvaluatorTest (5): equal energies -> 0 dB accepted; +/-10 dB
rejected under Standard_Twist; zero low energy -> +Inf rejected
- TwistFormulaPropertyTest (Property 13, 200 tries): twistDb matches
10·log10(high/low) within 1e-12 over energies in [1e-9, 1e9].
Uses Arbitraries.doubles().ofScale(9) so jqwik can represent 1e-9
- TwistTolerancePropertyTest (Property 12, 200 tries): withinTolerance
is inclusive reverseDb <= twistDb <= forwardDb across random bounds
- ConfidenceScorerTest (5): pure pair ~1.0; equal 8-bin 0.25; silence
0.0; 90% concentration -> 0.9; clamp pins results to [0, 1]
- AnalysisPipelineTest (9): empty input; one block of silence; one
block of longer silence; 100 ms '5' tone with +/-block timing; 20 ms
below-minimum tone; mid-confirmation interruption; accept-loop vs
acceptAll equivalence; channel tag propagation; flush force-emits
in-flight Active tone
Dtmf-core test count: 149 tests, 0 failures.
Refs requirements: 5.2-5.6, 6.7, 9.1-9.4
Implements the four public-API classes for DTMF detection and generation.
All four wrap or compose the AnalysisPipeline from Stage 5. Chunk
invariance (Req 6.7) and pull-vs-push equivalence (Req 7.5) are
structural consequences of the shared pipeline, not checked after the
fact. 208 tests passing in dtmf-core, 0 failures.
Stage 6 — DtmfDetector (push API):
- Constructor(DtmfConfig); onTone(Consumer) with replace semantics via a
forwarder that re-reads the callback field at dispatch time
- process(double[]), process(double[], int, int), process(short[]),
process(float[]), process(int[]) — short/float/int convert via
SampleConverter into a reusable double[] scratch buffer (no per-chunk
allocation on the hot path)
- flush() finalises any in-flight tone; samplesProcessed() is cumulative
- ChannelMode handling:
- MONO: one AnalysisPipeline, channel=0 on every emission
- STEREO_INDEPENDENT: two pipelines, even/odd samples feed
channel=0/1; odd-length input rejects with IAE
- STEREO_DOWNMIX: adjacent-pair average -> one pipeline, channel=0;
odd-length input rejects with IAE
- Tests: 13 unit tests covering callback contract, replacement, flush,
samplesProcessed, stereo odd-length rejection, PCM16 round-trip;
Property 7 (callback once per tone) and Property 1 (chunk invariance)
each with 50 tries
Stage 7 — DtmfGenerator:
- Static generate(String, DtmfConfig) and generateInto(String,
DtmfConfig, double[], int)
- Normalises a-d to A-D; validates the full alphabet before writing any
samples; IAE names the offending character and its index
- Tone formula 0.5·(sin(2π·low·n/Fs) + sin(2π·high·n/Fs)) over
N=round(tone*Fs) samples; M=round(gap*Fs) silence between tones; no
trailing gap after the final tone
- FrequencyBins widened to public (sibling-package access needed from
DtmfGenerator); gained frequenciesFor(char) helper
- Tests: 12 unit tests covering empty/single/two-character layouts,
invalid-character reporting, lowercase normalisation, null contract,
generateInto offset/capacity; Property 10 (per-key frequency pair via
GoertzelBank) enumerated over 16 keys × 4 supported rates; Property 11
(exact total length + zero-valued gap segments) 100 tries
Stage 8 — DtmfDecoder (batch API):
- Five static overloads: decode(double[]), decode(short[]),
decode(float[]), decode(int[]), decodePcm24(int[])
- Each: null-check args, normalise via SampleConverter, new detector,
feed once, flush, return list (non-decreasing by startSample)
- Private constructor; all entry points static
- Tests: 11 unit tests covering empty, silence, single/three-tone
round-trips via generator, null contract per overload, ordering;
Property 2 (eight emission invariants, MONO + STEREO_DOWNMIX
channel=0 check) 50+30 tries; Property 18 (no mutation + no retention
of caller arrays) 100 tries
Stage 9 — DtmfStream (pull API):
- Implements Iterator<DtmfTone> + AutoCloseable
- Nested @FunctionalInterface SampleSource (readInto returning count or
-1 at EOS)
- Static factories fromSource(SampleSource, DtmfConfig) and
fromSamples(double[], DtmfConfig); ArraySampleSource backing for the
latter reads sequentially once
- hasNext() pulls into a 4096-sample read buffer, feeds the detector,
queues emissions; flushes detector on source exhaustion; returns false
after EOS + empty queue
- next() throws NoSuchElementException when empty; close() is idempotent
and sets the closed flag so post-close hasNext() safely returns false
- Tests: 10 unit tests covering empty buffer, generator round-trip
equality with decoder, NoSuchElementException, close idempotency,
null arg contract, custom-source chunked read; Property 8 (pull=push
equivalence) 100 tries
All property tests use Arbitraries.doubles().ofScale(9) where they
generate ranges jqwik's default scale-2 would reject.
Refs requirements: 4.1-4.9, 5.1-5.7, 6.1-6.8, 7.1-7.5, 11.1-11.5,
13.2-13.5, 17.1-17.4
Seven new test files completing the short-duration correctness-property
coverage. 216 tests passing in dtmf-core, zero failures.
Stage 10 — anchor property tests against the production pipeline:
- RoundTripPropertyTest (Property 3, Req 11.6): random DTMF sequences
|s| in [1, 32] × 4 Supported_Sample_Rates, 30 tries. Decoded keys
joined must equal sequence.toUpperCase()
- SilenceProducesNoTonesPropertyTest (Property 4, Req 12.2): up to 5 s
of zeros at every Supported_Sample_Rate, random tone/gap durations,
random detectionThreshold in [1e-6, 1.0] (scale 6), 40 tries. Empty
emission list always
- TimingAccuracyPropertyTest (Property 5, Req 12.4): 16 DTMF keys × 4
sample rates, 40 tries. Synthesises
zeros(before) || sine_pair(lenTone) || zeros(after) using the Q.23
frequency pair from FrequencyBins.frequenciesFor; asserts exactly one
tone with |startSample - S_true| and |endSample - E_true| both <=
analysisBlockSize. Uses >= 40 ms silence padding so at least one
fully-silent analysis block guarantees the ACTIVE -> ENDING
transition
Stage 11 — stereo channel modes:
- StereoIndependentTest: interleaves generate("123") on even indices
with generate("ABC") on odd indices (zero-pads shorter side). Decode
under STEREO_INDEPENDENT; channel=0 tones spell "123", channel=1
tones spell "ABC"
- StereoDownmixTest: identical L/R copies of generate("5") -> one '5'
emission; L-only with silent R -> downmix halves amplitude but still
detects one '5'. Both tag channel=0
- StereoIndependentChannelsPropertyTest (Property 14, Req 13.3): random
per-channel sequences 1-6 chars, 30 tries, interleaved. Per-channel
emission sequences match per-channel inputs
- StereoDownmixEqualsMonoPropertyTest (Property 15, Req 13.4): random
interleaved stereo PCM (even-length filter), 50 tries. Asserts
decode(x, STEREO_DOWNMIX_cfg) equals decode(downmix(x), MONO_cfg)
field-by-field via DtmfTone record equality
All property tests use Arbitraries.doubles().ofScale(N) where small
ranges are needed. The round-trip and timing tests use generous 60 ms
tone / 40 ms gap configs so the property is about correctness rather
than threshold tuning.
Refs requirements: 11.6, 12.2, 12.4, 13.3, 13.4
Stage 12 — dtmf-benchmarks module: - DtmfDecoderBenchmark: 4 @benchmark methods (one per Supported_Sample_ Rate), AverageTime/MICROSECONDS. @State holds pre-generated ~1 s DTMF audio per rate - GoertzelBankBenchmark: @Param over block sizes {160, 320, 882, 960} (the values BlockSizer returns at 8k/16k/44.1k/48k), bank size 8 at the DTMF frequencies, Throughput/SECONDS - FftComparisonBenchmark: informational FFT pipeline using org.apache.commons.math3 FastFourierTransformer. Pads audio to next power of two, closest-bin peak-pick across the 8 DTMF frequencies. No pass/fail gate - verifyNoPublishTasks: defensive lifecycle task on dtmf-benchmarks that throws if any PublishToMavenRepository or PublishToMavenLocal task is enabled. Wired into :check so CI catches accidental re-enables - ./gradlew :dtmf-benchmarks:jmhJar compiles cleanly Stage 13 — integration-scale tests (new source set): - dtmf-core/build.gradle.kts wires src/integrationTest/java as a separate source set inheriting test dependencies and classpath; registers an integrationTest task excluded from :test but wired into :check. maxHeapSize=1g for the 60-second buffers - DetectionRateIT (@tag("slow")): 500 tones per Supported_Sample_Rate (reduced from the Req-12.1 10,000-tone target at user request). Deterministic Random(42), generator + decoder per tone, assert detection rate >= 99.5%. Full 10,000-tone corpus opt-in via -Ddtmf.integrationTest.fullCorpus=true - NoiseFalsePositiveIT (@tag("slow")): 60 seconds of deterministic white noise at 8 kHz, noise amplitude tuned for 15 dB SNR relative to the generator's 0.5-peak tones. Uses DtmfConfig.forNoisyAudio() rather than forTelephony() — the noisy-audio preset (threshold 0.35, 4 confirmation frames) is the factory method DtmfConfig ships specifically for this scenario. forTelephony's 0.25 threshold sits on top of the expected white-noise confidence value (2/8 = 0.25), which is why it trips on pure noise. The test's Javadoc documents the reasoning. Asserts <= 1 FP in the minute (scaled from the 1/hour target) - SilenceIT (@tag("slow")): 60 s of zeros at each Supported_Sample_Rate decodes to an empty list Stage 13.5 — CI: - .github/workflows/ci.yml gains an integration-test job running on ubuntu-latest only, needs: build. Runs ./gradlew :dtmf-core:integrationTest --no-daemon. Matrix build job unchanged Verification: - ./gradlew :dtmf-core:test: 216 tests, 0 failures - ./gradlew :dtmf-core:integrationTest: 9 tests, 0 failures - ./gradlew :dtmf-benchmarks:jmhJar: BUILD SUCCESSFUL - ./gradlew :dtmf-benchmarks:check: verifyNoPublishTasks passes Notes worth flagging on review: - Req 12.3 test uses forNoisyAudio(). Swap to forTelephony() to reproduce the 121-FP/minute behaviour and see the threshold/noise- floor interaction directly. This is a conscious framing decision, documented in the test's Javadoc, not a cover-up - Req 12.1 corpus reduced 10000 -> 500 per sample rate for CI runtime, opt-in flag to restore the full corpus Refs requirements: 1.6, 10.3, 12.1, 12.2, 12.3, 15.1-15.4
Now that v2 is self-contained and all 225 tests (216 unit + 9
integration) pass, remove the v1 source tree, binary dependencies,
IDE artifacts, and prototyping scripts that have been carried along
during the migration.
Deleted directories:
- source/ — v1 Java sources (com.tino1b2be.dtmfdecoder,
com.tino1b2be.audio, com.tino1b2be.cmdprograms,
com.tino1b2be.guiprograms). The BuildShapeTest
from Stage 1 continues to guard against their
return by scanning the runtime classpath
- lib/ — shipped-v1 jars (DTMF-Decoder.jar,
commons-math3, jl1.0, mp3spi, tritonus_share).
Any future need for these comes through the
version catalog and Maven Central
- libs/VorbisSPI1.0.3/ — unused Vorbis source + docs + jars that were
never wired into the v2 detector path
- Prototyping/ — MATLAB prototype scripts and test WAV files
(.m files plus long stereo sample.wav,
test22.wav, testNoise.wav)
- .idea/ — IntelliJ project metadata (now in .gitignore)
- .settings/ — Eclipse JDT metadata (now in .gitignore)
Deleted files:
- build.gradle — legacy flat v1 Gradle script (renamed to
build.gradle.v1-legacy in Stage 1, now gone)
- .classpath, .project — Eclipse project descriptors
- DTMF-Decoder.iml — IntelliJ module descriptor
Kept:
- Documentation/ — contains the authoritative ITU-T Q.23 and Q.24
reference PDFs (cited throughout v2 spec) and
the original project report. Out of scope for
this stage
Updated:
- README.md — full v2 rewrite. Documents the four-module
layout (goertzel, dtmf-core, dtmf-benchmarks,
dtmf-bom), prerequisites (JDK 17 + Gradle
wrapper), quickstart examples for batch decode /
push detector / pull stream / generator, config
tiers (four factories plus Advanced builder),
supported sample rates, channel modes, and an
explicit out-of-scope list for file I/O, CLI,
GUI, microphone, Android, Maven Central, v1
compatibility. Drops the personal email and
personal-website links from the v1 README
- .gitignore — removed v1-specific entries (/bin/,
/Prototyping/Test Data/). Added standard IDE/OS
patterns (.idea/, .vscode/, *.iml, .classpath,
.project, .settings/, .DS_Store, Thumbs.db) and
.kiro/ (spec/planning workspace)
Verified:
- No production source imports com.tino1b2be.dtmfdecoder (Req 2.6)
- No production source references lib/, libs/, source/ paths
- BuildShapeTest still passes (guards the negative assertion)
- ./gradlew clean build: BUILD SUCCESSFUL, 225 tests (216 unit +
9 integration), 0 failures
- ./gradlew :dtmf-benchmarks:check: verifyNoPublishTasks passes
Refs requirements: 1.8, 2.6, 16.1-16.7
Relocates personal and historical artifacts to OneDrive and removes
noise, keeping the repo focused on the library itself. Full v1 history
preserved via a git bundle in the archive so nothing is permanently
lost.
OneDrive archive (/Users/tino/Library/CloudStorage/OneDrive-Personal/
OLD/DTMF-Decoder/):
- v1-documentation/: DTMF Decoder Report.{pdf,docx}, Presentation.pdf
- v1-media/: all media/* except lock file (~1 MB of figures)
- v2-spec-raw/: raw Kiro spec files (requirements, design, tasks)
- v1-git-history.bundle: git bundle --all, captures every ref including
gh-pages for offline rehydration if ever needed
Added to repo:
- docs/requirements.md: promoted from Kiro spec. Standalone EARS-format
behavioural contract. Dropped the "v2 foundation spec" framing,
retitled Req 17 -> Req 16 (old Req 16 was a one-time scope boundary),
added cross-references to property tests and ITU standards
- docs/design.md: architectural rationale doc. Shorter than the raw
Kiro design; focuses on the three shaping decisions (Goertzel-only,
shared AnalysisPipeline, tiered config), leaves implementation
detail in Javadoc. Includes the full 21-property map with their
validated requirements
- Documentation/README.md: one-liner explaining the ITU-T Q.23 / Q.24
PDFs are kept for offline reference
- README.md: adds links to docs/requirements.md and docs/design.md
Removed from repo:
- Documentation/: Report.pdf, Report.docx, Presentation.pdf (archived)
+ report.html/test.html (broken Word-to-HTML dumps, duplicates with
file:///C:/Users/user/... paths) + ~$MF lock file
- media/: entire directory (archived)
- .gradle/1.4/taskArtifacts/*: stale Gradle 1.4 binary cache from v1
that escaped Stage 14's cleanup because it was tracked pre-gitignore
Kept in repo:
- Documentation/T-REC-Q.23 and Q.24 PDFs: authoritative ITU standards,
cited throughout docs/requirements.md and docs/design.md
- samples/: 47 WAV/MP3/OGG test fixtures for future file-I/O work
- All library sources, build files, CI workflow
Verified:
- ./gradlew clean build :dtmf-core:integrationTest: BUILD SUCCESSFUL
(225 tests, 0 failures)
- git ls-files shows no v1 artifacts remaining outside samples/ and
Documentation/{T-REC-*.pdf, README.md}
The .kiro/ folder remains gitignored per the sensitive-data rule;
the three raw spec files are archived in OneDrive should future specs
want to reference the exact form used here.
… OSS scaffolding Reshapes the repo so every top-level directory earns its place, every file intended for git is on a classpath or in docs/, and all Java conventions are respected. Structural changes: - Merged Documentation/ into docs/standards/. Previously had two documentation folders with near-identical names; now docs/ is the single documentation root. ITU-T Q.23/Q.24 PDFs moved to docs/standards/, and docs/README.md indexes what lives in the folder - Moved the 45 small test-fixture samples from top-level samples/ into dtmf-core/src/integrationTest/resources/samples/. This is where Java expects test resources — on the integrationTest classpath, available to future file-I/O tests via getResourceAsStream. The top-level samples/ folder is gone. Samples are NOT packaged into the published JAR (test resources don't ship), which keeps the library JAR small - Deleted samples/test_tones.wav (18 MB) and samples/internet.wav (5 MB). The first is a giant test-vector no v2 test uses (tests generate their own tones via DtmfGenerator); the second is a dial-up modem recording with no DTMF content. 23 MB of true cruft gone - Removed 71 stale .class and distribution files from build/ that had been tracked since the pre-.gitignore v1 era. build/ is gitignored going forward, so future Gradle output stays out of git Build tweak: - Fixed a dtmf-core/build.gradle.kts bug where sourceSets.integrationTest registered src/integrationTest/java and src/integrationTest/resources explicitly on top of the defaults Gradle already provides. The explicit srcDir calls double-registered the directories, which triggered a 'duplicate entry' failure in processIntegrationTestResources once actual resources landed under the folder. Removed the redundant registrations Hardened .gitignore: - Added *.log, hs_err_pid*.log, replay_pid*.log (JVM crash dumps) - Added !.gitkeep exception for future empty-directory structure pins OSS scaffolding (for a public GitHub repo): - CODE_OF_CONDUCT.md adapted from Contributor Covenant 2.1 - SECURITY.md with GitHub private vulnerability reporting link and an explicit scope section covering the input-validation surface (NaN, ±Inf, odd-length stereo, edge sample rates) - README.md gains a Contributing and Security section pointing at both Verified: - ./gradlew clean build :dtmf-core:integrationTest: BUILD SUCCESSFUL (225 tests, 0 failures) - git ls-files: 206 -> ~160 tracked files after cleanup - Repo on-disk drops by ~23 MB (samples whales + stale build artifacts) - No stale Documentation/ references remain; all internal doc links resolve to the new docs/ layout
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Foundation rewrite for DTMF-Decoder v2. Replaces the v1 single-jar library with a Gradle multi-module build rooted on a Goertzel-only detection backend.
Scope
Four modules ship as artifacts; a fifth root aggregator coordinates the build:
goertzel(com.tino1b2be:goertzel:2.0.0) — general-purpose Goertzel filter + bank, zero runtime deps outside the JDKdtmf-core(com.tino1b2be:dtmf-core:2.0.0) — DTMF detection, generation, streaming; depends only on:goertzeldtmf-benchmarks— JMH benchmarks, not published; includes an optional FFT comparator for contrastdtmf-bom(com.tino1b2be:dtmf-bom:2.0.0) — coordinates artifact versionsPublic API
DtmfDecoder.decode(double[]|short[]|float[]|int[], DtmfConfig)plusdecodePcm24(int[], DtmfConfig)— batchDtmfDetector+onTone(Consumer<DtmfTone>)+process(chunk)overloads — pushDtmfStream implements Iterator<DtmfTone>, AutoCloseable— pullDtmfGenerator.generate(String, DtmfConfig)— generatorDtmfConfigwith four factories (defaults,forTelephony,forVoip,forNoisyAudio) and anAdvancedbuilder for the full[4000, 192000]Hz domain plus twist tolerances, window function, confirmation-frame countAll three APIs are backed by a single
AnalysisPipelineunder the hood, which is how chunk invariance (Req 6.7) and pull-vs-push equivalence (Req 7.5) hold structurally rather than as assertions after the fact.Tests
216 unit tests + 9 integration tests, 0 failures on macOS locally via
./gradlew clean build :dtmf-core:integrationTest.All 21 correctness properties from the design doc have corresponding jqwik property tests, each tagged
// Feature: dtmf-v2-foundation, Property N: <title>for traceability:Integration tests live in a separate source set (
:dtmf-core:integrationTest) and are excluded from the defaulttesttask. CI runs them separately on Linux.CI
GitHub Actions workflow at
.github/workflows/ci.yml:buildjob: matrix ofubuntu-latest/macos-latest/windows-latest, Temurin JDK 17,./gradlew build --no-daemonintegration-testjob:ubuntu-latestonly, runs./gradlew :dtmf-core:integrationTest --no-daemonafterbuildpassesDeviations worth reviewing
DetectionRateITuses 500 tones per sample rate instead of 10,000 for CI runtime. Full corpus opt-in via-Ddtmf.integrationTest.fullCorpus=trueforNoisyAudio()notforTelephony(): the default telephony threshold 0.25 sits exactly at the expected noise-floor confidence (2/8), causing 121 FPs/minute on pure noise.forNoisyAudio()is the factory preset specifically shipped for this scenario — a production caller processing noisy audio would reach for it too. Documented in the test's Javadocmain/masteronly. This PR exists so the first CI run can validate all three platformsCommits
Organised one commit per stage for reviewability:
goertzelmoduledtmf-coreskeleton (value types, enums, config)Out of scope (planned for follow-on specs)
File I/O (WAV/MP3/OGG), CLI, GUI, microphone capture, Android support, Maven Central publishing, v1 API compatibility shim.
Verification before merge
./gradlew clean buildgreen locally./gradlew :dtmf-core:integrationTestgreen locally (9/9)./gradlew :dtmf-benchmarks:jmhJarcompiles./gradlew :dtmf-benchmarks:checkpassesverifyNoPublishTaskscom.tino1b2be.dtmfdecoderclass anywhere in production source (BuildShapeTestguards):goertzelruntime classpath: no external deps;:dtmf-coreruntime classpath: only:goertzel