release: bump to v2.1.0 and aggregate javadoc for dtmf-io modules

README.md

@@ -2,18 +2,21 @@
 
 A Java 17 library for detecting and generating [DTMF](https://en.wikipedia.org/wiki/Dual-tone_multi-frequency_signaling) (Dual-Tone Multi-Frequency) signalling tones per ITU-T Q.23 and Q.24. Ships a Goertzel-based detection backend with both batch and streaming APIs.
 
-> **Status:** v2 foundation. File I/O (WAV/MP3/OGG), CLI, GUI, microphone capture, Android support, and Maven Central publishing are explicitly out of scope for this spec and planned for follow-on releases. See [Out of scope](#out-of-scope) below.
+> **Status:** v2.1.0. File I/O ships as a separate layer in the `dtmf-io`, `dtmf-io-wav`, and `dtmf-io-mp3` modules (added in this release). CLI, GUI, microphone capture, Android support, FLAC/OGG/Opus/AAC codecs, and Maven Central publishing remain out of scope. See [Out of scope](#out-of-scope) below.
 
 ## Modules
 
-The project is a Gradle multi-module build. Four modules ship as artifacts; a fifth root aggregator coordinates the build.
+The project is a Gradle multi-module build. Five modules ship as artifacts; a sixth root aggregator coordinates the build, and a seventh (`dtmf-benchmarks`) hosts JMH benchmarks and is not published.
 
 | Module | Coordinates | Depends on | Purpose |
 |---|---|---|---|
-| `goertzel` | `com.tino1b2be:goertzel:2.0.0` | JDK 17 only | General-purpose Goertzel filter + filter bank |
-| `dtmf-core` | `com.tino1b2be:dtmf-core:2.0.0` | `goertzel` | DTMF detection, generation, streaming |
+| `goertzel` | `com.tino1b2be:goertzel:2.1.0` | JDK 17 only | General-purpose Goertzel filter + filter bank |
+| `dtmf-core` | `com.tino1b2be:dtmf-core:2.1.0` | `goertzel` | DTMF detection, generation, streaming |
+| `dtmf-io` | `com.tino1b2be:dtmf-io:2.1.0` | `dtmf-core` | Pull-based `AudioSource` SPI + `DtmfFileDecoder` |
+| `dtmf-io-wav` | `com.tino1b2be:dtmf-io-wav:2.1.0` | `dtmf-io` | WAV `AudioSourceProvider` (clean-room RIFF parser) |
+| `dtmf-io-mp3` | `com.tino1b2be:dtmf-io-mp3:2.1.0` | `dtmf-io`, JLayer, mp3spi | MP3 `AudioSourceProvider` |
 | `dtmf-benchmarks` | *(not published)* | `dtmf-core`, `goertzel` | JMH benchmarks |
-| `dtmf-bom` | `com.tino1b2be:dtmf-bom:2.0.0` | *(BOM only)* | Pins `goertzel` and `dtmf-core` at a coordinated version |
+| `dtmf-bom` | `com.tino1b2be:dtmf-bom:2.1.0` | *(BOM only)* | Pins the five shipping libraries at a coordinated version |
 
 ## Prerequisites
 
@@ -138,9 +141,10 @@ The standard factories accept exactly `{8000, 16000, 44100, 48000}` Hz. The adva
 
 ## Out of scope
 
-The following are explicitly **not** part of v2 foundation:
+The following are explicitly **not** part of the current release:
 
-- **File I/O** — no WAV, MP3, or OGG readers. Callers supply PCM samples as `double[]`, `short[]`, `float[]`, or `int[]`.
+- **Additional audio codecs** — beyond WAV and MP3. FLAC, OGG Vorbis, Opus, and AAC are future spec candidates.
+- **Production WAV/MP3 encoding** — `dtmf-io-wav` includes only a test-only encoder for round-trip tests; no public encoding API ships.
 - **CLI** — no command-line interface module.
 - **GUI** — no Swing, AWT, JavaFX, or applet code.
 - **Microphone capture** — no real-time audio input.

build.gradle.kts

@@ -2,7 +2,7 @@
 //
 // Per Task 1.6 of the dtmf-v2-foundation spec: the root applies no plugins
 // itself. Its sole responsibility is to stamp consistent Maven coordinates
-// — group `com.tino1b2be` and version `2.0.0` — onto every subproject
+// — group `com.tino1b2be` and version `2.1.0` — onto every subproject
 // (Requirements 2.1, 2.2, 2.3).
 //
 // `allprojects` (rather than `subprojects`) is used deliberately. The root
@@ -14,7 +14,7 @@
 
 allprojects {
     group = "com.tino1b2be"
-    version = "2.0.0"
+    version = "2.1.0"
 }
 
 // -------------------------------------------------------------------------
@@ -31,10 +31,19 @@ allprojects {
 //     index.html                  ← landing page listing the modules
 //     goertzel/                   ← :goertzel javadoc
 //     dtmf-core/                  ← :dtmf-core javadoc
+//     dtmf-io/                    ← :dtmf-io javadoc
+//     dtmf-io-wav/                ← :dtmf-io-wav javadoc
+//     dtmf-io-mp3/                ← :dtmf-io-mp3 javadoc
 //
 // Consumers can browse the full API at tino1b2be.github.io/DTMF-Decoder.
 
-val publishedModuleNames = setOf("goertzel", "dtmf-core")
+val publishedModuleNames = setOf(
+    "goertzel",
+    "dtmf-core",
+    "dtmf-io",
+    "dtmf-io-wav",
+    "dtmf-io-mp3",
+)
 
 tasks.register("aggregateJavadoc") {
     group = "documentation"

dtmf-bom/build.gradle.kts

@@ -11,8 +11,9 @@
 //
 // Group and version are stamped by the root `build.gradle.kts` via
 // `allprojects` — this BOM therefore publishes as
-// `com.tino1b2be:dtmf-bom:2.0.0` and pins the two shipping libraries at the
-// same coordinate. Maven Central publishing is intentionally out of scope
+// `com.tino1b2be:dtmf-bom:2.1.0` and pins the five shipping libraries
+// (goertzel, dtmf-core, dtmf-io, dtmf-io-wav, dtmf-io-mp3) at the same
+// coordinate. Maven Central publishing is intentionally out of scope
 // for the foundation spec (Requirement 16.6); this module only wires the
 // publication so `publishToMavenLocal` works for local smoke-testing.
 
@@ -27,11 +28,11 @@ javaPlatform {
 
 dependencies {
     constraints {
-        api("com.tino1b2be:goertzel:2.0.0")
-        api("com.tino1b2be:dtmf-core:2.0.0")
-        api("com.tino1b2be:dtmf-io:2.0.0")
-        api("com.tino1b2be:dtmf-io-wav:2.0.0")
-        api("com.tino1b2be:dtmf-io-mp3:2.0.0")
+        api("com.tino1b2be:goertzel:2.1.0")
+        api("com.tino1b2be:dtmf-core:2.1.0")
+        api("com.tino1b2be:dtmf-io:2.1.0")
+        api("com.tino1b2be:dtmf-io-wav:2.1.0")
+        api("com.tino1b2be:dtmf-io-mp3:2.1.0")
     }
 }
 

dtmf-core/build.gradle.kts

@@ -8,7 +8,7 @@
 // and the bare `maven-publish` publication all come from
 // `dtmf.published-library-conventions` (layered on top of
 // `dtmf.java-library-conventions`). Maven coordinates
-// (`com.tino1b2be:dtmf-core:2.0.0`) are inherited from the root
+// (`com.tino1b2be:dtmf-core:2.1.0`) are inherited from the root
 // `build.gradle.kts` via `allprojects`.
 
 plugins {

dtmf-io-mp3/build.gradle.kts

@@ -24,7 +24,7 @@
 // `maven-publish` publication all come from
 // `dtmf.published-library-conventions` (layered on top of
 // `dtmf.java-library-conventions`). Maven coordinates
-// (`com.tino1b2be:dtmf-io-mp3:2.0.0`) are inherited from the root
+// (`com.tino1b2be:dtmf-io-mp3:2.1.0`) are inherited from the root
 // `build.gradle.kts` via `allprojects`.
 
 plugins {

dtmf-io-mp3/src/main/java/com/tino1b2be/dtmf/io/mp3/Mp3AudioSource.java

@@ -109,7 +109,7 @@
  * identifying the source as closed (Requirement 3.14).
  * {@link #close()} itself is idempotent.
  *
- * @since 2.0.0
+ * @since 2.1.0
  * @see AudioSource
  * @see Mp3AudioSourceProvider
  */

dtmf-io-mp3/src/main/java/com/tino1b2be/dtmf/io/mp3/Mp3AudioSourceProvider.java

@@ -138,7 +138,7 @@
  * their own lifecycle and are <em>not</em> thread-safe &mdash; see
  * {@link Mp3AudioSource}.
  *
- * @since 2.0.0
+ * @since 2.1.0
  * @see Mp3AudioSource
  * @see Mp3HeaderScanner
  * @see AudioSourceProvider

dtmf-io-mp3/src/main/java/com/tino1b2be/dtmf/io/mp3/internal/Mp3HeaderScanner.java

@@ -91,7 +91,7 @@
  * entirely to whether the caller-supplied stream is safe to read from
  * concurrently — a question outside this scanner's scope.
  *
- * @since 2.0.0
+ * @since 2.1.0
  */
 public final class Mp3HeaderScanner {
 

dtmf-io-mp3/src/main/java/com/tino1b2be/dtmf/io/mp3/internal/package-info.java

@@ -17,6 +17,6 @@
  * {@code Mp3AudioSourceProvider} and {@code Mp3AudioSource} in the parent
  * package.
  *
- * @since 2.0.0
+ * @since 2.1.0
  */
 package com.tino1b2be.dtmf.io.mp3.internal;

dtmf-io-mp3/src/main/java/com/tino1b2be/dtmf/io/mp3/package-info.java

@@ -35,6 +35,6 @@
  * Stage 1 so the source tree exists for the build-shape smoke tests in
  * Task 1.8.
  *
- * @since 2.0.0
+ * @since 2.1.0
  */
 package com.tino1b2be.dtmf.io.mp3;

dtmf-io-wav/build.gradle.kts

@@ -17,7 +17,7 @@
 // `maven-publish` publication all come from
 // `dtmf.published-library-conventions` (layered on top of
 // `dtmf.java-library-conventions`). Maven coordinates
-// (`com.tino1b2be:dtmf-io-wav:2.0.0`) are inherited from the root
+// (`com.tino1b2be:dtmf-io-wav:2.1.0`) are inherited from the root
 // `build.gradle.kts` via `allprojects`.
 
 plugins {

dtmf-io-wav/src/main/java/com/tino1b2be/dtmf/io/wav/WavAudioSource.java

@@ -88,7 +88,7 @@
  * identifying the source as closed (Requirement 3.14).
  * {@link #close()} itself is idempotent.
  *
- * @since 2.0.0
+ * @since 2.1.0
  * @see AudioSource
  * @see WavAudioSourceProvider
  * @see WavSampleReader

dtmf-io-wav/src/main/java/com/tino1b2be/dtmf/io/wav/WavAudioSourceProvider.java

@@ -99,7 +99,7 @@
  * whose {@link AudioSource#close()} transitions the source into the
  * closed state but leaves the caller's {@link InputStream} untouched.
  *
- * @since 2.0.0
+ * @since 2.1.0
  * @see WavAudioSource
  * @see AudioSourceProvider
  * @see AudioSource

dtmf-io-wav/src/main/java/com/tino1b2be/dtmf/io/wav/internal/RiffChunk.java

@@ -58,7 +58,7 @@
  * @param dataStartOffset absolute byte position of the first payload
  *                        byte within the enclosing source; must be
  *                        non-negative
- * @since 2.0.0
+ * @since 2.1.0
  */
 public record RiffChunk(String id, long size, long dataStartOffset) {
 

dtmf-io-wav/src/main/java/com/tino1b2be/dtmf/io/wav/internal/RiffReader.java

@@ -64,7 +64,7 @@
  * mediates mutable byte-source state and must be used by one thread at a
  * time. Concurrent calls are undefined behaviour.
  *
- * @since 2.0.0
+ * @since 2.1.0
  */
 public final class RiffReader {
 

dtmf-io-wav/src/main/java/com/tino1b2be/dtmf/io/wav/internal/WavSampleReader.java

@@ -120,7 +120,7 @@
  * classes in the parent {@code com.tino1b2be.dtmf.io.wav} package can
  * reach it; external callers MUST NOT depend on it.
  *
- * @since 2.0.0
+ * @since 2.1.0
  */
 public final class WavSampleReader {
 

dtmf-io-wav/src/main/java/com/tino1b2be/dtmf/io/wav/internal/WaveFormat.java

@@ -98,7 +98,7 @@
  * @param totalFrames         number of complete frames in the payload
  *                            ({@code dataSizeBytes / bytesPerFrame});
  *                            must be non-negative
- * @since 2.0.0
+ * @since 2.1.0
  */
 public record WaveFormat(
         int sampleRate,

dtmf-io-wav/src/main/java/com/tino1b2be/dtmf/io/wav/internal/package-info.java

@@ -18,6 +18,6 @@
  * lives on {@code WavAudioSourceProvider} and {@code WavAudioSource} in the
  * parent package.
  *
- * @since 2.0.0
+ * @since 2.1.0
  */
 package com.tino1b2be.dtmf.io.wav.internal;

dtmf-io-wav/src/main/java/com/tino1b2be/dtmf/io/wav/package-info.java

@@ -31,6 +31,6 @@
  * Stage 1 so the source tree exists for the build-shape smoke tests in
  * Task 1.8.
  *
- * @since 2.0.0
+ * @since 2.1.0
  */
 package com.tino1b2be.dtmf.io.wav;

dtmf-io-wav/src/test/java/com/tino1b2be/dtmf/io/wav/WavEncoder.java

@@ -98,7 +98,7 @@
  * {@code dtmf-io-wav} jar. External consumers MUST NOT depend on it, at
  * any version, via any mechanism.
  *
- * @since 2.0.0
+ * @since 2.1.0
  */
 final class WavEncoder {
 

dtmf-io/build.gradle.kts

@@ -14,7 +14,7 @@
 // `maven-publish` publication all come from
 // `dtmf.published-library-conventions` (layered on top of
 // `dtmf.java-library-conventions`). Maven coordinates
-// (`com.tino1b2be:dtmf-io:2.0.0`) are inherited from the root
+// (`com.tino1b2be:dtmf-io:2.1.0`) are inherited from the root
 // `build.gradle.kts` via `allprojects`.
 
 plugins {

dtmf-io/src/integrationTest/java/com/tino1b2be/dtmf/io/IntegrationWavEncoder.java

@@ -27,7 +27,7 @@
  * <p>Not part of the published API. Used only by
  * {@code OpenWavIT} / {@code UnrecognizedInputIT} helpers.
  *
- * @since 2.0.0
+ * @since 2.1.0
  */
 final class IntegrationWavEncoder {
 

dtmf-io/src/integrationTest/java/com/tino1b2be/dtmf/io/Mp3RoundTripIT.java

@@ -91,7 +91,7 @@
  * pathological case (e.g. LAME producing a degenerate frame) does not
  * fail the suite as long as the corpus average stays above 99%.
  *
- * @since 2.0.0
+ * @since 2.1.0
  */
 @Tag("slow")
 @EnabledIfSystemProperty(

dtmf-io/src/integrationTest/java/com/tino1b2be/dtmf/io/OpenMp3IT.java

@@ -52,7 +52,7 @@
  * directory happens to be the repo root rather than the module
  * directory.
  *
- * @since 2.0.0
+ * @since 2.1.0
  */
 final class OpenMp3IT {
 

dtmf-io/src/integrationTest/java/com/tino1b2be/dtmf/io/OpenWavIT.java

@@ -32,7 +32,7 @@
  * package, and feed the same file through {@code DtmfFileDecoder} to
  * recover the original keys.
  *
- * @since 2.0.0
+ * @since 2.1.0
  */
 final class OpenWavIT {
 

dtmf-io/src/integrationTest/java/com/tino1b2be/dtmf/io/RegisteredFormatsIT.java

@@ -22,7 +22,7 @@
  * {@code dtmf-io-mp3} — what matters for callers is that both names are
  * present.
  *
- * @since 2.0.0
+ * @since 2.1.0
  */
 final class RegisteredFormatsIT {
 

dtmf-io/src/integrationTest/java/com/tino1b2be/dtmf/io/UnrecognizedInputIT.java

@@ -34,7 +34,7 @@
  * is negligible but non-zero for truly random bytes, so pinning the seed
  * is strictly more robust than calling {@code new Random()} here.
  *
- * @since 2.0.0
+ * @since 2.1.0
  */
 final class UnrecognizedInputIT {
 

dtmf-io/src/main/java/com/tino1b2be/dtmf/io/AudioSource.java

@@ -91,7 +91,7 @@
  * as closed (Requirement 3.14). {@link #close()} itself remains callable
  * and is a no-op on subsequent invocations.
  *
- * @since 2.0.0
+ * @since 2.1.0
  * @see AudioSourceProvider
  * @see AudioSources
  * @see RawPcmAudioSource

dtmf-io/src/main/java/com/tino1b2be/dtmf/io/AudioSourceProvider.java

@@ -84,7 +84,7 @@
  * explicitly nullable and implementations must tolerate {@code null}
  * without throwing.
  *
- * @since 2.0.0
+ * @since 2.1.0
  */
 public interface AudioSourceProvider {
 

dtmf-io/src/main/java/com/tino1b2be/dtmf/io/AudioSources.java

@@ -92,7 +92,7 @@
  * call. Provider instances themselves may be called concurrently from
  * multiple threads; see {@link AudioSourceProvider} for that contract.
  *
- * @since 2.0.0
+ * @since 2.1.0
  * @see AudioSource
  * @see AudioSourceProvider
  * @see UnsupportedAudioFormatException

dtmf-io/src/main/java/com/tino1b2be/dtmf/io/DtmfFileDecoder.java

@@ -92,7 +92,7 @@
  * are safe to invoke concurrently from multiple threads on different
  * inputs.
  *
- * @since 2.0.0
+ * @since 2.1.0
  * @see AudioSources
  * @see DtmfDecoder
  * @see DtmfConfig

dtmf-io/src/main/java/com/tino1b2be/dtmf/io/PcmEncoding.java

@@ -40,7 +40,7 @@
  * decode to signed 16-bit PCM and bypass the raw-PCM constructor path
  * entirely.
  *
- * @since 2.0.0
+ * @since 2.1.0
  * @see RawPcmAudioSource
  */
 public enum PcmEncoding {

dtmf-io/src/main/java/com/tino1b2be/dtmf/io/RawPcmAudioSource.java

@@ -70,7 +70,7 @@
  * underlying {@code byte[]} (which is safe provided no one mutates the
  * bytes).
  *
- * @since 2.0.0
+ * @since 2.1.0
  * @see AudioSource
  * @see PcmEncoding
  * @see com.tino1b2be.dtmf.io.internal.SampleConversion

dtmf-io/src/main/java/com/tino1b2be/dtmf/io/UnsupportedAudioFormatException.java

@@ -51,7 +51,7 @@
  * caught exception to multiple consumers is safe; attempting to mutate
  * the returned collections throws {@link UnsupportedOperationException}.
  *
- * @since 2.0.0
+ * @since 2.1.0
  * @see AudioSources
  * @see AudioSourceProvider
  */

dtmf-io/src/main/java/com/tino1b2be/dtmf/io/internal/ProviderScore.java

@@ -42,7 +42,7 @@
  * @param priority the value of {@link AudioSourceProvider#priority()} at
  *                 the time of scoring, used as the tie-breaker when two
  *                 providers return the same {@code score}
- * @since 2.0.0
+ * @since 2.1.0
  */
 public record ProviderScore(AudioSourceProvider provider, int score, int priority) {