@runanywhere/web 0.1.0-beta.1

package/dist/Foundation/WASMBridge.js

@@ -0,0 +1,393 @@
+/**
+ * RunAnywhere Web SDK - WASM Bridge
+ *
+ * Loads the RACommons WASM module and provides typed wrappers
+ * around the C API functions. This is the web equivalent of:
+ *   - CppBridge.swift (iOS)
+ *   - CppBridge.kt (Kotlin/Android)
+ *   - dart_bridge.dart (Flutter)
+ *   - HybridRunAnywhereCore.cpp (React Native)
+ */
+import { SDKError, SDKErrorCode } from './ErrorTypes';
+import { SDKLogger } from './SDKLogger';
+// ---------------------------------------------------------------------------
+// WASM Bridge
+// ---------------------------------------------------------------------------
+const logger = new SDKLogger('WASMBridge');
+/**
+ * WASMBridge - Loads and manages the RACommons WASM module.
+ *
+ * Singleton that provides access to all RACommons C API functions
+ * compiled to WebAssembly. This is the central point through which
+ * all SDK operations flow, identical to CppBridge on mobile platforms.
+ */
+export class WASMBridge {
+    static _instance = null;
+    _module = null;
+    _loaded = false;
+    _loading = null;
+    _accelerationMode = 'cpu';
+    /** The URL that was used to load the WASM glue JS (for worker reuse). */
+    _loadedModuleUrl = null;
+    static get shared() {
+        if (!WASMBridge._instance) {
+            WASMBridge._instance = new WASMBridge();
+        }
+        return WASMBridge._instance;
+    }
+    /** Whether the WASM module is loaded */
+    get isLoaded() {
+        return this._loaded && this._module !== null;
+    }
+    /** Get the raw Emscripten module (throws if not loaded) */
+    get module() {
+        if (!this._module) {
+            throw SDKError.wasmNotLoaded();
+        }
+        return this._module;
+    }
+    /** The hardware acceleration mode in use (webgpu or cpu). */
+    get accelerationMode() {
+        return this._accelerationMode;
+    }
+    /**
+     * The URL of the WASM glue JS that was successfully loaded.
+     * Web Workers should use this URL to load the same WASM variant
+     * (WebGPU or CPU) that the main thread is using.
+     *
+     * Returns `null` if `load()` has not been called yet.
+     */
+    get workerWasmUrl() {
+        return this._loadedModuleUrl;
+    }
+    /**
+     * Load the RACommons WASM module.
+     *
+     * Detects WebGPU at init time and loads the appropriate build variant:
+     *   - `racommons-webgpu.js` when WebGPU + JSPI are available
+     *   - `racommons.js` as the CPU-only fallback
+     *
+     * Safe to call concurrently -- only the first caller triggers the actual
+     * load; subsequent callers await the same in-flight promise.
+     *
+     * @param wasmUrl        - URL to the CPU-only racommons.js glue file.
+     * @param webgpuWasmUrl  - URL to the WebGPU racommons-webgpu.js glue file.
+     * @param acceleration   - Force a specific mode ('auto' detects, 'webgpu' forces GPU, 'cpu' forces CPU).
+     */
+    async load(wasmUrl, webgpuWasmUrl, acceleration = 'auto') {
+        if (this._loaded) {
+            logger.debug('WASM module already loaded');
+            return;
+        }
+        // Prevent duplicate loading -- return the in-flight promise
+        if (this._loading) {
+            await this._loading;
+            return;
+        }
+        this._loading = this._doLoad(wasmUrl, webgpuWasmUrl, acceleration);
+        try {
+            await this._loading;
+        }
+        finally {
+            this._loading = null;
+        }
+    }
+    /**
+     * Internal load implementation.
+     * Separated from `load()` so the concurrent-load guard can wrap it.
+     */
+    async _doLoad(wasmUrl, webgpuWasmUrl, acceleration = 'auto') {
+        logger.info('Loading RACommons WASM module...');
+        try {
+            // Determine whether to use the WebGPU variant
+            const useWebGPU = await this.resolveAcceleration(acceleration);
+            this._accelerationMode = useWebGPU ? 'webgpu' : 'cpu';
+            // Select the correct module URL
+            const moduleUrl = useWebGPU
+                ? (webgpuWasmUrl ?? new URL('../../wasm/racommons-webgpu.js', import.meta.url).href)
+                : (wasmUrl ?? new URL('../../wasm/racommons.js', import.meta.url).href);
+            this._loadedModuleUrl = moduleUrl;
+            logger.info(`Acceleration mode: ${this._accelerationMode} (loading ${useWebGPU ? 'racommons-webgpu' : 'racommons'})`);
+            // Safety-net probe: verify the WebGPU glue JS was compiled with
+            // JSPI support.  A JSPI-enabled build contains "WebAssembly.promising"
+            // which wraps exported WASM functions so they can suspend during
+            // async WebGPU operations.  If the marker is absent the build is
+            // either outdated or misconfigured and generation would crash with
+            // "RuntimeError: unreachable".  Fall back to CPU in that case.
+            if (useWebGPU && acceleration === 'auto') {
+                try {
+                    const probeResp = await fetch(moduleUrl);
+                    const probeText = await probeResp.text();
+                    if (!probeText.includes('WebAssembly.promising')) {
+                        logger.warning('WebGPU WASM build lacks JSPI support (WebAssembly.promising not found). Falling back to CPU.');
+                        return this._doLoad(wasmUrl, undefined, 'cpu');
+                    }
+                }
+                catch {
+                    // If the probe fails, proceed with WebGPU and let runtime errors
+                    // surface normally.
+                }
+            }
+            // Dynamic import of the Emscripten glue JS
+            // The glue file exports a factory function: createRACommonsModule()
+            const { default: createModule } = await import(/* @vite-ignore */ moduleUrl);
+            // Instantiate the WASM module
+            this._module = await createModule({
+                // Emscripten module overrides
+                print: (text) => logger.info(text),
+                printErr: (text) => logger.error(text),
+            });
+            // Verify module loaded correctly.
+            // With JSPI builds some exports may return Promises, so await just
+            // in case _rac_wasm_ping was wrapped with WebAssembly.promising.
+            const pingRaw = this._module._rac_wasm_ping();
+            const pingResult = (typeof pingRaw === 'object' && pingRaw !== null && 'then' in pingRaw)
+                ? await pingRaw
+                : pingRaw;
+            if (pingResult !== 42) {
+                throw new Error(`WASM ping failed: expected 42, got ${pingResult}`);
+            }
+            this._loaded = true;
+            logger.info(`RACommons WASM module loaded successfully (${this._accelerationMode})`);
+        }
+        catch (error) {
+            // If WebGPU load failed, fall back to CPU automatically
+            if (this._accelerationMode === 'webgpu' && acceleration === 'auto') {
+                const reason = error instanceof Error ? error.message : String(error);
+                logger.warning(`WebGPU WASM module failed to load (${reason}), falling back to CPU`);
+                this._accelerationMode = 'cpu';
+                this._module = null;
+                this._loaded = false;
+                return this._doLoad(wasmUrl, undefined, 'cpu');
+            }
+            this._module = null;
+            this._loaded = false;
+            const message = error instanceof Error ? error.message : String(error);
+            logger.error(`Failed to load WASM module: ${message}`);
+            throw new SDKError(SDKErrorCode.WASMLoadFailed, `Failed to load WASM module: ${message}`);
+        }
+    }
+    // -----------------------------------------------------------------------
+    // WebGPU Detection
+    // -----------------------------------------------------------------------
+    /**
+     * Determine whether to use WebGPU based on the acceleration preference
+     * and actual browser capability.
+     */
+    async resolveAcceleration(preference) {
+        if (preference === 'cpu')
+            return false;
+        const hasWebGPU = await WASMBridge.detectWebGPU();
+        if (preference === 'webgpu' && !hasWebGPU) {
+            logger.warning('WebGPU requested but not available; falling back to CPU');
+            return false;
+        }
+        if (!hasWebGPU)
+            return false;
+        // The WebGPU WASM module is compiled with JSPI (WebAssembly JavaScript
+        // Promise Integration).  If the browser doesn't expose the JSPI APIs
+        // the module will fail to instantiate.
+        const hasJSPI = WASMBridge.detectJSPI();
+        if (!hasJSPI) {
+            logger.warning('WebGPU available but browser lacks JSPI support (WebAssembly.promising). ' +
+                'Update Chrome to 128+ or enable chrome://flags/#experimental-wasm-jspi. Falling back to CPU.');
+            return false;
+        }
+        return true;
+    }
+    /**
+     * Probe for a functional WebGPU adapter.
+     * Returns true only when the browser exposes navigator.gpu AND
+     * a valid adapter can be obtained.
+     */
+    static async detectWebGPU() {
+        if (typeof navigator === 'undefined' || !('gpu' in navigator))
+            return false;
+        try {
+            const gpu = navigator.gpu;
+            const adapter = await gpu?.requestAdapter();
+            return adapter !== null;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Detect JSPI (JavaScript Promise Integration) support.
+     * The WebGPU WASM module requires WebAssembly.promising and
+     * WebAssembly.Suspending to suspend during async GPU operations.
+     */
+    static detectJSPI() {
+        try {
+            return (typeof WebAssembly !== 'undefined' &&
+                'promising' in WebAssembly &&
+                'Suspending' in WebAssembly);
+        }
+        catch {
+            return false;
+        }
+    }
+    // -----------------------------------------------------------------------
+    // String Helpers
+    // -----------------------------------------------------------------------
+    /** Allocate a C string in WASM memory. Caller must free. */
+    allocString(str) {
+        const m = this.module;
+        const len = m.lengthBytesUTF8(str) + 1;
+        const ptr = m._malloc(len);
+        m.stringToUTF8(str, ptr, len);
+        return ptr;
+    }
+    /** Read a C string from WASM memory */
+    readString(ptr) {
+        if (ptr === 0)
+            return '';
+        return this.module.UTF8ToString(ptr);
+    }
+    /** Free WASM memory */
+    free(ptr) {
+        if (ptr !== 0) {
+            this.module._free(ptr);
+        }
+    }
+    // -----------------------------------------------------------------------
+    // Binary Data Helpers
+    //
+    // HEAPU8 / HEAPF32 may not be exported by the Emscripten module.
+    // These helpers try the fast HEAPU8/HEAPF32 path first, then fall
+    // back to byte-by-byte setValue/getValue which is always available.
+    // -----------------------------------------------------------------------
+    /**
+     * Write a Uint8Array into WASM linear memory at `destPtr`.
+     *
+     * Fast path uses `HEAPU8.set()` when available (after WASM rebuild).
+     * Fallback uses `setValue` byte-by-byte (works with any build).
+     */
+    writeBytes(src, destPtr) {
+        const m = this.module;
+        if (m.HEAPU8) {
+            m.HEAPU8.set(src, destPtr);
+            return;
+        }
+        for (let i = 0; i < src.length; i++) {
+            m.setValue(destPtr + i, src[i], 'i8');
+        }
+    }
+    /**
+     * Read `length` bytes from WASM linear memory starting at `srcPtr`.
+     *
+     * Fast path uses `HEAPU8.slice()` when available.
+     * Fallback uses `getValue` byte-by-byte.
+     */
+    readBytes(srcPtr, length) {
+        const m = this.module;
+        if (m.HEAPU8) {
+            return m.HEAPU8.slice(srcPtr, srcPtr + length);
+        }
+        const result = new Uint8Array(length);
+        for (let i = 0; i < length; i++) {
+            result[i] = m.getValue(srcPtr + i, 'i8') & 0xFF;
+        }
+        return result;
+    }
+    /**
+     * Read `count` float32 values from WASM linear memory starting at `srcPtr`.
+     *
+     * Fast path uses `HEAPF32` when available.
+     * Fallback reads 4 bytes at a time via getValue('float').
+     */
+    readFloat32Array(srcPtr, count) {
+        const m = this.module;
+        if (m.HEAPF32) {
+            const startIndex = srcPtr >> 2; // byte offset → float32 index
+            return m.HEAPF32.slice(startIndex, startIndex + count);
+        }
+        const result = new Float32Array(count);
+        for (let i = 0; i < count; i++) {
+            result[i] = m.getValue(srcPtr + i * 4, 'float');
+        }
+        return result;
+    }
+    /**
+     * Write a Float32Array into WASM linear memory at `destPtr`.
+     * `destPtr` must be 4-byte aligned.
+     *
+     * Fast path uses `HEAPF32.set()` when available.
+     * Fallback uses `setValue` with 'float'.
+     */
+    writeFloat32Array(src, destPtr) {
+        const m = this.module;
+        if (m.HEAPF32) {
+            m.HEAPF32.set(src, destPtr >> 2);
+            return;
+        }
+        for (let i = 0; i < src.length; i++) {
+            m.setValue(destPtr + i * 4, src[i], 'float');
+        }
+    }
+    /**
+     * Read a single float32 value from WASM linear memory.
+     */
+    readFloat32(ptr) {
+        const m = this.module;
+        if (m.HEAPF32) {
+            return m.HEAPF32[ptr >> 2];
+        }
+        return m.getValue(ptr, 'float');
+    }
+    // -----------------------------------------------------------------------
+    // C API Wrappers
+    // -----------------------------------------------------------------------
+    /** Check a rac_result_t and throw SDKError if not success */
+    checkResult(result, operation) {
+        if (result !== 0) {
+            const errMsgPtr = this.module._rac_error_message(result);
+            const errMsg = this.readString(errMsgPtr);
+            throw SDKError.fromRACResult(result, `${operation}: ${errMsg}`);
+        }
+    }
+    /** Get RACommons error message for a result code */
+    getErrorMessage(resultCode) {
+        const ptr = this.module._rac_error_message(resultCode);
+        return this.readString(ptr);
+    }
+    /**
+     * Type-safe wrapper around Emscripten ccall().
+     * Centralizes all dynamic WASM function calls through the bridge.
+     */
+    callFunction(funcName, returnType, argTypes, args, opts) {
+        if (!this._module)
+            throw SDKError.wasmNotLoaded();
+        return this._module.ccall(funcName, returnType, argTypes, args, opts);
+    }
+    /**
+     * Call a WASM function that returns rac_result_t and throw SDKError if
+     * the result is non-zero.
+     */
+    callWithCheck(funcName, argTypes, args) {
+        const result = this.callFunction(funcName, 'number', argTypes, args);
+        this.checkResult(result, funcName);
+    }
+    // -----------------------------------------------------------------------
+    // Cleanup
+    // -----------------------------------------------------------------------
+    /** Shutdown the WASM module */
+    shutdown() {
+        if (this._module && this._loaded) {
+            try {
+                this._module._rac_shutdown();
+            }
+            catch {
+                // Ignore shutdown errors
+            }
+        }
+        this._module = null;
+        this._loaded = false;
+        this._loading = null;
+        this._accelerationMode = 'cpu';
+        this._loadedModuleUrl = null;
+        WASMBridge._instance = null;
+        logger.info('WASM bridge shut down');
+    }
+}
+//# sourceMappingURL=WASMBridge.js.map

package/dist/Foundation/WASMBridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"WASMBridge.js","sourceRoot":"","sources":["../../src/Foundation/WASMBridge.ts"],"names":[],"mappings":"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"}

package/dist/Infrastructure/ArchiveUtility.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Archive Utility - Tar.gz extraction for model archives
+ *
+ * Provides browser-native tar.gz extraction using DecompressionStream (gzip)
+ * and a minimal tar parser. This matches the Swift SDK approach where Piper TTS
+ * models are distributed as .tar.gz archives bundling model files + espeak-ng-data.
+ */
+/** A single entry extracted from a tar archive. */
+export interface TarEntry {
+    /** Relative path within the archive (e.g., 'espeak-ng-data/phondata') */
+    path: string;
+    /** File contents */
+    data: Uint8Array;
+}
+/**
+ * Extract a .tar.gz archive into an array of file entries.
+ *
+ * Uses the browser-native DecompressionStream for gzip decompression,
+ * then parses the tar format (512-byte header blocks).
+ *
+ * @param tarGzData - The raw tar.gz bytes
+ * @returns Array of extracted files (directories are skipped)
+ */
+export declare function extractTarGz(tarGzData: Uint8Array): Promise<TarEntry[]>;
+//# sourceMappingURL=ArchiveUtility.d.ts.map

package/dist/Infrastructure/ArchiveUtility.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ArchiveUtility.d.ts","sourceRoot":"","sources":["../../src/Infrastructure/ArchiveUtility.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH,mDAAmD;AACnD,MAAM,WAAW,QAAQ;IACvB,yEAAyE;IACzE,IAAI,EAAE,MAAM,CAAC;IACb,oBAAoB;IACpB,IAAI,EAAE,UAAU,CAAC;CAClB;AAoBD;;;;;;;;GAQG;AACH,wBAAsB,YAAY,CAAC,SAAS,EAAE,UAAU,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CAG7E"}

package/dist/Infrastructure/ArchiveUtility.js

@@ -0,0 +1,139 @@
+/**
+ * Archive Utility - Tar.gz extraction for model archives
+ *
+ * Provides browser-native tar.gz extraction using DecompressionStream (gzip)
+ * and a minimal tar parser. This matches the Swift SDK approach where Piper TTS
+ * models are distributed as .tar.gz archives bundling model files + espeak-ng-data.
+ */
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** Tar header block size */
+const TAR_BLOCK_SIZE = 512;
+/** Tar file type flags */
+var TarFileType;
+(function (TarFileType) {
+    TarFileType[TarFileType["Regular"] = 48] = "Regular";
+    TarFileType[TarFileType["RegularAlt"] = 0] = "RegularAlt";
+    TarFileType[TarFileType["Directory"] = 53] = "Directory";
+})(TarFileType || (TarFileType = {}));
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Extract a .tar.gz archive into an array of file entries.
+ *
+ * Uses the browser-native DecompressionStream for gzip decompression,
+ * then parses the tar format (512-byte header blocks).
+ *
+ * @param tarGzData - The raw tar.gz bytes
+ * @returns Array of extracted files (directories are skipped)
+ */
+export async function extractTarGz(tarGzData) {
+    const tarData = await decompressGzip(tarGzData);
+    return parseTar(tarData);
+}
+// ---------------------------------------------------------------------------
+// Gzip Decompression (browser-native)
+// ---------------------------------------------------------------------------
+/**
+ * Decompress gzip data using the browser's native DecompressionStream API.
+ * Supported in Chrome 80+, Firefox 113+, Safari 16.4+.
+ */
+async function decompressGzip(compressed) {
+    const ds = new DecompressionStream('gzip');
+    const writer = ds.writable.getWriter();
+    const reader = ds.readable.getReader();
+    // Write compressed data and close the stream
+    writer.write(compressed);
+    writer.close();
+    // Read all decompressed chunks
+    const chunks = [];
+    let totalLength = 0;
+    while (true) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        chunks.push(value);
+        totalLength += value.length;
+    }
+    // Concatenate into a single buffer
+    const result = new Uint8Array(totalLength);
+    let offset = 0;
+    for (const chunk of chunks) {
+        result.set(chunk, offset);
+        offset += chunk.length;
+    }
+    return result;
+}
+// ---------------------------------------------------------------------------
+// Tar Parser
+// ---------------------------------------------------------------------------
+/**
+ * Parse a tar archive and return all regular file entries.
+ * Directories and special entries are skipped.
+ *
+ * Tar format:
+ *  - Each entry = 512-byte header + ceil(fileSize/512)*512 bytes of data
+ *  - Header contains filename (0-100), size (124-136 octal), type (156)
+ *  - Archive ends with two consecutive zero-filled 512-byte blocks
+ */
+function parseTar(tarData) {
+    const entries = [];
+    let offset = 0;
+    while (offset + TAR_BLOCK_SIZE <= tarData.length) {
+        const header = tarData.subarray(offset, offset + TAR_BLOCK_SIZE);
+        // End of archive: two zero-filled blocks
+        if (isZeroBlock(header))
+            break;
+        const name = readString(header, 0, 100);
+        const size = readOctal(header, 124, 12);
+        const typeFlag = header[156];
+        // UStar prefix (for paths longer than 100 chars)
+        const prefix = readString(header, 345, 155);
+        const fullPath = prefix ? `${prefix}/${name}` : name;
+        // Normalise: strip leading './' or '/'
+        const normalisedPath = fullPath.replace(/^\.\//, '').replace(/^\//, '');
+        offset += TAR_BLOCK_SIZE;
+        if (size > 0) {
+            const dataStart = offset;
+            const dataEnd = dataStart + size;
+            // Only include regular files (skip directories, symlinks, etc.)
+            if (typeFlag === TarFileType.Regular || typeFlag === TarFileType.RegularAlt) {
+                entries.push({
+                    path: normalisedPath,
+                    data: tarData.slice(dataStart, dataEnd),
+                });
+            }
+            // Advance past data blocks (padded to 512-byte boundary)
+            offset += Math.ceil(size / TAR_BLOCK_SIZE) * TAR_BLOCK_SIZE;
+        }
+    }
+    return entries;
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/** Read a null-terminated ASCII string from a tar header field. */
+function readString(header, offset, length) {
+    let end = offset;
+    const limit = offset + length;
+    while (end < limit && header[end] !== 0)
+        end++;
+    const decoder = new TextDecoder('ascii');
+    return decoder.decode(header.subarray(offset, end));
+}
+/** Read an octal number from a tar header field. */
+function readOctal(header, offset, length) {
+    const str = readString(header, offset, length).trim();
+    return str ? parseInt(str, 8) : 0;
+}
+/** Check if a 512-byte block is all zeros (end-of-archive marker). */
+function isZeroBlock(block) {
+    for (let i = 0; i < block.length; i++) {
+        if (block[i] !== 0)
+            return false;
+    }
+    return true;
+}
+//# sourceMappingURL=ArchiveUtility.js.map

package/dist/Infrastructure/ArchiveUtility.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ArchiveUtility.js","sourceRoot":"","sources":["../../src/Infrastructure/ArchiveUtility.ts"],"names":[],"mappings":"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"}

package/dist/Infrastructure/AudioCapture.d.ts

@@ -0,0 +1,87 @@
+/**
+ * RunAnywhere Web SDK - Audio Capture
+ *
+ * Captures microphone audio using Web Audio API and provides
+ * Float32Array PCM samples suitable for STT and VAD processing.
+ *
+ * Supports:
+ *   - Real-time microphone capture via getUserMedia
+ *   - Configurable sample rate (resampling via AudioContext)
+ *   - Chunk-based callbacks for streaming STT/VAD
+ *   - Buffer accumulation (getAudioBuffer, drainBuffer, clearBuffer)
+ *   - Audio level monitoring via AnalyserNode (currentLevel getter)
+ */
+export type AudioChunkCallback = (samples: Float32Array) => void;
+export type AudioLevelCallback = (level: number) => void;
+export interface AudioCaptureConfig {
+    /** Target sample rate (default: 16000 for STT) */
+    sampleRate?: number;
+    /** Chunk size in samples (default: 1600 = 100ms at 16kHz) */
+    chunkSize?: number;
+    /** Number of audio channels (default: 1, mono) */
+    channels?: number;
+}
+/**
+ * AudioCapture - Captures microphone audio for STT/VAD processing.
+ *
+ * Uses Web Audio API (AudioContext + ScriptProcessorNode) to capture
+ * microphone audio, resample to target rate, and deliver Float32Array
+ * PCM chunks to the consumer.
+ *
+ * Includes buffer accumulation for batch STT and an AnalyserNode for
+ * real-time audio level metering (0-1 range).
+ */
+export declare class AudioCapture {
+    private audioContext;
+    private mediaStream;
+    private sourceNode;
+    private processorNode;
+    private _analyser;
+    private _animFrameId;
+    private _isCapturing;
+    private _currentLevel;
+    private _pcmChunks;
+    private readonly config;
+    private chunkCallback;
+    private levelCallback;
+    constructor(config?: AudioCaptureConfig);
+    get isCapturing(): boolean;
+    /** Current normalized audio level (0..1), updated per animation frame. */
+    get currentLevel(): number;
+    /**
+     * Get the actual sample rate of the audio context.
+     * May differ from requested rate if browser doesn't support it.
+     */
+    get actualSampleRate(): number;
+    /** Duration of collected audio in seconds based on configured sample rate. */
+    get bufferDurationSeconds(): number;
+    /**
+     * Start capturing microphone audio.
+     *
+     * @param onChunk - Optional callback receiving Float32Array chunks of PCM audio (streaming)
+     * @param onLevel - Optional callback invoked per animation frame with audio level 0..1
+     * @throws If microphone permission is denied
+     */
+    start(onChunk?: AudioChunkCallback, onLevel?: AudioLevelCallback): Promise<void>;
+    /**
+     * Stop capturing audio and release resources.
+     */
+    stop(): void;
+    /**
+     * Get all collected PCM audio as a single Float32Array.
+     * Does NOT clear the buffer — call `clearBuffer()` separately.
+     */
+    getAudioBuffer(): Float32Array;
+    /**
+     * Drain: return the current buffer and clear it for the next segment.
+     * Useful for live mode where we transcribe segments incrementally.
+     */
+    drainBuffer(): Float32Array;
+    /** Clear collected PCM data without stopping capture. */
+    clearBuffer(): void;
+    /** Start the requestAnimationFrame loop that reads the AnalyserNode. */
+    private startLevelMonitoring;
+    private cleanupResources;
+    private nearestPowerOf2;
+}
+//# sourceMappingURL=AudioCapture.d.ts.map