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

@@ -101,7 +101,7 @@ print(result.preview_url())          # first preview across requested providers,
 
 Valid `return_metadata` values: `apple_music`, `spotify`, `deezer`, `napster`, `musicbrainz`. Attributes are `None` when not requested.
 
-`EnterpriseMatch` (returned by `recognize_enterprise`) carries the same core tags plus `score`, `start_offset`, `end_offset`, `isrc`, `upc`. Access to `isrc`, `upc`, and `score` requires a Startup plan or higher — [contact us](mailto:api@audd.io) for enterprise features.
+`EnterpriseMatch` (returned by `recognize_enterprise`) carries the same core tags plus `score`, `isrc`, `upc`, and — the fields you need for a long file — **`start_seconds` and `end_seconds`**: where this song plays in your file, in seconds (e.g. `64.2` to `71.8`). Feed them straight to a player or `ffmpeg`. They're computed for you while parsing the chunked enterprise response, and `recognize_enterprise` requests accurate offsets by default so they're precise to the sub-second. (`start_offset`/`end_offset` are the raw millisecond positions *within* AudD's internal 12-second scan fragment that these are derived from; you rarely need them directly.) Access to `isrc`, `upc`, and `score` requires a Startup plan or higher — [contact us](mailto:api@audd.io) for enterprise features.
 
 For ad-hoc inspection during development, `result.pretty_print()` dumps the full state — typed fields plus everything in `model_extra` — as indented JSON.
 

src/audd/_version.py

@@ -1,3 +1,3 @@
 """Single source of truth for the package version. Hatch reads this."""
 
-__version__ = "1.5.11"
+__version__ = "1.5.12"

src/audd/client.py

@@ -25,7 +25,12 @@
     AudDServerError,
     raise_from_error_response,
 )
-from audd.models import EnterpriseChunkResult, EnterpriseMatch, RecognitionResult
+from audd.models import (
+    EnterpriseChunkResult,
+    EnterpriseMatch,
+    RecognitionResult,
+    _offset_to_seconds,
+)
 
 API_BASE = "https://api.audd.io"
 ENTERPRISE_BASE = "https://enterprise.audd.io"
@@ -208,6 +213,14 @@ def _decode_enterprise(resp: HTTPResponse) -> list[EnterpriseMatch]:
             chunk = EnterpriseChunkResult.model_validate(chunk_dict)
         except Exception:  # degrade, never raise on response parse
             continue
+        # The file position lives on the chunk; the API drops it once we flatten
+        # to a song list. Resolve each match's absolute position in the file
+        # here (chunk offset + in-fragment offset) so callers don't lose it.
+        base = _offset_to_seconds(chunk.offset)
+        if base is not None:
+            for song in chunk.songs:
+                song.start_seconds = base + (song.start_offset or 0) / 1000
+                song.end_seconds = base + (song.end_offset or 0) / 1000
         out.extend(chunk.songs)
     return out
 
@@ -411,7 +424,7 @@ def recognize_enterprise(
         limit: int | None = None,
         skip_first_seconds: int | None = None,
         use_timecode: bool | None = None,
-        accurate_offsets: bool | None = None,
+        accurate_offsets: bool = True,
         timeout: float | None = None,
         extra_parameters: dict[str, str] | None = None,
     ) -> list[EnterpriseMatch]:
@@ -603,7 +616,7 @@ async def recognize_enterprise(
         limit: int | None = None,
         skip_first_seconds: int | None = None,
         use_timecode: bool | None = None,
-        accurate_offsets: bool | None = None,
+        accurate_offsets: bool = True,
         timeout: float | None = None,
         extra_parameters: dict[str, str] | None = None,
     ) -> list[EnterpriseMatch]:

src/audd/models.py

@@ -37,6 +37,24 @@ class _Forward(BaseModel):
     model_config = ConfigDict(extra="allow", populate_by_name=True, str_strip_whitespace=False)
 
 
+def _offset_to_seconds(offset: str | None) -> float | None:
+    """Parse a chunk offset (``"SS"``, ``"MM:SS"``, or ``"HH:MM:SS"``, or a
+    bare number) into seconds. Returns ``None`` for missing/unparseable input —
+    response parsing never raises on a malformed field."""
+    if offset is None:
+        return None
+    text = str(offset).strip()
+    if not text:
+        return None
+    try:
+        total = 0.0
+        for part in text.split(":"):
+            total = total * 60 + float(part)
+        return total
+    except ValueError:
+        return None
+
+
 def _coerce_model_list(value: Any, model: type[BaseModel]) -> list[Any]:
     """Best-effort list-of-model coercion that never raises.
 
@@ -295,6 +313,13 @@ class EnterpriseMatch(_Forward):
     song_link: str | None = None
     start_offset: int | None = None
     end_offset: int | None = None
+    start_seconds: float | None = None
+    """Where this song starts in your file, in seconds (e.g. ``64.2``). Computed
+    by the client from the fragment's file position and the in-fragment offset.
+    ``None`` if the position can't be determined. ``start_offset``/``end_offset``
+    are the raw, fragment-relative millisecond values behind this."""
+    end_seconds: float | None = None
+    """Where this song ends in your file, in seconds. ``None`` if unknown."""
 
     def __repr__(self) -> str:
         parts: list[str] = []

tests/unit/test_client.py

@@ -140,6 +140,43 @@ def test_recognize_enterprise_returns_list_of_matches() -> None:
     assert matches[0].artist == "X"
 
 
+@respx.mock
+def test_recognize_enterprise_anchors_offsets_to_file() -> None:
+    """The flattened matches expose file-absolute start_seconds/end_seconds,
+    derived from the chunk offset + the in-fragment start_offset/end_offset.
+    The chunk offset is the only source of file position and must not be lost."""
+    respx.post("https://enterprise.audd.io/").mock(
+        return_value=httpx.Response(200, json={
+            "status": "success",
+            "result": [
+                {"offset": "00:01:00", "songs": [{
+                    "artist": "A", "title": "T",
+                    "start_offset": 4200, "end_offset": 11800,
+                }]},
+                {"offset": None, "songs": [{"artist": "B", "title": "U"}]},
+            ],
+        }),
+    )
+    matches = AudD(api_token="t-test").recognize_enterprise("https://example.mp3", limit=2)
+    assert matches[0].start_seconds == 64.2   # 60 + 4200/1000
+    assert matches[0].end_seconds == 71.8     # 60 + 11800/1000
+    assert matches[1].start_seconds is None    # chunk offset absent → unknown
+    assert matches[1].end_seconds is None
+
+
+@respx.mock
+def test_recognize_enterprise_requests_accurate_offsets_by_default() -> None:
+    captured: dict[str, str] = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        captured["body"] = request.read().decode()
+        return httpx.Response(200, json={"status": "success", "result": []})
+
+    respx.post("https://enterprise.audd.io/").mock(side_effect=handler)
+    AudD(api_token="t-test").recognize_enterprise("https://example.mp3", limit=1)
+    assert "accurate_offsets=true" in captured["body"]
+
+
 @respx.mock
 def test_recognize_enterprise_song_without_score_parses() -> None:
     """Enterprise endpoint legitimately returns songs with no score (and no