@ohm_studio/sdk 0.2.0 → 0.5.0

package/dist/recorder.d.ts

@@ -1,30 +1,105 @@
 /**
- * Browser MediaRecorder wrapper. Hides the boilerplate of permissions,
- * stream tracks, chunk collection, and cleanup so customers can ship a
- * working recorder UI in three lines:
+ * Browser audio recorder for clinical consults.
  *
- *   const rec = new Recorder();
+ * Wraps `MediaRecorder` + `getUserMedia` + `AudioContext` + `Wake Lock`
+ * with clinically-tuned defaults (16 kHz mono, echo-cancel, noise-suppress,
+ * auto-gain) and a codec cascade that works on iOS Safari, Firefox, and
+ * every Chromium browser.
+ *
+ *   const rec = new Recorder({
+ *     onLevel: (rms) => setVu(rms),
+ *     onError: (e)   => toast(e.message),
+ *     maxDurationMs: 10 * 60_000,        // hard cap at 10 min
+ *     silenceAutoStop: { ms: 6000 },     // stop after 6 s of silence
+ *     wakeLock: true,
+ *   });
  *   await rec.start();
- *   const blob = await rec.stop();   // → ready to pass to ohm.audio.extract
+ *   const blob = await rec.stop();       // → ohm.audio.extract({ file: blob, ... })
  *
- * Designed for Vite / Next.js / CRA / any modern browser. SSR-safe — the
- * `MediaRecorder` API is only touched inside method bodies, so importing
- * this module doesn't break server bundles.
+ * SSR-safe — every browser-only API is touched inside method bodies, never
+ * at module scope. Importing this file from a Next.js server bundle is OK.
  */
+export type RecorderState = "idle" | "starting" | "recording" | "paused" | "stopping";
+export type RecorderErrorCode = "NotSupported" | "PermissionDenied" | "NoMicrophone" | "MicrophoneBusy" | "OverConstrained" | "DeviceLost" | "InvalidState" | "Unknown";
+export declare class RecorderError extends Error {
+    code: RecorderErrorCode;
+    cause?: unknown;
+    constructor(code: RecorderErrorCode, message: string, cause?: unknown);
+}
 export interface RecorderOptions {
     /**
-     * MIME type to request from the browser. Default `audio/webm;codecs=opus`
-     * which is universally supported and small. Pass another value if your
-     * extraction pipeline needs a specific format.
+     * MIME type to request. Default: best supported from the cascade
+     * `audio/webm;codecs=opus` → `audio/mp4;codecs=mp4a.40.2` →
+     * `audio/ogg;codecs=opus` → `audio/mp4` → `audio/webm`.
+     * Pass an explicit value only if your pipeline needs a specific format.
      */
     mimeType?: string;
-    /** Audio constraints passed to `getUserMedia`. */
+    /**
+     * Audio bitrate in bits-per-second. Default 32 000 (32 kbps Opus is
+     * plenty for clinical speech and keeps files tiny).
+     */
+    audioBitsPerSecond?: number;
+    /**
+     * Selected microphone deviceId. Use `Recorder.listMicrophones()` to enumerate.
+     */
+    deviceId?: string;
+    /**
+     * Override `getUserMedia` constraints entirely. If omitted, the SDK applies
+     * clinically-tuned defaults: 16 kHz mono, echo cancellation on,
+     * noise suppression on, auto-gain on.
+     */
     audioConstraints?: MediaTrackConstraints;
-    /** Called whenever recording state changes (idle / recording / stopping). */
+    /**
+     * If true (default), sets `sampleRate: { ideal: 16000 }`, `channelCount: 1`,
+     * and the three voice-cleanup flags. STT models expect 16 kHz mono.
+     */
+    clinicalDefaults?: boolean;
+    /**
+     * Emit a `dataavailable` chunk every N ms. Required for streaming uploads.
+     * Default 0 (one final chunk on stop).
+     */
+    timesliceMs?: number;
+    /**
+     * Hard cap — auto-stop after this many ms of recording. Default off.
+     */
+    maxDurationMs?: number;
+    /**
+     * Auto-stop after sustained silence. RMS below `threshold` for `ms`
+     * continuous milliseconds triggers stop. Default off.
+     */
+    silenceAutoStop?: {
+        /** ms of continuous silence before auto-stop. Default 6000. */
+        ms?: number;
+        /** Linear-RMS threshold 0–1. Default 0.012 (≈ -38 dBFS). */
+        threshold?: number;
+    };
+    /**
+     * Hold a screen Wake Lock while recording, so phones / tablets don't dim.
+     * Default false. Falls back silently when the API isn't available.
+     */
+    wakeLock?: boolean;
+    /**
+     * Pause recording when the tab becomes hidden. Default false.
+     * (We never auto-resume — the user has to come back and tap.)
+     */
+    pauseOnHidden?: boolean;
+    /** Recording state changes. */
     onStateChange?: (state: RecorderState) => void;
+    /** Periodic linear RMS level 0–1 (≈ 60 Hz). Wire to a VU meter. */
+    onLevel?: (rms: number) => void;
+    /** Each `dataavailable` chunk. Useful for streaming uploads. */
+    onChunk?: (chunk: Blob) => void;
+    /** All recorder errors flow through here in addition to throwing on the awaited call. */
+    onError?: (err: RecorderError) => void;
+    /** Microphone disconnected (cable unplugged, OS revoked permission). */
+    onDeviceLost?: () => void;
+}
+export interface MicrophoneInfo {
+    deviceId: string;
+    label: string;
+    groupId: string;
 }
-export type RecorderState = "idle" | "recording" | "stopping";
-/** Returns true if the runtime supports recording (browser with MediaRecorder). */
+/** True if the runtime supports recording (browser with MediaRecorder + getUserMedia). */
 export declare function isRecordingSupported(): boolean;
 export declare class Recorder {
     private rec;
@@ -32,23 +107,64 @@ export declare class Recorder {
     private stream;
     private state;
     private opts;
+    private mime;
+    private startedAt;
+    private pausedAccumMs;
+    private pauseStartedAt;
+    private maxStopTimer;
+    private audioCtx;
+    private analyser;
+    private levelSource;
+    private levelRafId;
+    private levelBuffer;
+    private silenceSinceMs;
+    private wakeLockSentinel;
+    private visibilityHandler;
     constructor(opts?: RecorderOptions);
-    /** Current recorder state. */
+    /** Static support check. */
+    static isSupported(): boolean;
+    /** Pick the best supported MIME type for this browser. */
+    static getSupportedMimeType(prefer?: string): string | undefined;
+    /**
+     * Probe microphone permission *without* requesting it. Returns:
+     *   "granted" — already allowed
+     *   "denied"  — user has blocked access; calling start() will reject
+     *   "prompt"  — browser will show the dialog on next start()
+     *   "unknown" — browser doesn't support the Permissions API
+     */
+    static probePermission(): Promise<"granted" | "denied" | "prompt" | "unknown">;
+    /** Enumerate microphones. Empty `label` until permission is granted at least once. */
+    static listMicrophones(): Promise<MicrophoneInfo[]>;
+    /** Current state. */
     get currentState(): RecorderState;
+    /** Final MIME type the browser is producing (set after `start`). */
+    get mimeType(): string | undefined;
+    /** Recorded duration in ms (excluding paused time). 0 when idle. */
+    getDuration(): number;
     /**
      * Request microphone access and begin recording. Resolves once the
-     * underlying MediaRecorder fires its `start` event. Throws on permission
-     * denial or unsupported runtime.
+     * underlying MediaRecorder has fired `start`.
      */
     start(): Promise<void>;
+    /** Pause recording. Resumable via `resume()`. */
+    pause(): void;
+    /** Resume after `pause()`. */
+    resume(): void;
     /**
-     * Stop recording and resolve with the assembled Blob. The caller can
-     * pass this Blob directly to `ohm.audio.extract({ file: blob, ... })`.
-     * Stops all media tracks so the browser's mic indicator clears.
+     * Stop recording and return the assembled Blob, ready to pass to
+     * `ohm.audio.extract({ file: blob, … })`. Releases mic, wake lock, AudioContext.
      */
     stop(): Promise<Blob>;
-    /** Abort the recording without surfacing the captured audio. */
+    /** Stop after `ms` from now. Returns the same promise as `stop()`. */
+    stopAfter(ms: number): Promise<Blob>;
+    /** Abort — releases everything, no Blob. */
     cancel(): void;
+    private startLevelMeter;
+    private acquireWakeLock;
+    private releaseWakeLock;
+    private attachVisibility;
+    private detachVisibility;
+    private cleanupStream;
     private cleanup;
     private setState;
 }

package/dist/recorder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"recorder.d.ts","sourceRoot":"","sources":["../src/recorder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,kDAAkD;IAClD,gBAAgB,CAAC,EAAE,qBAAqB,CAAC;IACzC,6EAA6E;IAC7E,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC;CAChD;AAED,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,WAAW,GAAG,UAAU,CAAC;AAE9D,mFAAmF;AACnF,wBAAgB,oBAAoB,IAAI,OAAO,CAK9C;AAED,qBAAa,QAAQ;IACnB,OAAO,CAAC,GAAG,CAA8B;IACzC,OAAO,CAAC,MAAM,CAAc;IAC5B,OAAO,CAAC,MAAM,CAA4B;IAC1C,OAAO,CAAC,KAAK,CAAyB;IACtC,OAAO,CAAC,IAAI,CAAkB;gBAElB,IAAI,GAAE,eAAoB;IAItC,8BAA8B;IAC9B,IAAI,YAAY,IAAI,aAAa,CAEhC;IAED;;;;OAIG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IA6B5B;;;;OAIG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAsB3B,gEAAgE;IAChE,MAAM,IAAI,IAAI;IAWd,OAAO,CAAC,OAAO;IAQf,OAAO,CAAC,QAAQ;CAKjB"}
+{"version":3,"file":"recorder.d.ts","sourceRoot":"","sources":["../src/recorder.ts"],"names":[],"mappings":"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"}