Add file-absolute start_seconds/end_seconds to enterprise matches

recognize_enterprise now reports where each song plays in the file as
start_seconds / end_seconds (seconds, file-absolute). These are computed from
the chunk offset the response otherwise carries only at the chunk level, so the
position is no longer lost when chunks are flattened. The endpoint is now asked
for accurate offsets by default, so the values are precise. The raw
start_offset / end_offset remain as the fragment-relative milliseconds.

Author: Mikhail Samin's Claude

README.md

@@ -140,9 +140,14 @@ Valid `returnMetadata` values: `apple_music`, `spotify`, `deezer`,
 
 For longer audio files, use `audd.recognizeEnterprise(source,
 opts)` — it returns `List<EnterpriseMatch>`. Each `EnterpriseMatch`
-carries the same core tags plus `score()`, `startOffset()`, `endOffset()`,
-`isrc()`, `upc()`. Access to `isrc`, `upc`, and `score` requires a Startup
-plan or higher — [contact us](mailto:api@audd.io) for enterprise features.
+carries the same core tags plus `score()`, `startSeconds()`, `endSeconds()`,
+`startOffset()`, `endOffset()`, `isrc()`, `upc()`. `startSeconds()` and
+`endSeconds()` are where the song plays in your file, in seconds — precise
+because accurate offsets are requested by default (pass
+`accurateOffsets(false)` to opt out). Behind them, `startOffset()` and
+`endOffset()` are the raw fragment-relative milliseconds. Access to `isrc`,
+`upc`, and `score` requires a Startup plan or higher — [contact
+us](mailto:api@audd.io) for enterprise features.
 
 ### Reading additional metadata
 

pom.xml

@@ -6,7 +6,7 @@
 
   <groupId>io.audd</groupId>
   <artifactId>audd</artifactId>
-  <version>1.5.13</version>
+  <version>1.5.14</version>
   <packaging>jar</packaging>
 
   <name>AudD Java SDK</name>

src/main/java/io/audd/AsyncAudD.java

@@ -152,7 +152,10 @@ public CompletableFuture<List<EnterpriseMatch>> recognizeEnterprise(Object sourc
                     for (JsonNode chunkNode : result) {
                         try {
                             EnterpriseChunkResult chunk = MAPPER.treeToValue(chunkNode, EnterpriseChunkResult.class);
-                            if (chunk != null && chunk.songs() != null) out.addAll(chunk.songs());
+                            if (chunk != null && chunk.songs() != null) {
+                                AudD.applyChunkPositions(chunk);
+                                out.addAll(chunk.songs());
+                            }
                         } catch (Exception e) {
                             throw new io.audd.errors.AudDSerializationError("Failed to decode EnterpriseChunkResult", resp.rawText());
                         }

src/main/java/io/audd/AudD.java

@@ -209,6 +209,7 @@ public List<EnterpriseMatch> recognizeEnterprise(Object source, EnterpriseOption
             try {
                 EnterpriseChunkResult chunk = MAPPER.treeToValue(chunkNode, EnterpriseChunkResult.class);
                 if (chunk != null && chunk.songs() != null) {
+                    applyChunkPositions(chunk);
                     out.addAll(chunk.songs());
                 }
             } catch (Exception e) {
@@ -299,6 +300,46 @@ static SourcePreparer.Prepared prepareSource(Object source) {
         }
     }
 
+    /**
+     * Parse an enterprise chunk offset ({@code "SS"}, {@code "MM:SS"},
+     * {@code "HH:MM:SS"}, or a plain number) into seconds. Returns null when the
+     * value is null/empty/unparseable. Never throws.
+     */
+    static Double offsetToSeconds(String o) {
+        if (o == null) return null;
+        String s = o.trim();
+        if (s.isEmpty()) return null;
+        try {
+            String[] parts = s.split(":");
+            if (parts.length == 1) {
+                return Double.parseDouble(parts[0].trim());
+            }
+            double total = 0;
+            for (String part : parts) {
+                total = total * 60 + Double.parseDouble(part.trim());
+            }
+            return total;
+        } catch (NumberFormatException e) {
+            return null;
+        }
+    }
+
+    /**
+     * Anchor each song in a chunk to its position in the user's file. The chunk
+     * offset is the fragment's start in the file; per-song start/end offsets are
+     * milliseconds within the fragment. Sets startSeconds/endSeconds when the
+     * chunk offset parses; leaves them null otherwise.
+     */
+    static void applyChunkPositions(EnterpriseChunkResult chunk) {
+        Double base = offsetToSeconds(chunk.offset());
+        if (base == null) return;
+        for (EnterpriseMatch song : chunk.songs()) {
+            if (song == null) continue;
+            song.startSeconds = base + (song.startOffset == null ? 0 : song.startOffset) / 1000.0;
+            song.endSeconds = base + (song.endOffset == null ? 0 : song.endOffset) / 1000.0;
+        }
+    }
+
     static Map<String, String> buildEnterpriseFields(EnterpriseOptions opts) {
         Map<String, String> fields = new HashMap<>();
         if (opts == null) return fields;

src/main/java/io/audd/EnterpriseOptions.java

@@ -58,7 +58,9 @@ public static final class Builder {
         private Integer limit;
         private Integer skipFirstSeconds;
         private Boolean useTimecode;
-        private Boolean accurateOffsets;
+        // Accurate offsets are on by default so startSeconds/endSeconds land on
+        // exact positions in the user's file. Pass accurateOffsets(false) to opt out.
+        private Boolean accurateOffsets = Boolean.TRUE;
         private Long timeoutMs;
         private Map<String, String> extraParameters;
 

src/main/java/io/audd/internal/UserAgent.java

@@ -2,7 +2,7 @@
 
 /** SDK identifier sent on every request. */
 public final class UserAgent {
-    public static final String SDK_VERSION = "1.5.13";
+    public static final String SDK_VERSION = "1.5.14";
 
     private UserAgent() {}
 

src/main/java/io/audd/models/EnterpriseMatch.java

@@ -23,6 +23,19 @@ public final class EnterpriseMatch extends ForwardCompatible {
     @JsonProperty("start_offset") public Integer startOffset;
     @JsonProperty("end_offset") public Integer endOffset;
 
+    /**
+     * Where this song starts in the user's file, in seconds. Computed from the
+     * chunk offset plus {@link #startOffset}; null when the chunk offset can't
+     * be parsed. Not a wire field.
+     */
+    @JsonIgnore public Double startSeconds;
+    /**
+     * Where this song ends in the user's file, in seconds. Computed from the
+     * chunk offset plus {@link #endOffset}; null when the chunk offset can't
+     * be parsed. Not a wire field.
+     */
+    @JsonIgnore public Double endSeconds;
+
     public Integer score() { return score; }
     public String timecode() { return timecode; }
     public String artist() { return artist; }
@@ -35,6 +48,8 @@ public final class EnterpriseMatch extends ForwardCompatible {
     public String songLink() { return songLink; }
     public Integer startOffset() { return startOffset; }
     public Integer endOffset() { return endOffset; }
+    public Double startSeconds() { return startSeconds; }
+    public Double endSeconds() { return endSeconds; }
 
     @JsonIgnore
     public String thumbnailUrl() {

src/test/java/io/audd/AudDTest.java

@@ -151,6 +151,36 @@ void recognizeEnterprise_flatList() throws Exception {
         assertThat(req.getBody().readUtf8()).contains("limit").contains("1");
     }
 
+    @Test
+    void recognizeEnterprise_anchorsSongsToFilePositions() throws Exception {
+        server.enqueue(new MockResponse().setBody(
+            "{\"status\":\"success\",\"result\":["
+            + "{\"songs\":[{\"score\":81,\"artist\":\"A\",\"title\":\"B\","
+            + "\"start_offset\":4200,\"end_offset\":11800}],\"offset\":\"00:01:00\"},"
+            + "{\"songs\":[{\"score\":70,\"artist\":\"C\",\"title\":\"D\","
+            + "\"start_offset\":1000,\"end_offset\":2000}]}]}"));
+
+        List<EnterpriseMatch> matches = audd.recognizeEnterprise("https://example.com/audio.mp3",
+            EnterpriseOptions.builder().limit(1).build());
+        assertThat(matches).hasSize(2);
+        // Chunk offset "00:01:00" = 60s; 60 + 4200/1000 = 64.2, 60 + 11800/1000 = 71.8.
+        assertThat(matches.get(0).startSeconds()).isEqualTo(64.2);
+        assertThat(matches.get(0).endSeconds()).isEqualTo(71.8);
+        // Chunk with absent offset -> positions stay null.
+        assertThat(matches.get(1).startSeconds()).isNull();
+        assertThat(matches.get(1).endSeconds()).isNull();
+    }
+
+    @Test
+    void recognizeEnterprise_defaultRequestSendsAccurateOffsets() throws Exception {
+        server.enqueue(new MockResponse().setBody("{\"status\":\"success\",\"result\":[]}"));
+
+        audd.recognizeEnterprise("https://example.com/audio.mp3");
+
+        RecordedRequest req = server.takeRequest();
+        assertThat(req.getBody().readUtf8()).contains("accurate_offsets").contains("true");
+    }
+
     @Test
     void close_isIdempotent() {
         audd.close();