0
# PvRecorder Node
1

2
PvRecorder is a cross-platform audio recorder library designed for real-time speech audio processing in Node.js applications. It provides frame-based audio capture with configurable buffer sizes, supporting multiple platforms including Linux, macOS, Windows, and Raspberry Pi. The library offers both synchronous and asynchronous APIs for reading audio frames, automatic device enumeration and selection capabilities, and proper resource management.
3

4
## Package Information
5

6
- **Package Name**: @picovoice/pvrecorder-node
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @picovoice/pvrecorder-node`
10

11
## Core Imports
12

13
```typescript
14
import { PvRecorder } from "@picovoice/pvrecorder-node";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { PvRecorder } = require("@picovoice/pvrecorder-node");
21
```
22

23
## Basic Usage
24

25
```typescript
26
import { PvRecorder } from "@picovoice/pvrecorder-node";
27

28
// Initialize recorder with frame length (required) and optional device index
29
const recorder = new PvRecorder(512); // 512 samples per frame
30
// or with specific device: new PvRecorder(512, deviceIndex);
31

32
// Start recording
33
recorder.start();
34

35
// Read audio frames
36
while (recorder.isRecording) {
37
  // Asynchronous read
38
  const frame = await recorder.read();
39
  console.log(`Received ${frame.length} audio samples`);
40
  
41
  // Or synchronous read
42
  // const frame = recorder.readSync();
43
  
44
  // Process frame (Int16Array with frameLength samples)
45
  // ... your audio processing logic
46
}
47

48
// Stop recording
49
recorder.stop();
50

51
// Clean up resources
52
recorder.release();
53
```
54

55
## Architecture
56

57
PvRecorder is built around several key components:
58

59
- **Native Audio Interface**: Cross-platform native modules for audio device access using platform-specific libraries
60
- **Frame-based Processing**: Fixed-size audio frames (Int16Array) for consistent real-time processing
61
- **Device Management**: Automatic device enumeration and selection with platform-specific optimizations
62
- **Resource Management**: Explicit lifecycle management with start/stop/release methods
63
- **Dual APIs**: Both synchronous and asynchronous reading patterns for different use cases
64
- **Platform Abstraction**: Automatic runtime platform detection (Linux, macOS, Windows, Raspberry Pi) and dynamic native library loading based on architecture and OS
65
- **Error Handling**: Comprehensive status code mapping from native library to JavaScript errors with descriptive messages
66

67
## Capabilities
68

69
### Audio Recording
70

71
Core audio recording functionality providing frame-based audio capture from system audio devices.
72

73
```typescript { .api }
74
/**
75
 * PvRecorder constructor
76
 * @param frameLength - Length of audio frames to receive per read call
77
 * @param deviceIndex - Audio device index (-1 for default device, defaults to -1)
78
 * @param bufferedFramesCount - Number of frames buffered internally (defaults to 50)
79
 */
80
constructor(
81
  frameLength: number,
82
  deviceIndex: number = -1,
83
  bufferedFramesCount: number = 50
84
);
85

86
/** Start recording audio */
87
start(): void;
88

89
/** Stop recording audio */
90
stop(): void;
91

92
/** Asynchronously read a frame of audio data */
93
read(): Promise<Int16Array>;
94

95
/** Synchronously read a frame of audio data */
96
readSync(): Int16Array;
97

98
/** Release resources acquired by PvRecorder */
99
release(): void;
100
```
101

102
### Device Management
103

104
Audio device enumeration and selection capabilities for choosing specific recording devices.
105

106
```typescript { .api }
107
/** 
108
 * Get list of available audio device names 
109
 * @throws {Error} When failed to retrieve audio devices
110
 */
111
static getAvailableDevices(): string[];
112

113
/** 
114
 * Get name of the currently selected audio device 
115
 * @throws {Error} When failed to get selected device information
116
 */
117
getSelectedDevice(): string;
118
```
119

120
### Configuration and Monitoring
121

122
Configuration options and runtime monitoring capabilities for optimal recording performance.
123

124
```typescript { .api }
125
/** Enable or disable debug logging for buffer overflows and silence detection */
126
setDebugLogging(isDebugLoggingEnabled: boolean): void;
127

128
/** Get length of audio frames per read call */
129
get frameLength(): number;
130

131
/** Get audio sample rate used by PvRecorder */
132
get sampleRate(): number;
133

134
/** Get version of the PvRecorder library */
135
get version(): string;
136

137
/** Check if PvRecorder is currently recording */
138
get isRecording(): boolean;
139
```
140

141
## Error Handling
142

143
PvRecorder operations can throw errors for various failure conditions. All errors are thrown as standard JavaScript `Error` objects with descriptive messages:
144

145
- Invalid constructor parameters (device index, frame length, buffer size)
146
- Audio backend/driver failures
147
- Device initialization problems
148
- Input/output operation failures
149
- Memory allocation issues
150

151
```typescript
152
try {
153
  const recorder = new PvRecorder(512, invalidDeviceIndex);
154
  recorder.start();
155
  const frame = await recorder.read();
156
} catch (error) {
157
  console.error("PvRecorder operation failed:", error.message);
158
  // Handle error appropriately for your use case
159
}
160
```
161

162
## Platform Support
163

164
- **Node.js**: 18.0.0 or higher (as specified in package.json engines field)
165
- **Platforms**: Linux (x86_64), macOS (x86_64, arm64), Windows (x86_64, arm64)
166
- **Raspberry Pi**: Models 3, 4, 5 with ARM Cortex-A53, A72, A76 processors
167
- **Architectures**: Automatic platform detection and native library loading
168

169
## Advanced Usage Examples
170

171
### Device Selection
172

173
```typescript
174
import { PvRecorder } from "@picovoice/pvrecorder-node";
175

176
// List available audio devices
177
const devices = PvRecorder.getAvailableDevices();
178
console.log("Available devices:", devices);
179

180
// Select specific device by index
181
const recorder = new PvRecorder(512, 0); // Use first device
182
console.log("Selected device:", recorder.getSelectedDevice());
183
```
184

185
### Streaming Audio Processing
186

187
```typescript
188
import { PvRecorder } from "@picovoice/pvrecorder-node";
189

190
const recorder = new PvRecorder(512);
191
recorder.setDebugLogging(true); // Enable debug logging
192

193
recorder.start();
194

195
// Process audio in streaming fashion
196
const processAudio = async () => {
197
  while (recorder.isRecording) {
198
    try {
199
      const frame = await recorder.read();
200
      
201
      // Example: Calculate RMS (root mean square) for volume detection
202
      const rms = Math.sqrt(
203
        frame.reduce((sum, sample) => sum + sample * sample, 0) / frame.length
204
      );
205
      
206
      if (rms > 1000) { // Threshold for voice activity
207
        console.log("Voice detected, RMS:", rms);
208
        // Process speech audio...
209
      }
210
    } catch (error) {
211
      console.error("Audio read error:", error);
212
      break;
213
    }
214
  }
215
};
216

217
processAudio();
218

219
// Stop after 10 seconds
220
setTimeout(() => {
221
  recorder.stop();
222
  recorder.release();
223
}, 10000);
224
```
225

226
### Buffered Recording with Custom Buffer Size
227

228
```typescript
229
import { PvRecorder } from "@picovoice/pvrecorder-node";
230

231
// Use larger internal buffer for high-throughput scenarios
232
const recorder = new PvRecorder(
233
  1024,  // Larger frame size
234
  -1,    // Default device
235
  100    // Larger buffer (100 frames)
236
);
237

238
console.log(`Sample rate: ${recorder.sampleRate} Hz`);
239
console.log(`Frame length: ${recorder.frameLength} samples`);
240
console.log(`Library version: ${recorder.version}`);
241

242
recorder.start();
243

244
// Synchronous reading for low-latency scenarios
245
const frames = [];
246
for (let i = 0; i < 100; i++) {
247
  frames.push(recorder.readSync());
248
}
249

250
recorder.stop();
251
recorder.release();
252

253
console.log(`Recorded ${frames.length} frames of audio`);
254
```
255

256
### Error Handling and Validation
257

258
```typescript
259
import { PvRecorder } from "@picovoice/pvrecorder-node";
260

261
// Test for invalid constructor parameters as shown in test suite
262
try {
263
  // Invalid device index (must be >= -1)
264
  const recorder1 = new PvRecorder(512, -2);
265
} catch (error) {
266
  console.error("Invalid device index:", error.message);
267
}
268

269
try {
270
  // Invalid frame length (must be > 0)
271
  const recorder2 = new PvRecorder(0, 0);
272
} catch (error) {
273
  console.error("Invalid frame length:", error.message);
274
}
275

276
try {
277
  // Invalid buffered frames count (must be > 0)
278
  const recorder3 = new PvRecorder(512, 0, 0);
279
} catch (error) {
280
  console.error("Invalid buffered frames count:", error.message);
281
}
282

283
// Valid usage with proper error handling
284
const recorder = new PvRecorder(512, 0);
285

286
// Test recorder state management
287
console.log("Before start:", recorder.isRecording); // false
288
recorder.start();
289
console.log("After start:", recorder.isRecording);  // true
290

291
recorder.stop();
292
console.log("After stop:", recorder.isRecording);   // false
293

294
recorder.release();
295
```