@sorisdk/matcher 0.1.4 → 0.4.0

package/dist/generated/core.d.ts

@@ -12,6 +12,7 @@ export class WasmMatcherDatabase {
     loadPackBytesAppend(bytes: Uint8Array): void;
     constructor();
     removeEntry(name: string): void;
+    setEntryVariantMetadata(name: string, encoded_metadata: string): void;
     readonly length: number;
 }
 
@@ -19,7 +20,9 @@ export class WasmMatcherEngine {
     free(): void;
     [Symbol.dispose](): void;
     bestMatch(database: WasmMatcherDatabase, query: Uint8Array, config?: any | null): any;
+    bestMatchWithVariants(database: WasmMatcherDatabase, query: Uint8Array, pitch_query: any, config?: any | null, variant_config?: any | null): any;
     matchQuery(database: WasmMatcherDatabase, query: Uint8Array, config?: any | null): any;
+    matchQueryWithVariants(database: WasmMatcherDatabase, query: Uint8Array, pitch_query: any, config?: any | null, variant_config?: any | null): any;
     constructor();
     resetDistinctMatchState(): void;
 }

package/dist/generated/core_bg.js

@@ -102,6 +102,20 @@ export class WasmMatcherDatabase {
             throw takeFromExternrefTable0(ret[0]);
         }
     }
+    /**
+     * @param {string} name
+     * @param {string} encoded_metadata
+     */
+    setEntryVariantMetadata(name, encoded_metadata) {
+        const ptr0 = passStringToWasm0(name, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ptr1 = passStringToWasm0(encoded_metadata, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len1 = WASM_VECTOR_LEN;
+        const ret = wasm.wasmmatcherdatabase_setEntryVariantMetadata(this.__wbg_ptr, ptr0, len0, ptr1, len1);
+        if (ret[1]) {
+            throw takeFromExternrefTable0(ret[0]);
+        }
+    }
 }
 if (Symbol.dispose) WasmMatcherDatabase.prototype[Symbol.dispose] = WasmMatcherDatabase.prototype.free;
 
@@ -132,6 +146,24 @@ export class WasmMatcherEngine {
         }
         return takeFromExternrefTable0(ret[0]);
     }
+    /**
+     * @param {WasmMatcherDatabase} database
+     * @param {Uint8Array} query
+     * @param {any} pitch_query
+     * @param {any | null} [config]
+     * @param {any | null} [variant_config]
+     * @returns {any}
+     */
+    bestMatchWithVariants(database, query, pitch_query, config, variant_config) {
+        _assertClass(database, WasmMatcherDatabase);
+        const ptr0 = passArray8ToWasm0(query, wasm.__wbindgen_malloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.wasmmatcherengine_bestMatchWithVariants(this.__wbg_ptr, database.__wbg_ptr, ptr0, len0, pitch_query, isLikeNone(config) ? 0 : addToExternrefTable0(config), isLikeNone(variant_config) ? 0 : addToExternrefTable0(variant_config));
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return takeFromExternrefTable0(ret[0]);
+    }
     /**
      * @param {WasmMatcherDatabase} database
      * @param {Uint8Array} query
@@ -148,6 +180,24 @@ export class WasmMatcherEngine {
         }
         return takeFromExternrefTable0(ret[0]);
     }
+    /**
+     * @param {WasmMatcherDatabase} database
+     * @param {Uint8Array} query
+     * @param {any} pitch_query
+     * @param {any | null} [config]
+     * @param {any | null} [variant_config]
+     * @returns {any}
+     */
+    matchQueryWithVariants(database, query, pitch_query, config, variant_config) {
+        _assertClass(database, WasmMatcherDatabase);
+        const ptr0 = passArray8ToWasm0(query, wasm.__wbindgen_malloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.wasmmatcherengine_matchQueryWithVariants(this.__wbg_ptr, database.__wbg_ptr, ptr0, len0, pitch_query, isLikeNone(config) ? 0 : addToExternrefTable0(config), isLikeNone(variant_config) ? 0 : addToExternrefTable0(variant_config));
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return takeFromExternrefTable0(ret[0]);
+    }
     constructor() {
         const ret = wasm.wasmmatcherengine_new();
         this.__wbg_ptr = ret >>> 0;

package/dist/generated/core_bg.wasm.d.ts

@@ -12,8 +12,11 @@ export const wasmmatcherdatabase_loadPackBytes: (a: number, b: number, c: number
 export const wasmmatcherdatabase_loadPackBytesAppend: (a: number, b: number, c: number) => [number, number];
 export const wasmmatcherdatabase_new: () => number;
 export const wasmmatcherdatabase_removeEntry: (a: number, b: number, c: number) => [number, number];
+export const wasmmatcherdatabase_setEntryVariantMetadata: (a: number, b: number, c: number, d: number, e: number) => [number, number];
 export const wasmmatcherengine_bestMatch: (a: number, b: number, c: number, d: number, e: number) => [number, number, number];
+export const wasmmatcherengine_bestMatchWithVariants: (a: number, b: number, c: number, d: number, e: any, f: number, g: number) => [number, number, number];
 export const wasmmatcherengine_matchQuery: (a: number, b: number, c: number, d: number, e: number) => [number, number, number];
+export const wasmmatcherengine_matchQueryWithVariants: (a: number, b: number, c: number, d: number, e: any, f: number, g: number) => [number, number, number];
 export const wasmmatcherengine_new: () => number;
 export const wasmmatcherengine_resetDistinctMatchState: (a: number) => void;
 export const init_matcher_wasm: () => void;

package/dist/index.d.ts

@@ -8,6 +8,33 @@ interface MatchConfig {
     scoreThreshold?: number;
     gapThreshold?: number;
 }
+interface VariantMatchQuery {
+    estimatedPitchRatio?: number | null;
+    pitchConfidence?: number | null;
+}
+interface VariantMatchConfig {
+    minConfidence?: number;
+    defaultToleranceRatio?: number;
+    minRatioMargin?: number;
+    candidateLimit?: number;
+}
+type VariantDecisionStatus = "variant" | "variant_unknown" | "no_variant";
+interface VariantDecision {
+    status: VariantDecisionStatus;
+    reason?: string | null;
+    canonicalMaterialId?: string | null;
+    matchedEntryName?: string | null;
+    variantId?: string | null;
+    variantLabel?: string | null;
+    nominalRatio?: number | null;
+    estimatedPitchRatio?: number | null;
+    pitchConfidence?: number | null;
+    ratioError?: number | null;
+    pitchScore?: number | null;
+    toleranceMinRatio?: number | null;
+    toleranceMaxRatio?: number | null;
+    candidateCount: number;
+}
 interface EntryMetadata {
     id?: string | null;
     name?: string | null;
@@ -22,6 +49,10 @@ interface MatchResult {
     position: number;
     afpType: AudioFingerprintType;
 }
+interface VariantMatch {
+    matchResult: MatchResult;
+    variant: VariantDecision;
+}
 type PackSource = Uint8Array | ArrayBuffer | Blob | Response | Request | string | URL;
 type MatcherSessionEventMap = {
     ready: {
@@ -134,11 +165,14 @@ declare class MatcherSession {
     loadPack(source: PackSource): Promise<void>;
     addEntry(name: string, afpType: AudioFingerprintType, fingerprint: Uint8Array): Promise<void>;
     addOrReplace(name: string, afpType: AudioFingerprintType, fingerprint: Uint8Array, metadata?: EntryMetadata | null): Promise<void>;
+    setEntryVariantMetadata(name: string, encodedMetadata: string): Promise<void>;
     removeEntry(name: string): Promise<void>;
     clear(): Promise<void>;
     getEntryMetadata(name: string): Promise<EntryMetadata | null>;
     match(query: Uint8Array, config?: MatchConfig): Promise<MatchResult[]>;
     bestMatch(query: Uint8Array, config?: MatchConfig): Promise<MatchResult | null>;
+    matchWithVariants(query: Uint8Array, pitchQuery: VariantMatchQuery, config?: MatchConfig, variantConfig?: VariantMatchConfig): Promise<VariantMatch[]>;
+    bestMatchWithVariants(query: Uint8Array, pitchQuery: VariantMatchQuery, config?: MatchConfig, variantConfig?: VariantMatchConfig): Promise<VariantMatch | null>;
     destroy(): void;
     private bootstrap;
     private ensureLiveReady;
@@ -151,4 +185,4 @@ declare function __setMatcherWasmModuleForTests(moduleLike: unknown): void;
 declare function __setMatcherEmbeddedPackForTests(bytes: Uint8Array): void;
 declare function __resetMatcherWasmForTests(): void;
 
-export { AudioFingerprintType, type EntryMetadata, type InitMatcherOptions, type InitMatcherResult, type MatchConfig, type MatchResult, type MatcherEphemeralAuthOptions, type MatcherEphemeralAuthResult, type MatcherEphemeralKeyExchangeMetadata, type MatcherEphemeralKeyExchangeOptions, MatcherSession, type MatcherSessionEventMap, type MatcherSessionEventName, type MatcherSessionListener, type MatcherSessionOptions, type PackSource, __resetMatcherWasmForTests, __setMatcherEmbeddedPackForTests, __setMatcherWasmModuleForTests, initMatcher };
+export { AudioFingerprintType, type EntryMetadata, type InitMatcherOptions, type InitMatcherResult, type MatchConfig, type MatchResult, type MatcherEphemeralAuthOptions, type MatcherEphemeralAuthResult, type MatcherEphemeralKeyExchangeMetadata, type MatcherEphemeralKeyExchangeOptions, MatcherSession, type MatcherSessionEventMap, type MatcherSessionEventName, type MatcherSessionListener, type MatcherSessionOptions, type PackSource, type VariantDecision, type VariantDecisionStatus, type VariantMatch, type VariantMatchConfig, type VariantMatchQuery, __resetMatcherWasmForTests, __setMatcherEmbeddedPackForTests, __setMatcherWasmModuleForTests, initMatcher };

package/dist/index.js

@@ -358,6 +358,13 @@ var WrappedDatabase = class {
     }
     return normalizeEntryMetadata(raw);
   }
+  setEntryVariantMetadata(name, encodedMetadata) {
+    const fn = getCallable(this.inner, ["setEntryVariantMetadata", "set_entry_variant_metadata"]);
+    if (!fn) {
+      throw new Error("WASM database is missing setEntryVariantMetadata-compatible method");
+    }
+    fn.call(this.inner, name, encodedMetadata);
+  }
   destroy() {
     const fn = getCallable(this.inner, ["destroy", "free"]);
     if (fn) {
@@ -403,6 +410,31 @@ var WrappedMatcher = class {
     }
     return normalizeResult(raw);
   }
+  findMatchesWithVariants(database, query, pitchQuery, config, variantConfig) {
+    const fn = getCallable(this.inner, [
+      "findMatchesWithVariants",
+      "matchQueryWithVariants",
+      "match_query_with_variants"
+    ]);
+    if (!fn) {
+      throw new Error("WASM matcher is missing findMatchesWithVariants-compatible method");
+    }
+    const dbRecord = typeof database.raw === "function" ? database.raw() : database;
+    const rawResults = fn.call(this.inner, dbRecord, query, pitchQuery, config, variantConfig);
+    return normalizeVariantMatches(rawResults ?? []);
+  }
+  bestMatchWithVariants(database, query, pitchQuery, config, variantConfig) {
+    const fn = getCallable(this.inner, [
+      "bestMatchWithVariants",
+      "best_match_with_variants"
+    ]);
+    if (!fn) {
+      throw new Error("WASM matcher is missing bestMatchWithVariants-compatible method");
+    }
+    const dbRecord = typeof database.raw === "function" ? database.raw() : database;
+    const raw = fn.call(this.inner, dbRecord, query, pitchQuery, config, variantConfig);
+    return raw && typeof raw === "object" ? normalizeVariantMatch(raw) : null;
+  }
   resetDistinctMatchState() {
     const fn = getCallable(this.inner, ["resetDistinctMatchState", "reset_distinct_match_state"]);
     fn?.call(this.inner);
@@ -423,7 +455,35 @@ function normalizeResult(raw) {
     afpType
   };
 }
+function normalizeVariantMatch(raw) {
+  const rawMatch = raw.matchResult ?? raw.match;
+  const rawVariant = raw.variant ?? {};
+  return {
+    matchResult: normalizeResult(rawMatch),
+    variant: {
+      ...rawVariant,
+      status: String(rawVariant.status),
+      candidateCount: Number(rawVariant.candidateCount ?? 0)
+    }
+  };
+}
+function isMapLike(raw) {
+  return raw instanceof Map || Object.prototype.toString.call(raw) === "[object Map]" && typeof raw.entries === "function";
+}
+function toEntryMetadataRecord(raw) {
+  if (isMapLike(raw)) {
+    const entries = [];
+    for (const [key, value] of raw.entries()) {
+      if (typeof key === "string") {
+        entries.push([key, value]);
+      }
+    }
+    return Object.fromEntries(entries);
+  }
+  return raw;
+}
 function normalizeEntryMetadata(raw) {
+  const metadata = toEntryMetadataRecord(raw);
   const {
     _id: legacyId,
     id,
@@ -433,7 +493,7 @@ function normalizeEntryMetadata(raw) {
     name,
     image,
     ...rest
-  } = raw;
+  } = metadata;
   return {
     ...rest,
     ...id !== void 0 || legacyId !== void 0 ? { id: String(id ?? legacyId) } : {},
@@ -446,6 +506,9 @@ function normalizeEntryMetadata(raw) {
 function normalizeResults(rawResults) {
   return rawResults.filter((item) => typeof item === "object" && item !== null).map((item) => normalizeResult(item));
 }
+function normalizeVariantMatches(rawResults) {
+  return rawResults.filter((item) => typeof item === "object" && item !== null).map((item) => normalizeVariantMatch(item));
+}
 function isInternallyDuplicatedBestMatch(result) {
   return Boolean(
     result && typeof result === "object" && result[INTERNAL_DUPLICATE_MATCH_FLAG] === true
@@ -603,6 +666,16 @@ var MatcherSession = class {
       handleError(this.events, "addOrReplace", error);
     }
   }
+  async setEntryVariantMetadata(name, encodedMetadata) {
+    try {
+      await this.ensureLiveReady();
+      this.databaseOrThrow().setEntryVariantMetadata(name, encodedMetadata);
+      this.distinctMatchDeduper.reset();
+      this.matcher?.resetDistinctMatchState?.();
+    } catch (error) {
+      handleError(this.events, "setEntryVariantMetadata", error);
+    }
+  }
   async removeEntry(name) {
     try {
       await this.ensureLiveReady();
@@ -658,6 +731,50 @@ var MatcherSession = class {
       handleError(this.events, "bestMatch", error);
     }
   }
+  async matchWithVariants(query, pitchQuery, config, variantConfig) {
+    try {
+      await this.ensureLiveReady();
+      const safeQuery = toUint8ArrayCopy(query);
+      this.events.emit("querystart", { queryByteLength: safeQuery.byteLength });
+      const results = this.matcherOrThrow().findMatchesWithVariants(
+        this.databaseOrThrow(),
+        safeQuery,
+        pitchQuery,
+        config,
+        variantConfig
+      );
+      this.emitDistinctMatchEvent(
+        results[0]?.matchResult ?? null,
+        safeQuery.byteLength,
+        results.map((result) => result.matchResult)
+      );
+      return results;
+    } catch (error) {
+      handleError(this.events, "matchWithVariants", error);
+    }
+  }
+  async bestMatchWithVariants(query, pitchQuery, config, variantConfig) {
+    try {
+      await this.ensureLiveReady();
+      const safeQuery = toUint8ArrayCopy(query);
+      this.events.emit("querystart", { queryByteLength: safeQuery.byteLength });
+      const best = this.matcherOrThrow().bestMatchWithVariants(
+        this.databaseOrThrow(),
+        safeQuery,
+        pitchQuery,
+        config,
+        variantConfig
+      );
+      this.emitDistinctMatchEvent(
+        best?.matchResult ?? null,
+        safeQuery.byteLength,
+        best ? [best.matchResult] : []
+      );
+      return best;
+    } catch (error) {
+      handleError(this.events, "bestMatchWithVariants", error);
+    }
+  }
   destroy() {
     if (this.destroyed) {
       return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sorisdk/matcher",
-  "version": "0.1.4",
+  "version": "0.4.0",
   "description": "Browser WASM SDK for audio fingerprint matching",
   "type": "module",
   "main": "./dist/index.js",