@audd/sdk 1.5.9 → 1.5.11

package/README.md

@@ -85,7 +85,7 @@ console.log(song.releaseDate, song.label, song.timecode);
 // AudD's universal song page — links into every provider
 console.log(song.songLink);
 
-// Helpers — driven off songLink, work without any `return` opt-in
+// Helpers — driven off songLink, work without any `returnMetadata` opt-in
 console.log(song.thumbnailUrl);             // cover-art image, or null
 console.log(song.streamingUrl("spotify"));  // direct or lis.tn redirect
 console.log(song.streamingUrls());          // map of provider -> URL
@@ -107,21 +107,21 @@ Valid `returnMetadata` values: `apple_music`, `spotify`, `deezer`, `napster`,
 `musicbrainz`. Blocks are `undefined` when not requested.
 
 `streamingUrl(provider)` prefers the direct provider URL when you
-requested that block via `return`, then falls back to the lis.tn redirect
+requested that block via `returnMetadata`, then falls back to the lis.tn redirect
 when `songLink` is on `lis.tn`. YouTube has only the redirect path.
 
 ## Reading additional metadata
 
 Every model carries an `extras` map with any server-side fields outside
 the typed surface, plus a `rawResponse` of the full unparsed JSON. Use
-`extras` to read undocumented or beta fields:
+`extras` to read fields outside the typed surface:
 
 ```ts
 console.log(song.extras);       // any non-typed top-level fields
 console.log(song.rawResponse);  // the whole result object as the server returned it
 ```
 
-For the **request** side, every call accepts an `extraParameters` map for additional form fields the typed options don't cover — undocumented parameters or beta features:
+For the **request** side, every call accepts an `extraParameters` map for additional form fields the typed options don't cover:
 
 ```ts
 await audd.recognize(url, {
@@ -145,10 +145,15 @@ for (const m of matches) {
 }
 ```
 
-`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.
+`EnterpriseMatch` carries the same core tags plus `score`, `startSeconds`,
+`endSeconds`, `startOffset`, `endOffset`, `isrc`, `upc`. `startSeconds` and
+`endSeconds` are where this song plays in your file, in seconds (e.g. 64.2 to
+71.8) — feed straight to a player or ffmpeg; computed while parsing the chunked
+response, and `recognizeEnterprise` requests accurate offsets by default so
+they're precise. `startOffset`/`endOffset` are the raw millisecond positions
+within AudD's internal 12-second scan fragment behind them. Access to `isrc`,
+`upc`, and `score` requires a Startup plan or higher — [contact
+us](mailto:api@audd.io) for enterprise features.
 
 The default per-call timeout is **1 hour** for this endpoint (60s for
 standard recognition); override with `timeoutMs`.

package/dist/index.cjs

@@ -285,6 +285,20 @@ function asNumber(v) {
 function asBoolean(v) {
   return typeof v === "boolean" ? v : void 0;
 }
+function parseOffsetToSeconds(o) {
+  if (o === void 0 || o === null) return void 0;
+  if (typeof o === "number") return Number.isFinite(o) ? o : void 0;
+  const t = String(o).trim();
+  if (t === "") return void 0;
+  let total = 0;
+  for (const part of t.split(":")) {
+    if (part.trim() === "") return void 0;
+    const n = Number(part);
+    if (!Number.isFinite(n)) return void 0;
+    total = total * 60 + n;
+  }
+  return total;
+}
 var STREAMING_PROVIDERS = [
   "spotify",
   "apple_music",
@@ -366,9 +380,6 @@ var RECOGNITION_KEYS = [
 function parseRecognitionResult(raw) {
   const r = requireObject(raw, "RecognitionResult");
   const timecode = asString(r.timecode);
-  if (timecode === void 0) {
-    throw new TypeError("RecognitionResult: timecode missing or not string");
-  }
   const audioId = asNumber(r.audio_id);
   const artist = asString(r.artist);
   const title = asString(r.title);
@@ -437,14 +448,14 @@ var ENTERPRISE_MATCH_KEYS = [
   "upc",
   "song_link",
   "start_offset",
-  "end_offset"
+  "end_offset",
+  "start_seconds",
+  "end_seconds"
 ];
 function parseEnterpriseMatch(raw) {
   const r = requireObject(raw, "EnterpriseMatch");
   const score = asNumber(r.score);
   const timecode = asString(r.timecode);
-  if (score === void 0) throw new TypeError("EnterpriseMatch: score not number");
-  if (timecode === void 0) throw new TypeError("EnterpriseMatch: timecode not string");
   const songLink = asString(r.song_link);
   return {
     score,
@@ -459,6 +470,8 @@ function parseEnterpriseMatch(raw) {
     songLink,
     startOffset: asNumber(r.start_offset),
     endOffset: asNumber(r.end_offset),
+    startSeconds: void 0,
+    endSeconds: void 0,
     extras: pickExtras(r, ENTERPRISE_MATCH_KEYS),
     rawResponse: r,
     streamingUrl(provider) {
@@ -491,14 +504,19 @@ function parseEnterpriseMatch(raw) {
 var ENTERPRISE_CHUNK_KEYS = ["songs", "offset"];
 function parseEnterpriseChunkResult(raw) {
   const r = requireObject(raw, "EnterpriseChunkResult");
-  const songsRaw = r.songs;
-  if (!Array.isArray(songsRaw)) {
-    throw new TypeError("EnterpriseChunkResult: songs not array");
-  }
+  const songsRaw = Array.isArray(r.songs) ? r.songs : [];
   const offset = asString(r.offset);
-  if (offset === void 0) throw new TypeError("EnterpriseChunkResult: offset not string");
+  const base = parseOffsetToSeconds(r.offset);
+  const songs = songsRaw.map((s) => {
+    const match = parseEnterpriseMatch(s);
+    if (base !== void 0) {
+      match.startSeconds = base + (match.startOffset ?? 0) / 1e3;
+      match.endSeconds = base + (match.endOffset ?? 0) / 1e3;
+    }
+    return match;
+  });
   return {
-    songs: songsRaw.map(parseEnterpriseMatch),
+    songs,
     offset,
     extras: pickExtras(r, ENTERPRISE_CHUNK_KEYS),
     rawResponse: r
@@ -510,9 +528,6 @@ function parseStream(raw) {
   const radioId = asNumber(r.radio_id);
   const url = asString(r.url);
   const streamRunning = asBoolean(r.stream_running);
-  if (radioId === void 0) throw new TypeError("Stream: radio_id not number");
-  if (url === void 0) throw new TypeError("Stream: url not string");
-  if (streamRunning === void 0) throw new TypeError("Stream: stream_running not boolean");
   return {
     radioId,
     url,
@@ -543,9 +558,6 @@ function parseStreamCallbackSong(raw) {
   const artist = asString(r.artist);
   const title = asString(r.title);
   const score = asNumber(r.score);
-  if (artist === void 0) throw new TypeError("StreamCallbackSong: artist not string");
-  if (title === void 0) throw new TypeError("StreamCallbackSong: title not string");
-  if (score === void 0) throw new TypeError("StreamCallbackSong: score not number");
   const musicbrainz = Array.isArray(r.musicbrainz) ? r.musicbrainz.filter((x) => asObject(x) !== void 0) : void 0;
   return {
     artist,
@@ -574,13 +586,9 @@ var STREAM_CALLBACK_MATCH_KEYS = [
 function parseStreamCallbackMatch(raw) {
   const r = requireObject(raw, "StreamCallbackMatch");
   const radioId = asNumber(r.radio_id);
-  if (radioId === void 0) throw new TypeError("StreamCallbackMatch: radio_id not number");
-  const resultsRaw = r.results;
-  if (!Array.isArray(resultsRaw)) throw new TypeError("StreamCallbackMatch: results not array");
-  if (resultsRaw.length === 0) throw new TypeError("StreamCallbackMatch: results is empty");
-  const songs = resultsRaw.map(parseStreamCallbackSong);
+  const resultsRaw = Array.isArray(r.results) ? r.results : [];
+  const songs = resultsRaw.filter((x) => asObject(x) !== void 0).map(parseStreamCallbackSong);
   const [first, ...rest] = songs;
-  if (first === void 0) throw new TypeError("StreamCallbackMatch: results is empty");
   return {
     radioId,
     timestamp: asString(r.timestamp),
@@ -600,14 +608,8 @@ var STREAM_CALLBACK_NOTIFICATION_KEYS = [
 function parseStreamCallbackNotification(raw) {
   const r = requireObject(raw, "StreamCallbackNotification");
   const radioId = asNumber(r.radio_id);
-  if (radioId === void 0)
-    throw new TypeError("StreamCallbackNotification: radio_id not number");
   const code = asNumber(r.notification_code);
-  if (code === void 0)
-    throw new TypeError("StreamCallbackNotification: notification_code not number");
   const message = asString(r.notification_message);
-  if (message === void 0)
-    throw new TypeError("StreamCallbackNotification: notification_message not string");
   return {
     radioId,
     streamRunning: asBoolean(r.stream_running),
@@ -631,8 +633,6 @@ function parseLyricsResult(raw) {
   const r = requireObject(raw, "LyricsResult");
   const artist = asString(r.artist);
   const title = asString(r.title);
-  if (artist === void 0) throw new TypeError("LyricsResult: artist not string");
-  if (title === void 0) throw new TypeError("LyricsResult: title not string");
   return {
     artist,
     title,
@@ -1403,8 +1403,8 @@ function buildEnterpriseFields(opts) {
   if (opts.skipFirstSeconds !== void 0)
     fields["skip_first_seconds"] = String(opts.skipFirstSeconds);
   if (opts.useTimecode !== void 0) fields["use_timecode"] = opts.useTimecode ? "true" : "false";
-  if (opts.accurateOffsets !== void 0)
-    fields["accurate_offsets"] = opts.accurateOffsets ? "true" : "false";
+  const accurate = opts.accurateOffsets ?? true;
+  fields["accurate_offsets"] = accurate ? "true" : "false";
   return fields;
 }
 function isDeprecationPassThrough(body) {