audio-chunkify 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,326 @@
+# audio-chunkify
+
+**Record audio in the browser and automatically split it into chunks — by silence, by time, or both.**
+
+Framework agnostic · Zero dependencies · TypeScript · ESM
+
+---
+
+## Why audio-chunkify?
+
+Long audio recordings are a problem: large files are slow to upload, expensive to process, and painful to recover from if something goes wrong. `audio-chunkify` solves this by splitting recordings into smaller, manageable chunks as they happen — in real time, without gaps or clicks.
+
+Each chunk lands in an `onChunkProcessed` callback as a `File` object, ready to upload the moment it's created.
+
+```
+[──────────────── recording ────────────────────────────────]
+[── chunk 0 ──][── chunk 1 ──][── chunk 2 ──][── chunk 3 ──]
+     ↓               ↓               ↓               ↓
+  upload()        upload()        upload()      upload() ← final
+```
+
+Splitting happens automatically: after a minimum duration, the recorder listens for a moment of silence and cuts there. If no silence comes, it cuts at a configurable maximum duration. You get clean boundaries and parallel uploads, without any manual work.
+
+---
+
+## Features
+
+- ✂️ **Smart chunk splitting** — cuts at silence after a minimum duration, or forces a cut at maximum duration
+- 🔇 **Real-time silence detection** — dB analysis via Web Audio API, configurable threshold
+- 🔀 **Multi-stream mixing** — merge microphone + system audio (or any streams) into one recording
+- ⏱️ **Time tracking** — elapsed recording time, pause-aware
+- 📦 **TypeScript** — full type definitions included
+- 🪶 **Zero dependencies**
+- ⚙️ **Works with React, Vue, Svelte, Angular, Vanilla JS** — or any browser environment
+
+---
+
+## Installation
+
+```bash
+npm install audio-chunkify
+# or
+pnpm add audio-chunkify
+# or
+yarn add audio-chunkify
+```
+
+---
+
+## Quick start
+
+```ts
+import { AudioChunkify } from 'audio-chunkify'
+
+const recorder = new AudioChunkify()
+const stream = await navigator.mediaDevices.getUserMedia({ audio: true })
+
+recorder.create(stream)
+
+// Called automatically as each chunk is ready
+recorder.onChunkProcessed(async ({ file, index, duration, isLastChunk }) => {
+  console.log(`Chunk ${index} — ${duration.toFixed(1)}s`)
+  await uploadToServer(file) // upload while recording continues
+
+  if (isLastChunk) {
+    console.log('Recording complete')
+  }
+})
+
+recorder.start()
+
+// Later...
+recorder.stop()
+
+// Always release resources when done
+recorder.destroy()
+```
+
+---
+
+## How chunking works
+
+```
+minDuration ──────────────┐
+                           ↓
+[recording...]  [silence detected?] ──yes──→ split here ✂️
+                           │
+                          no
+                           │
+maxDuration ───────────────┴──────────────→ force split ✂️
+```
+
+| Parameter | Default | Description |
+|---|---|---|
+| `minDuration` | `30s` | Chunk won't split before this time |
+| `maxDuration` | `300s` | Chunk always splits after this time |
+| `minSilenceDuration` | `1s` | Silence must last this long to trigger a split |
+| `silenceThreshold` | `-50 dB` | Audio below this level is considered silence |
+
+All four values are configurable:
+
+```ts
+recorder.create(stream, {
+  timeslice: 250,
+  silenceThreshold: -45,
+  chunkOptions: {
+    minDuration: 10,
+    maxDuration: 60,
+    minSilenceDuration: 1.5,
+  },
+})
+```
+
+---
+
+## API
+
+### `new AudioChunkify()`
+
+Creates a new instance. No arguments required.
+
+---
+
+### `.create(stream, options?)`
+
+Initialises the recorder. Must be called before `start()`.
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `mimeType` | `string` | auto | Force a specific MIME type (e.g. `'audio/webm;codecs=opus'`). Auto-detected if omitted. |
+| `timeslice` | `number` | — | Millisecond interval for internal `ondataavailable` events |
+| `silenceThreshold` | `number` | `-50` | dB threshold for silence detection |
+| `chunkOptions.minDuration` | `number` | `30` | Minimum chunk duration in seconds |
+| `chunkOptions.maxDuration` | `number` | `300` | Maximum chunk duration in seconds |
+| `chunkOptions.minSilenceDuration` | `number` | `1` | Seconds of silence required to trigger a split |
+
+Returns the underlying `MediaRecorder` instance.
+
+---
+
+### `.start(timeslice?)` / `.pause()` / `.resume()` / `.stop()`
+
+Control the recording lifecycle. Pause/resume correctly accounts for paused time when calculating chunk durations.
+
+---
+
+### `.addAudioStream(stream)` / `.removeAudioStream(stream)`
+
+Dynamically add or remove streams from the mix at any time. The internal `AudioContext` graph is rebuilt transparently.
+
+---
+
+### `.destroy(options?)`
+
+Stops recording, closes internal `AudioContext` instances, and clears all state. Always call this when done to avoid memory leaks.
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `stopStreams` | `boolean` | `true` | When `true`, calls `stop()` on every track of the streams you passed to `create()` / `addAudioStream()`. Set to `false` to keep those streams alive (e.g. reuse the same microphone for another recording). |
+
+By default, `destroy()` releases the microphone and any other input tracks — same as today. If you own the `MediaStream` and want to keep it after teardown:
+
+```ts
+recorder.stop()
+recorder.destroy({ stopStreams: false })
+
+// stream is still active — safe to pass to a new AudioChunkify instance
+const next = new AudioChunkify()
+next.create(stream)
+```
+
+When unmounting a component or leaving a page, keep the default (`stopStreams: true`) so the browser releases the mic indicator.
+
+---
+
+### State & metadata
+
+| Method | Returns | Description |
+|---|---|---|
+| `.getState()` | `'inactive' \| 'recording' \| 'paused'` | Current state |
+| `.getMimeType()` | `string \| null` | Active MIME type |
+| `.getStream()` | `MediaStream \| null` | The mixed audio stream |
+| `.getMediaRecorder()` | `MediaRecorder \| null` | The underlying `MediaRecorder` |
+| `.getRecordingTime()` | `number` | Elapsed seconds (excludes paused time) |
+| `.getSilenceTime()` | `number` | Continuous silence in seconds |
+| `.getSilenceThreshold()` | `number` | Current dB threshold |
+| `.setSilenceThreshold(dB)` | `void` | Update the dB threshold (must be negative) |
+| `.getCurrentChunkIndex()` | `number` | Zero-based index of the current chunk |
+| `.getAudioChunks()` | `Blob[]` | Current internal chunk buffer |
+
+---
+
+### Events
+
+All `on*` methods return `this` for chaining.
+
+```ts
+recorder
+  .onStart(() => setUI('recording'))
+  .onPause(() => setUI('paused'))
+  .onResume(() => setUI('recording'))
+  .onStop(() => setUI('idle'))
+  .onTimeUpdate((seconds) => setTimer(seconds))
+  .onSilenceDetected(() => console.log('silence…'))
+  .onAudioDetected(() => console.log('audio resumed'))
+  .onError((e) => console.error(e))
+  .onChunkProcessed(async ({ file, index, duration, isLastChunk }) => {
+    await upload(file)
+  })
+```
+
+#### `onChunkProcessed` payload
+
+```ts
+interface ChunkProcessedPayload {
+  file: File        // Named "chunk-{index}.{ext}" with correct MIME type
+  index: number     // Zero-based chunk index within the session
+  duration: number  // Duration of this chunk in seconds
+  isLastChunk: boolean // true only when triggered by stop()
+}
+```
+
+---
+
+## Recipes
+
+### Microphone only
+
+```ts
+import { AudioChunkify } from 'audio-chunkify'
+
+const stream = await navigator.mediaDevices.getUserMedia({ audio: true })
+const recorder = new AudioChunkify()
+
+recorder.create(stream)
+recorder.onChunkProcessed(async ({ file, isLastChunk }) => {
+  await uploadChunk(file)
+})
+recorder.start()
+```
+
+### Mix microphone + system audio
+
+```ts
+const mic = await navigator.mediaDevices.getUserMedia({ audio: true })
+const system = await navigator.mediaDevices.getDisplayMedia({ audio: true, video: false })
+
+const recorder = new AudioChunkify()
+recorder.create(mic)
+recorder.addAudioStream(system)
+recorder.start()
+```
+
+### Short chunks for real-time transcription
+
+```ts
+recorder.create(stream, {
+  timeslice: 200,
+  silenceThreshold: -40,
+  chunkOptions: {
+    minDuration: 5,
+    maxDuration: 15,
+    minSilenceDuration: 0.5,
+  },
+})
+
+recorder.onChunkProcessed(async ({ file }) => {
+  const transcript = await transcribeAudio(file) // send to Whisper, etc.
+  appendToTranscript(transcript)
+})
+```
+
+### React hook
+
+```tsx
+import { useEffect, useRef, useState } from 'react'
+import { AudioChunkify } from 'audio-chunkify'
+
+export function useAudioChunkify() {
+  const recorder = useRef(new AudioChunkify())
+  const [state, setState] = useState<'idle' | 'recording' | 'paused'>('idle')
+  const [elapsed, setElapsed] = useState(0)
+
+  async function start() {
+    const stream = await navigator.mediaDevices.getUserMedia({ audio: true })
+
+    recorder.current
+      .create(stream, { timeslice: 250 })
+      .onStart(() => setState('recording'))
+      .onPause(() => setState('paused'))
+      .onResume(() => setState('recording'))
+      .onStop(() => { setState('idle'); setElapsed(0) })
+      .onTimeUpdate(setElapsed)
+      .onChunkProcessed(async ({ file, isLastChunk }) => {
+        await uploadChunk(file)
+      })
+
+    recorder.current.start()
+  }
+
+  useEffect(() => () => { recorder.current.destroy() }, [])
+
+  return {
+    state,
+    elapsed,
+    start,
+    pause: () => recorder.current.pause(),
+    resume: () => recorder.current.resume(),
+    stop: () => recorder.current.stop(),
+  }
+}
+```
+
+---
+
+## Browser support
+
+Requires the [MediaRecorder API](https://developer.mozilla.org/en-US/docs/Web/API/MediaRecorder) and [Web Audio API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API). Supported in all modern browsers (Chrome, Firefox, Safari 14.1+, Edge).
+
+Not supported in Node.js or non-browser environments.
+
+---
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,257 @@
+/**
+ * Options passed to AudioRecorder.create()
+ */
+interface RecorderCreateOptions {
+    /**
+     * Explicit MIME type to use (e.g. 'audio/webm;codecs=opus').
+     * If omitted the library auto-detects the best supported type.
+     */
+    mimeType?: string;
+    /**
+     * Millisecond interval for ondataavailable events.
+     * Passed directly to MediaRecorder.start(timeslice).
+     */
+    timeslice?: number;
+    /**
+     * Silence detection threshold in dB (negative value, e.g. -50).
+     * Audio below this level is considered silence.
+     * @default -50
+     */
+    silenceThreshold?: number;
+    /**
+     * Overrides for chunk-splitting timing constants.
+     */
+    chunkOptions?: Partial<ChunkOptions>;
+}
+/**
+ * Chunk splitting timing configuration.
+ */
+interface ChunkOptions {
+    /** Maximum chunk duration in seconds before a forced split. @default 300 */
+    maxDuration: number;
+    /** Minimum chunk duration in seconds before silence-based split is allowed. @default 30 */
+    minDuration: number;
+    /** Minimum continuous silence (seconds) needed to trigger a split. @default 1 */
+    minSilenceDuration: number;
+}
+/**
+ * Payload delivered to the onChunkProcessed callback.
+ */
+interface ChunkProcessedPayload {
+    /** File object for the audio chunk, named chunk-{index}.{ext} */
+    file: File;
+    /** Zero-based index of this chunk in the current recording session */
+    index: number;
+    /** Duration of this chunk in seconds */
+    duration: number;
+    /** true when this is the final chunk (recorder was stopped) */
+    isLastChunk: boolean;
+}
+/**
+ * Recorder state — mirrors the native MediaRecorder.state values.
+ */
+type RecorderState = 'inactive' | 'recording' | 'paused';
+/**
+ * Options passed to AudioChunkify.destroy().
+ */
+interface DestroyOptions {
+    /**
+     * When `true` (default), calls `stop()` on every track of the streams
+     * passed to `create()` / `addAudioStream()`. Set to `false` when you
+     * plan to reuse those streams after tearing down the recorder
+     * (e.g. start a new recording with the same microphone).
+     */
+    stopStreams?: boolean;
+}
+
+/**
+ * AudioChunkify
+ *
+ * A framework-agnostic MediaRecorder wrapper that adds:
+ * - Automatic MIME type detection
+ * - Multi-stream mixing via AudioContext
+ * - Silence detection with configurable threshold
+ * - Automatic chunk splitting (time + silence based)
+ * - Recording time tracking
+ * - Pause/resume with correct duration accounting
+ */
+declare class AudioChunkify {
+    private _mediaRecorder;
+    private _stream;
+    private _audioStreams;
+    private _mimeType;
+    private _timeslice;
+    private _onDataAvailableCallback;
+    private _onStartCallback;
+    private _onPauseCallback;
+    private _onResumeCallback;
+    private _onStopCallback;
+    private _onErrorCallback;
+    private _recordingTime;
+    private _intervalId;
+    private _onTimeUpdateCallback;
+    private _audioContext;
+    private _analyserNode;
+    private _sourceNode;
+    private _silenceTime;
+    private _silenceIntervalId;
+    private _silenceCheckIntervalId;
+    private _silenceThreshold;
+    private _isInSilence;
+    private _onSilenceDetectedCallback;
+    private _onAudioDetectedCallback;
+    private _mixedStreamContext;
+    private _mixedStreamDestination;
+    private _mixedStreamSourceNodes;
+    private _audioChunks;
+    private _currentChunkIndex;
+    private _processingChunk;
+    private _isChunkSplit;
+    private _lastChunkEnd;
+    private _silenceStartForChunking;
+    private _chunkSplitIntervalId;
+    private _onChunkProcessedCallback;
+    private _pauseStartTime;
+    private _totalPausedTime;
+    private _chunkOptions;
+    /**
+     * Initialises the recorder with the given stream and options.
+     *
+     * @example
+     * const recorder = new AudioChunkify()
+     * const stream = await navigator.mediaDevices.getUserMedia({ audio: true })
+     * recorder.create(stream, { timeslice: 250 })
+     */
+    create(stream: MediaStream, options?: RecorderCreateOptions): MediaRecorder;
+    /** Starts recording. Optionally overrides the timeslice set in create(). */
+    start(timeslice?: number): void;
+    /** Pauses an active recording. */
+    pause(): void;
+    /** Resumes a paused recording. */
+    resume(): void;
+    /** Stops the recording and finalises all pending chunks. */
+    stop(): void;
+    /**
+     * Dynamically mixes in an additional audio stream.
+     * The recorder is briefly restarted to rebuild the AudioContext graph.
+     */
+    addAudioStream(stream: MediaStream): void;
+    /**
+     * Removes a previously added audio stream from the mix.
+     * At least one stream must remain — call destroy() to tear everything down.
+     */
+    removeAudioStream(stream: MediaStream): void;
+    /** Current recorder state: 'inactive' | 'recording' | 'paused' */
+    getState(): RecorderState;
+    /** Active MIME type (resolved at create() time). */
+    getMimeType(): string | null;
+    /** The mixed MediaStream used internally by the recorder. */
+    getStream(): MediaStream | null;
+    /** The underlying MediaRecorder instance. */
+    getMediaRecorder(): MediaRecorder | null;
+    /** Elapsed recording time in seconds (excludes paused time). */
+    getRecordingTime(): number;
+    /** Resets the elapsed recording time counter to zero. */
+    resetRecordingTime(): void;
+    /** Current continuous silence duration in seconds. */
+    getSilenceTime(): number;
+    /** Current silence detection threshold in dB. */
+    getSilenceThreshold(): number;
+    /**
+     * Updates the silence detection threshold.
+     * @param threshold — Must be a negative number in dB (e.g. -50).
+     */
+    setSilenceThreshold(threshold: number): void;
+    /** Accumulated audio chunks since the last start() or split. */
+    getAudioChunks(): Blob[];
+    /** Zero-based index of the current chunk. */
+    getCurrentChunkIndex(): number;
+    /** Clears the internal chunk buffer. */
+    clearAudioChunks(): void;
+    onDataAvailable(callback: (event: BlobEvent) => void): this;
+    onStart(callback: () => void): this;
+    onPause(callback: () => void): this;
+    onResume(callback: () => void): this;
+    onStop(callback: () => void): this;
+    onError(callback: (event: Event) => void): this;
+    onTimeUpdate(callback: (seconds: number) => void): this;
+    onSilenceDetected(callback: () => void): this;
+    onAudioDetected(callback: () => void): this;
+    /**
+     * Called each time a chunk is finalised (either by splitting or on stop).
+     *
+     * @example
+     * recorder.onChunkProcessed(async ({ file, index, duration, isLastChunk }) => {
+     *   await uploadChunk(file)
+     *   if (isLastChunk) console.log('Recording complete')
+     * })
+     */
+    onChunkProcessed(callback: (payload: ChunkProcessedPayload) => Promise<void> | void): this;
+    /**
+     * Fully tears down the recorder: stops recording, closes AudioContexts
+     * and clears all internal state.
+     *
+     * By default also stops every track on the input streams. Pass
+     * `{ stopStreams: false }` to keep those streams alive for reuse.
+     */
+    destroy(options?: DestroyOptions): void;
+    private _assertReady;
+    private _assertCallback;
+    private _captureState;
+    private _restoreState;
+    private _now;
+    private _startTimeTracking;
+    private _stopTimeTracking;
+    private _pauseTimeTracking;
+    private _resumeTimeTracking;
+    private _setupAudioAnalysis;
+    private _cleanupAudioAnalysis;
+    /**
+     * Measures the current audio level in dBFS via time-domain RMS.
+     * Shared by silence events and chunk-splitting logic.
+     */
+    private _measureAudioLevelDb;
+    private _isCurrentlySilent;
+    private _checkSilence;
+    private _startSilenceChecking;
+    private _stopSilenceTracking;
+    private _shouldSplitChunk;
+    private _restartRecorderSegment;
+    private _startChunkSplitting;
+    private _stopChunkSplitting;
+    private _createMixedStream;
+    private _recreateMediaRecorder;
+    private _cleanupMixedStream;
+    private _setupEventHandlers;
+    private _processChunk;
+}
+
+/**
+ * Returns the first audio MIME type supported by the current browser,
+ * or null if MediaRecorder is unavailable.
+ */
+declare function getCompatibleMimeType(): string | null;
+/**
+ * Derives a file extension from a MIME type string.
+ * Falls back to 'webm' if the type is unrecognised.
+ */
+declare function getFileExtensionFromMimeType(mimeType: string | null): string;
+
+/**
+ * Default audio analysis and chunking constants.
+ * All values can be overridden via RecorderOptions.
+ */
+declare const DEFAULT_AUDIO_CONSTANTS: {
+    /** FFT size for the AnalyserNode (must be a power of 2). Affects frequency resolution. */
+    readonly ANALYSIS_BUFFER_SIZE: 2048;
+    /** Silence threshold in dB used for chunk splitting (-Infinity to 0). */
+    readonly SILENCE_THRESHOLD: -50;
+    /** Maximum chunk duration in seconds before a forced split. */
+    readonly MAX_CHUNK_DURATION: 300;
+    /** Minimum chunk duration in seconds before a silence-based split is allowed. */
+    readonly MIN_CHUNK_DURATION: 30;
+    /** Minimum continuous silence duration in seconds required to trigger a split. */
+    readonly MIN_SILENCE_DURATION: 1;
+};
+
+export { AudioChunkify, type ChunkOptions, type ChunkProcessedPayload, DEFAULT_AUDIO_CONSTANTS, type DestroyOptions, type RecorderCreateOptions, type RecorderState, getCompatibleMimeType, getFileExtensionFromMimeType };