https://jacoblincool.github.io/awesome-recorder/
Effortless audio recording with built-in Voice Activity Detection and optimized MP3/WAV/PCM outputs in modern browsers.
https://jacoblincool.github.io/awesome-recorder/
audio-recorder browser mp3 vad
Last synced: 3 months ago
JSON representation
Effortless audio recording with built-in Voice Activity Detection and optimized MP3/WAV/PCM outputs in modern browsers.
- Host: GitHub
- URL: https://jacoblincool.github.io/awesome-recorder/
- Owner: JacobLinCool
- License: mit
- Created: 2025-03-04T17:25:18.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-04-04T18:09:19.000Z (over 1 year ago)
- Last Synced: 2026-05-06T04:04:29.594Z (3 months ago)
- Topics: audio-recorder, browser, mp3, vad
- Language: TypeScript
- Homepage: https://jacoblincool.github.io/awesome-recorder/
- Size: 120 KB
- Stars: 2
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# 🎙️ Awesome Recorder
[](https://www.npmjs.com/package/awesome-recorder)
> **Effortless audio recording with built-in Voice Activity Detection and optimized MP3 outputs in modern browsers.**
`awesome-recorder` is a lightweight, powerful JavaScript library designed for seamless audio capture directly in the browser. It automatically segments speech using advanced Voice Activity Detection (VAD), encoding spoken audio into compact MP3 files—perfect for web apps, voice assistants, transcription services, and more.
## ✨ Key Features
- 🎤 **Automatic Voice Activity Detection** — Precisely detects and segments speech.
- 📦 **Compact MP3 Encoding** — Small, optimized MP3 audio outputs. (WAV or raw PCM also supported)
- ⚡ **Simple Async API** — Easy-to-use with async generators and async/await.
- 🚀 **Event-Driven** — Real-time speech state notifications.
- 🛠️ **Full TypeScript Support** — Complete type definitions included.
- 🌐 **WebAssembly Optimized** — Ultra-lightweight custom FFmpeg WASM (~1.2 MB).
## 🚩 Installation
```bash
npm install awesome-recorder
# or
yarn add awesome-recorder
# or
pnpm add awesome-recorder
```
## 🧑💻 Quick Start
```typescript
import { Recorder } from "awesome-recorder";
const recorder = new Recorder();
// Listen for speech state changes (optional)
recorder.on("speechStateChanged", ({ isSpeaking }) => {
console.log(`User is speaking: ${isSpeaking}`);
});
// Start capturing audio segments
async function startRecording() {
try {
// Choose output format: "mp3" (default), "wav", or "pcm"
for await (const audioChunk of recorder.start("mp3")) {
console.log("Detected speech segment:", audioChunk);
// Play audio directly in browser (MP3/WAV only)
const audio = new Audio(URL.createObjectURL(audioChunk));
audio.play();
// Or trigger immediate download
const link = document.createElement("a");
link.href = URL.createObjectURL(audioChunk);
link.download = `speech-${Date.now()}.mp3`;
link.click();
}
} catch (error) {
console.error("Recording Error:", error);
}
}
// Stop recording gracefully
function stopRecording() {
recorder.stop();
}
```
## 📚 API Reference
### `Recorder` Class
Main class for handling recording and voice detection.
```typescript
new Recorder(vadOptions?: Partial & { preprocessAudio?: (audio: Float32Array) => Float32Array });
```
#### Options
- **`preprocessAudio`**
Optional callback to process audio data before encoding.
Default behavior trims the last 2000 samples.
You can remove unwanted tail noise, apply custom modifications, or access raw audio data with this callback.
#### Methods
- **`.preload(): Promise`**
Preloads the VAD model and FFmpeg WASM module.
- **`.start(outputFormat?: "mp3" | "wav" | "pcm"): AsyncGenerator`**
Starts audio recording, yielding segments upon speech detection:
- `"mp3"` (default): MP3 files
- `"wav"`: WAV files
- `"pcm"`: Raw PCM audio as Float32Array (16kHz sample rate)
- **`.stop(): Promise`**
Stops audio recording.
- **`.on(event: string, callback: Function): void`**
Subscribes to recorder events.
- **`.off(event: string, callback: Function): void`**
Unsubscribes from recorder events.
#### Events
- **`speechStateChanged`**
Emitted with `{ isSpeaking: boolean }` when speech state changes.
## 🌐 WebAssembly Optimized
By default, `awesome-recorder` uses an optimized, custom FFmpeg WASM build from [`@hinagiku/ffmpeg-core`](https://www.npmjs.com/package/@hinagiku/ffmpeg-core), specifically tailored for minimal size (~1.2 MB). However, you can easily use your own custom build if preferred:
```typescript
import { setCoreURL, setWasmURL } from "awesome-recorder";
setCoreURL("https://your-cdn.com/ffmpeg-core.js");
setWasmURL("https://your-cdn.com/ffmpeg-core.wasm");
```
## 🚀 Advanced Usage
### Custom Voice Activity Detection Options
Fine-tune detection sensitivity and timing:
```typescript
const recorder = new Recorder({
positiveSpeechThreshold: 0.9,
negativeSpeechThreshold: 0.7,
minSpeechFrames: 5,
preSpeechPadFrames: 15,
redemptionFrames: 10,
});
```
See the [`@ricky0123/vad-web` Documentation](https://docs.vad.ricky0123.com/user-guide/api/#micvad) for detailed configuration options.
## ☁️ Uploading Audio Segments
Stream recorded segments directly to your backend:
```typescript
async function streamSegments(recorder: Recorder) {
let segmentCount = 0;
for await (const audioFile of recorder.start()) {
segmentCount++;
const formData = new FormData();
formData.append("segment", audioFile);
fetch("/api/upload-segment", {
method: "POST",
body: formData,
})
.then((res) => res.json())
.then((data) => console.log(`Uploaded segment ${segmentCount}:`, data))
.catch((err) => console.error("Upload failed:", err));
}
}
```
## 🌍 Browser Compatibility
Compatible with modern browsers supporting:
- ✅ WebAssembly (WASM)
- ✅ Web Audio API (`AudioContext`)
- ✅ MediaDevices API
## ⚠️ Notes for Bundlers
### Vite
When using Vite, exclude `@ffmpeg/ffmpeg` from dependency optimization:
```js
// vite.config.js
export default {
optimizeDeps: {
exclude: ["@ffmpeg/ffmpeg"],
},
};
```
## 🔍 Example Project
Check out the practical demo in the [example](./example/) directory:
- **[👉 Simple Recorder Demo](https://jacoblincool.github.io/awesome-recorder/)**
## 📄 License
Released under the **MIT License**.
✨ **Enjoy effortless, efficient, and powerful audio recording in your web apps!** ✨