@mastra/node-audio

Cross-platform audio I/O toolkit for Node.js — play audio, stream microphone input, and record to disk. Designed for use with voice-enabled agents like Mastra.

🎧 Features

- ✅ Play audio from file, URL, or stream
- 🎤 Get microphone stream with sane defaults
- 📼 Record audio to disk using ffmpeg
- 🔄 Unified createHuddle API for mic/speaker coordination
- 🧰 Built on node-mic, @mastra/node-speaker, and fluent-ffmpeg

🚀 Getting Started

$3

``bash
npm install @mastra/node-audio
`

$3

This package wraps native audio libraries. You may need additional system dependencies:

#### 🖥 Speaker
- Docs: node-speaker - Audio selection

#### 🎙 Microphone Input
- Docs: node-mic

#### 💾 Recording Audio
- Docs: fluent-ffmpeg
- You must have ffmpeg installed and available in your system path

`bash


macOS

brew install ffmpeg

Debian/Ubuntu

sudo apt-get install ffmpeg

Windows

choco install ffmpeg
`

📚 API Reference

$3

Plays a local file, URL, or raw audio stream.

`ts
import { playAudio } from "@mastra/node-audio";

playAudio("./response.wav");
`

You can also pass a stream:

`ts
const stream = fs.createReadStream("./hello.wav");
playAudio(stream);
`

$3

Starts recording from the default system mic and returns a stream.

`ts
import { getMicrophoneStream } from "@mastra/node-audio";

const micStream = getMicrophoneStream({ rate: 24100 });
micStream.pipe(fs.createWriteStream("raw_input.pcm"));
`

$3


Records audio from a stream to disk using ffmpeg.

`ts
import { getMicrophoneStream, recordAudioToFile } from "@mastra/node-audio";

const mic = getMicrophoneStream();
const recorder = recordAudioToFile(mic, "output.mp3");

// Optionally stop recording later:
// recorder.stream.end();
`

$3

Unified helper for managing mic + speaker + recording.

`ts
import { createHuddle } from "@mastra/node-audio";

const huddle = createHuddle({
mic: { rate: 24100 },
speaker: { sampleRate: 24100 },
record: { outputPath: "session.mp3" },
});

huddle.start();

// Stream mic to agent
const micStream = huddle.getMicrophoneStream();
agent.voice.send(micStream);

// Play response from agent
agent.voice.on("speaker", (stream) => {
huddle.play(stream);
});

// Gracefully stop
huddle.stop();
`

🛠 Development

Build both ESM and CommonJS outputs:

`bash
npm run build
``