Implementation:Openai Openai node Audio Helpers

Knowledge Sources	Openai_Openai_node
Domains	SDK, Audio
Last Updated	2026-02-15 12:00 GMT

Overview

The audio helpers module provides playAudio and recordAudio convenience functions for playing and recording audio in Node.js environments using ffplay and ffmpeg.

Description

This module exposes two high-level audio utility functions designed for Node.js server-side use. Both functions depend on external FFmpeg tools being installed on the system.

playAudio accepts a NodeJS.ReadableStream, a Response object, or a File and pipes the audio data to ffplay (a command-line media player from the FFmpeg suite) via stdin. It handles all three input types transparently: Response objects have their body piped directly, File objects are converted to a Readable stream, and raw readable streams are piped as-is. The function returns a Promise<void> that resolves when playback completes or rejects if ffplay exits with a non-zero code.

recordAudio uses ffmpeg to capture audio from the system's default input device. It automatically selects the platform-appropriate recording provider (avfoundation on macOS, dshow on Windows, alsa on Linux and other Unix-like systems). It records at 24kHz mono WAV format by default and returns a Promise<File>. Recording can be stopped via an AbortSignal or a timeout in milliseconds, both of which send SIGTERM to the ffmpeg process.

Both functions are Node.js-only and throw descriptive errors when invoked in a browser environment, suggesting the wavtools npm package as a browser-compatible alternative.

Usage

Use these helpers for quick audio playback of TTS responses or audio recording for transcription workflows in Node.js applications. Both require FFmpeg to be installed and available on the system PATH.

Code Reference

Source Location

• Repository: openai-node
• File: src/helpers/audio.ts

Signature

export async function playAudio(input: NodeJS.ReadableStream | Response | File): Promise<void>;

export async function recordAudio(options?: RecordAudioOptions): Promise<File>;

type RecordAudioOptions = {
  signal?: AbortSignal;
  device?: number;
  timeout?: number;
};

Import

import { playAudio, recordAudio } from 'openai/helpers/audio';

I/O Contract

Inputs (playAudio)

Name	Type	Required	Description
input	Response | File	Yes	The audio source to play. Can be a readable stream, a fetch Response (e.g., from the speech API), or a File object.

Inputs (recordAudio)

Name	Type	Required	Description
signal	AbortSignal	No	An abort signal to stop recording externally.
device	number	No	The audio input device index. Defaults to 0.
timeout	number	No	Maximum recording duration in milliseconds. Uses AbortSignal.timeout() internally.

Outputs

Name	Type	Description
playAudio return	Promise<void>	Resolves when playback completes. Rejects if ffplay exits with a non-zero code.
recordAudio return	Promise<File>	A File object named "audio.wav" with MIME type "audio/wav" containing the recorded audio at 24kHz mono.

Usage Examples

import OpenAI from 'openai';
import { playAudio, recordAudio } from 'openai/helpers/audio';

const client = new OpenAI();

// Play audio from the TTS API
const speechResponse = await client.audio.speech.create({
  model: 'tts-1',
  voice: 'alloy',
  input: 'Hello, world!',
});
await playAudio(speechResponse);

// Record audio with a 10-second timeout
const audioFile = await recordAudio({ timeout: 10000 });
console.log('Recorded:', audioFile.name, audioFile.size, 'bytes');

// Record until manually stopped via AbortController
const controller = new AbortController();
setTimeout(() => controller.abort(), 5000); // stop after 5 seconds
const recording = await recordAudio({ signal: controller.signal });

// Use recorded audio for transcription
const transcription = await client.audio.transcriptions.create({
  model: 'whisper-1',
  file: recording,
});
console.log(transcription.text);

Related Pages

• Environment:Openai_Openai_node_Node_20_Runtime