@sorisdk/web-audio 0.6.8 → 0.6.9

package/README.md

@@ -52,7 +52,7 @@ configuration, or Node-based asset server is required:
 ```html
 <script type="module">
   import { AudioRecognizer } from
-    "https://cdn.iplateia.com/web/sorisdk/v0.6.8/sori-web-audio.mjs";
+    "https://cdn.iplateia.com/web/sorisdk/v0.6.9/sori-web-audio.mjs";
 
   const recognizer = new AudioRecognizer({
     appId: "YOUR_APP_ID",
@@ -79,7 +79,7 @@ configuration, or Node-based asset server is required:
 ```
 
 Static URL imports are valid inside `<script type="module">`. Dynamic
-`await import("https://cdn.iplateia.com/web/sorisdk/v0.6.8/sori-web-audio.mjs")`
+`await import("https://cdn.iplateia.com/web/sorisdk/v0.6.9/sori-web-audio.mjs")`
 is an optional alternative when the SDK should be loaded conditionally.
 
 Pin an exact version in production. Do not construct a mutable `latest` URL.
@@ -149,7 +149,7 @@ An import map can give the standalone URL the npm package name:
 <script type="importmap">
 {
   "imports": {
-    "@sorisdk/web-audio": "https://cdn.iplateia.com/web/sorisdk/v0.6.8/sori-web-audio.mjs"
+    "@sorisdk/web-audio": "https://cdn.iplateia.com/web/sorisdk/v0.6.9/sori-web-audio.mjs"
   }
 }
 </script>
@@ -219,6 +219,22 @@ await recognizer.stop();
 await recognizer.destroy();
 ```
 
+## Continuous recognition
+
+Continuous observations of one material emit one public `match`. An intervening
+material (A → B → A), two consecutive fingerprint no-match results, or a gap
+greater than 30 seconds since the last successful observation starts a new run.
+The next successful A is delivered immediately. A single fingerprint miss or
+marker miss does not split a run. Successful observations renew continuity even
+when no public `match` event is emitted, in both marker modes.
+
+The 30-second boundary also covers capture interruptions with no queries; it is
+checked when querying resumes. Two consecutive misses can confirm a boundary
+sooner. `nomatch` is emitted on an observed boundary, rather than by an idle
+timer. Sequential stop/start, failed-start cleanup, and successful database
+replacement or mutation clear recognition and capture state. Pending queries
+from an older capture cannot restore suppression in the new capture.
+
 ## Activity refinement
 
 The default `AudioRecognizer` activity reporter represents one ordered,
@@ -242,7 +258,7 @@ server activity:
 7. The refined `campaign` event keeps the same non-empty `activityId`, so an
    application can replace the earlier campaign row deterministically.
 
-A consecutive match for the same material and fingerprint type renews a local
+A successful observation for the same material and fingerprint type renews a local
 30-second continuity lease without another POST or campaign event. That local
 lease can keep one segment alive beyond the initial server refinement window,
 but it never extends the original PUT deadline. A marker confirmed anywhere
@@ -264,7 +280,7 @@ refine the earlier A. Marker evidence arriving after a segment is sealed is
 ignored for that segment; create or PUT transport that already started may
 finish under the existing capture, deadline, and cancellation guards.
 
-Ordinary fingerprint `match` events remain independently observable and never
+Fingerprint `match` events follow the continuous-run rules above and never
 contain the private detector result. Public `audiomarker` delivery is sourced
 only from a completed activity response. It is independent from campaign
 availability but does prove that the server resolved the marker id and name.

package/dist/index.js

@@ -354,6 +354,9 @@ var FingerprintMatchWindow = class {
   }
 };
 
+// src/activity-refinement.ts
+import { MATCH_CONTINUITY_GAP_MS } from "@sorisdk/matcher";
+
 // src/detected-match.ts
 function toPublicDetectedMatch(match) {
   const { audioMarker: _internalAudioMarker, ...publicMatch } = match;
@@ -665,7 +668,6 @@ async function refineMatchedMaterialActivity(reporter, match, context, isActive
 
 // src/activity-refinement.ts
 var ACTIVITY_REFINEMENT_WINDOW_MS = 3e4;
-var ACTIVITY_CONTINUITY_GAP_MS = 3e4;
 var DEFAULT_MAX_REFINEMENT_ATTEMPTS = 2;
 var MAX_REFINEMENT_ATTEMPTS = 10;
 function normalizeError(error) {
@@ -700,11 +702,14 @@ var ActivityRefinementCoordinator = class {
       this.registeredRequests.add(requestId);
     }
   }
-  report(recognitionId, match, captureGeneration, requestId = null) {
+  report(recognitionId, match, captureGeneration, requestId = null, distinct = true) {
     const coordinatorGeneration = this.generation;
     const markerSegment = this.resolveMarkerSegment(match, captureGeneration);
     const hasMarker = typeof match.audioMarker?.code === "string" && match.audioMarker.code.length > 0;
     const refinement = this.reporter.refinement;
+    if (!refinement && !distinct) {
+      return;
+    }
     const requestCanRefine = requestId !== null && !this.settledRequests.has(requestId);
     const pendingMarker = requestId === null ? void 0 : this.pendingMarkers.get(requestId);
     if (requestId !== null) {
@@ -1054,12 +1059,12 @@ var ActivityRefinementCoordinator = class {
     }
   }
   isContinuousMatch(lifecycle, match, captureGeneration, now) {
-    return !lifecycle.sealed && this.activeLifecycle === lifecycle && lifecycle.captureGeneration === captureGeneration && lifecycle.match.name === match.name && lifecycle.match.afpType === match.afpType && this.isTransportActive(lifecycle) && now - lifecycle.lastObservedAt <= ACTIVITY_CONTINUITY_GAP_MS;
+    return !lifecycle.sealed && this.activeLifecycle === lifecycle && lifecycle.captureGeneration === captureGeneration && lifecycle.match.name === match.name && lifecycle.match.afpType === match.afpType && this.isTransportActive(lifecycle) && now - lifecycle.lastObservedAt <= MATCH_CONTINUITY_GAP_MS;
   }
   resolveMarkerSegment(match, captureGeneration) {
     const now = this.now();
     const active = this.activeMarkerSegment;
-    if (active && active.captureGeneration === captureGeneration && active.materialName === match.name && active.afpType === match.afpType && now - active.lastObservedAt <= ACTIVITY_CONTINUITY_GAP_MS) {
+    if (active && active.captureGeneration === captureGeneration && active.materialName === match.name && active.afpType === match.afpType && now - active.lastObservedAt <= MATCH_CONTINUITY_GAP_MS) {
       active.lastObservedAt = now;
       return active;
     }
@@ -1088,14 +1093,14 @@ var ActivityRefinementCoordinator = class {
     if (lifecycle.continuityTimer) {
       clearTimeout(lifecycle.continuityTimer);
     }
-    const remainingMs = lifecycle.lastObservedAt + ACTIVITY_CONTINUITY_GAP_MS - this.now();
+    const remainingMs = lifecycle.lastObservedAt + MATCH_CONTINUITY_GAP_MS - this.now();
     lifecycle.continuityTimer = setTimeout(() => {
       lifecycle.continuityTimer = null;
       if (this.activeLifecycle !== lifecycle || lifecycle.sealed) {
         return;
       }
       const now = this.now();
-      if (now - lifecycle.lastObservedAt <= ACTIVITY_CONTINUITY_GAP_MS) {
+      if (now - lifecycle.lastObservedAt <= MATCH_CONTINUITY_GAP_MS) {
         this.scheduleContinuityExpiry(lifecycle);
         return;
       }
@@ -1381,6 +1386,7 @@ var MicrophoneMatcher = class {
       }
       await this.matcherSession.loadPack(target);
       this.loadedPack = true;
+      await this.resetCaptureState();
     } catch (error) {
       emitAndThrow(this.events, "loadPack", error);
     }
@@ -1422,6 +1428,7 @@ var MicrophoneMatcher = class {
       this.ensureNotDestroyed();
       await this.prepare();
       await this.matcherSession.addEntry(name, afpType, fingerprint);
+      await this.resetCaptureState();
     } catch (error) {
       emitAndThrow(this.events, "addEntry", error);
     }
@@ -1431,6 +1438,7 @@ var MicrophoneMatcher = class {
       this.ensureNotDestroyed();
       await this.prepare();
       await this.matcherSession.addOrReplace(name, afpType, fingerprint);
+      await this.resetCaptureState();
     } catch (error) {
       emitAndThrow(this.events, "addOrReplace", error);
     }
@@ -1439,9 +1447,8 @@ var MicrophoneMatcher = class {
     try {
       this.ensureNotDestroyed();
       await this.prepare();
-      this.activityRefinement?.reset();
-      this.matchWindowOrThrow().reset();
       await this.matcherSession.clear();
+      await this.resetCaptureState();
     } catch (error) {
       emitAndThrow(this.events, "clear", error);
     }
@@ -1486,9 +1493,9 @@ var MicrophoneMatcher = class {
         return;
       }
       this.running = false;
+      await this.resetCaptureState();
       await this.graphController?.stop();
       this.graphController = null;
-      await this.resetCaptureState();
       if (this.stopTracksOnStop) {
         this.stream?.getTracks().forEach((track) => track.stop());
       }
@@ -1578,15 +1585,18 @@ var MicrophoneMatcher = class {
         let matchedBest = null;
         let shouldEmitNoMatch = false;
         let audioMarkerRequestId = null;
-        let associatedActivity = false;
+        let observedBest = null;
         const handleMatch = (event) => {
-          if (!event.best) {
+          if (!event.best || captureGeneration !== this.captureGeneration || !this.running) {
             return;
           }
           matchedBest = event.best;
           shouldEmitNoMatch = false;
         };
         const handleNoMatch = () => {
+          if (captureGeneration !== this.captureGeneration || !this.running) {
+            return;
+          }
           matchedBest = null;
           shouldEmitNoMatch = true;
         };
@@ -1596,7 +1606,6 @@ var MicrophoneMatcher = class {
           this.diagnostics.matchRequests += 1;
           const bestMatchPromise = this.matcherSession.bestMatch(query, this.matchConfig());
           audioMarkerRequestId = this.beginAudioMarkerDetection(captureGeneration);
-          let observedBest;
           try {
             observedBest = await bestMatchPromise;
           } catch (error) {
@@ -1605,15 +1614,10 @@ var MicrophoneMatcher = class {
             }
             throw error;
           }
-          if (audioMarkerRequestId !== null) {
-            associatedActivity = this.activityRefinement?.associate(
-              audioMarkerRequestId,
-              observedBest,
-              captureGeneration
-            ) ?? false;
+          if (captureGeneration !== this.captureGeneration || !this.running) {
+            return;
           }
-          const distinctBest = this.withAudioMarkerForRequest(matchedBest, audioMarkerRequestId);
-          matchedBest = distinctBest;
+          observedBest = this.withAudioMarkerForRequest(observedBest, audioMarkerRequestId);
         } finally {
           this.matcherSession.off("match", handleMatch);
           this.matcherSession.off("nomatch", handleNoMatch);
@@ -1621,33 +1625,46 @@ var MicrophoneMatcher = class {
         if (captureGeneration !== this.captureGeneration || !this.running) {
           return;
         }
-        if (matchedBest) {
-          this.events.emit("match", { best: toPublicDetectedMatch(matchedBest) });
+        if (observedBest) {
+          const distinct = matchedBest !== null;
+          if (distinct) {
+            this.activityRefinement?.clearActive(captureGeneration);
+            this.events.emit("match", { best: toPublicDetectedMatch(observedBest) });
+          }
+          if (captureGeneration !== this.captureGeneration || !this.running) {
+            return;
+          }
           this.activityRecognitionId += 1;
           this.reportCampaign(
             this.activityRecognitionId,
-            matchedBest,
+            observedBest,
             captureGeneration,
-            audioMarkerRequestId
+            audioMarkerRequestId,
+            distinct
           );
-        } else if (shouldEmitNoMatch) {
-          if (audioMarkerRequestId !== null && !associatedActivity) {
+        } else {
+          if (audioMarkerRequestId !== null) {
             this.activityRefinement?.discardRequest(audioMarkerRequestId);
           }
-          this.activityRefinement?.clearActive(captureGeneration);
-          this.events.emit("nomatch", {});
-        } else if (audioMarkerRequestId !== null && !associatedActivity) {
-          this.activityRefinement?.discardRequest(audioMarkerRequestId);
+          if (shouldEmitNoMatch) {
+            this.activityRefinement?.clearActive(captureGeneration);
+            this.events.emit("nomatch", {});
+          }
         }
       } while (this.pendingMatch || this.matchWindowOrThrow().hasReadyQuery());
     } catch (error) {
-      emitError(this.events, "match", error);
+      if (captureGeneration === this.captureGeneration && this.running) {
+        emitError(this.events, "match", error);
+      }
     } finally {
-      this.matchInFlight = false;
+      if (captureGeneration === this.captureGeneration) {
+        this.matchInFlight = false;
+      }
     }
   }
   async resetCaptureState() {
     this.captureGeneration += 1;
+    this.matcherSession.resetRecognitionState();
     this.pendingMatch = false;
     this.matchInFlight = false;
     this.pcmBuffer = new Float32Array(0);
@@ -1657,7 +1674,7 @@ var MicrophoneMatcher = class {
     this.latestAudioMarkerDetection = null;
     this.audioMarkerRequestId += 1;
     this.activityRefinement?.reset();
-    this.matchWindowOrThrow().reset();
+    this.matchWindow?.reset();
     await this.extractor?.reset();
   }
   appendAudioMarkerSamples(samples) {
@@ -1692,8 +1709,10 @@ var MicrophoneMatcher = class {
       this.activityRefinement?.refine(requestId, detection, captureGeneration);
       return detection;
     } catch (error) {
-      this.activityRefinement?.settleRequest(requestId);
-      emitError(this.events, "audiomarker", error);
+      if (captureGeneration === this.captureGeneration && this.running) {
+        this.activityRefinement?.settleRequest(requestId);
+        emitError(this.events, "audiomarker", error);
+      }
       return null;
     }
   }
@@ -1744,9 +1763,9 @@ var MicrophoneMatcher = class {
   }
   async cleanupAfterStartFailure() {
     this.running = false;
+    await this.resetCaptureState();
     await this.graphController?.stop();
     this.graphController = null;
-    await this.resetCaptureState();
     if (this.stopTracksOnStop) {
       this.stream?.getTracks().forEach((track) => track.stop());
     }
@@ -1777,7 +1796,7 @@ var MicrophoneMatcher = class {
     }
     return this.matchWindow;
   }
-  reportCampaign(recognitionId, match, captureGeneration, audioMarkerRequestId) {
+  reportCampaign(recognitionId, match, captureGeneration, audioMarkerRequestId, distinct) {
     const reporter = this.options.activityReporter;
     if (!reporter) {
       return;
@@ -1786,7 +1805,8 @@ var MicrophoneMatcher = class {
       recognitionId,
       match,
       captureGeneration,
-      audioMarkerRequestId
+      audioMarkerRequestId,
+      distinct
     );
   }
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sorisdk/web-audio",
-  "version": "0.6.8",
+  "version": "0.6.9",
   "description": "Web SDK for browser-based audio recognition with SORI API",
   "type": "module",
   "main": "./dist/index.js",
@@ -34,8 +34,8 @@
   "license": "SEE LICENSE IN LICENSE.md",
   "homepage": "https://docs.soriapi.com/ko/integration/web",
   "dependencies": {
-    "@sorisdk/afpgen": "0.6.8",
-    "@sorisdk/matcher": "0.6.8"
+    "@sorisdk/afpgen": "0.6.9",
+    "@sorisdk/matcher": "0.6.9"
   },
   "devDependencies": {
     "tsup": "^8.5.1",