Rewrite SDK with napi-rs

[steckes]

Rewritten on napi-rs, on top of the public aic-sdk Rust crate.

The previous release was a raw native addon exporting low-level primitives, wrapped in a
hand-written JavaScript ergonomics layer and documented only with JSDoc. That layer is gone:
the binding and its type declarations are now generated from annotated Rust.

Added

• TypeScript declarations. index.d.ts ships with the package, with doc comments on
  every class, method and enum member. Previous releases published no types.
• Analyzer.analyzeAsync, running the analysis model on a worker thread. The SDK's
  analysis models are too expensive for an audio thread, and Node cannot move the analyzer
  into a worker the way the Rust SDK's collector/analyzer split allows, so this is how that
  capability is reached here. There is no AnalyzerAsync class: only this one call moves
  off-thread, and buffer stays synchronous and lock-free so audio can keep arriving while
  an analysis is in flight.
• ProcessorAsync and VadAsync, mirroring the Rust SDK. Each call returns a promise
  and runs on Node's libuv thread pool, keeping enhancement and detection off the event
  loop. process copies its input and resolves to the samples rather than writing in place,
  so the caller's array stays valid while the promise is pending. Parallelism is across
  instances: give each stream its own, and raise UV_THREADPOOL_SIZE to run more than four
  at once.
• Model.download is asynchronous and resolves to the model path, so a cold download no
  longer blocks the event loop.

Changed

The API was modernized:

0.23	0.24
Model.download(...) (blocking)	await Model.download(...)
analyzerPair(model, key)	new Analyzer(model, key)
collector.buffer(...)	analyzer.buffer(...)
OtelConfig.enabled()	{ enable: true }

• analyzerPair() and the separate Collector are replaced by a single Analyzer class
  with buffer() and analyzeBuffered(). The SDK separates collection from analysis so the
  halves can live on different threads; that does not apply in Node, where an instance cannot
  cross into another worker.
• OtelConfig is a plain object ({ enable, sessionId?, exportIntervalMs? }) rather than a
  class with static factories, still passed as the optional third constructor argument.
• ProcessorParameter and VadParameter are real enums with stable numeric values
  (Bypass = 0, EnhancementLevel = 1; SpeechHoldDuration = 0, Sensitivity = 1,
  MinimumSpeechDuration = 2).
• Minimum supported Node version is 18.

Removed

• FileAnalyzer. Its convenience windowing is not yet reimplemented on the new binding;
  window over Analyzer directly in the meantime.

[andresovela]

analyzerPair() and the separate Collector are replaced by a single Analyzer class
with buffer() and analyzeBuffered(). The SDK separates collection from analysis so the
halves can live on different threads; that does not apply in Node, where an instance cannot
cross into another worker.

I don't understand this. If that were the case, there's also no point in keeping the Context types around, since they're meant to be used across threads?

[steckes]

@andresovela The only way to use background threads in napi seems to be via the async functions which execute on the uv thread pool. That happens when you call analyzeAsync. For the contexts on the other hand, it does make sense to keep them separate, because you still want to call the functions on the context while the process function is being called on the background thread. The Collector / Analyzer split does not offer any functionality in that regard.

[andresovela]

@steckes how would you write code that analyzes the output of a Quail model for example? You'd have to call analyze in the same thread dedicated for audio processing

[steckes]

Everything runs on the main event loop also your incoming audio. From there you run analyze_async which then runs the analyzer on the background thread without blocking your event loop. There is no dedicated audio thread or similar in node afaik where you could push the analyzer inside or where you process the audio.

for (const block of audioBlocks) {
  processor.process(block)      // enhance in place
  analyzer.buffer(block)        // lock-free, cheap
}

const result = await analyzer.analyzeAsync()  // model runs on a worker

[andresovela]

That example runs the analyzer in a background thread, but blocks the current thread from processing further audio until the analysis is complete. Ideally you'd analyze independently in a different task, and then the Collector/Analyzer split is the way to go.

[mgeier]

LGTM, pending the resolution of @andresovela's comments.

[andresovela]

I think I've come to terms with the new Analyzer API. I think we can leave it as proposed in this PR. However, I do think the docs of the new APIs need to be rewritten as we have them as we have them in other SDKs. They have diverged a lot in this PR, and several doc-comments read very AI-generated.

For example:
This PR:

/// Analyzer for analysis models such as Tyto.
///
/// Buffering and analysis are deliberately separate calls: {@link Analyzer#buffer} is cheap
/// enough for the audio path, while running the model is not. Analysis therefore comes in
/// two forms: {@link Analyzer#analyzeAsync} on a worker thread, and
/// {@link Analyzer#analyze} on the calling thread.
///
/// Only a fixed span of audio is retained, determined by the model; older audio is
/// discarded as more is buffered.
///
/// The SDK splits this into a collector and an analyzer so the two halves can live on
/// different threads. A class instance cannot cross into a Node worker, so both are exposed
/// as one object here, but the split still shows through: {@link Analyzer#buffer} drives
/// the collector on the calling thread, while {@link Analyzer#analyzeAsync} moves the
/// analyzer half onto a worker. The SDK guarantees the two are safe to use concurrently.

vs Rust SDK:

/// Creates a collector/analyzer pair for non-real-time analysis.
///
/// The collector is designed to be placed in the audio thread, buffering audio chunks for
/// later analysis.
///
/// The analyzer is designed to be run separately. Analysis models are computationally expensive
/// and cannot run in the audio thread. The analyzer has access to the audio buffered by the
/// collector, and it can access it safely across threads.
///
/// The collector retains a span of audio determined by the analysis model. As more samples
/// get collected, old audio is discarded.