Repository navigation
Expand file tree
/
Copy pathvoice.ts
More file actions
525 lines (464 loc) · 16.7 KB
/
Copy pathvoice.ts
File metadata and controls
525 lines (464 loc) · 16.7 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
// Voice service: audio recording for push-to-talk voice input.
//
// Recording uses native audio capture (cpal) on macOS, Linux, and Windows
// for in-process mic access. Falls back to SoX `rec` or arecord (ALSA)
// on Linux if the native module is unavailable.
import { type ChildProcess, spawn, spawnSync } from 'child_process'
import { readFile } from 'fs/promises'
import { logForDebugging } from '../utils/debug.js'
import { isEnvTruthy, isRunningOnHomespace } from '../utils/envUtils.js'
import { logError } from '../utils/log.js'
import { getPlatform } from '../utils/platform.js'
// Lazy-loaded native audio module. audio-capture.node links against
// CoreAudio.framework + AudioUnit.framework; dlopen is synchronous and
// blocks the event loop for ~1s warm, up to ~8s on cold coreaudiod
// (post-wake, post-boot). Load happens on first voice keypress — no
// preload, because there's no way to make dlopen non-blocking and a
// startup freeze is worse than a first-press delay.
type AudioNapi = typeof import('audio-capture-napi')
let audioNapi: AudioNapi | null = null
let audioNapiPromise: Promise<AudioNapi> | null = null
function loadAudioNapi(): Promise<AudioNapi> {
audioNapiPromise ??= (async () => {
const t0 = Date.now()
const mod = await import('audio-capture-napi')
// vendor/audio-capture-src/index.ts defers require(...node) until the
// first function call — trigger it here so timing reflects real cost.
mod.isNativeAudioAvailable()
audioNapi = mod
logForDebugging(`[voice] audio-capture-napi loaded in ${Date.now() - t0}ms`)
return mod
})()
return audioNapiPromise
}
// ─── Constants ───────────────────────────────────────────────────────
const RECORDING_SAMPLE_RATE = 16000
const RECORDING_CHANNELS = 1
// SoX silence detection: stop after this duration of silence
const SILENCE_DURATION_SECS = '2.0'
const SILENCE_THRESHOLD = '3%'
// ─── Dependency check ────────────────────────────────────────────────
function hasCommand(cmd: string): boolean {
// Spawn the target directly instead of `which cmd`. On Termux/Android
// `which` is a shell builtin — the external binary is absent or
// kernel-blocked (EPERM) when spawned from Node. Only reached on
// non-Windows (win32 returns early from all callers), no PATHEXT issue.
// result.error is set iff the spawn itself fails (ENOENT/EACCES); exit
// code is irrelevant — an unrecognized --version still means cmd exists.
const result = spawnSync(cmd, ['--version'], {
stdio: 'ignore',
timeout: 3000,
})
return result.error === undefined
}
// Probe whether arecord can actually open a capture device. hasCommand()
// only checks PATH; on WSL1/Win10-WSL2/headless Linux the binary exists
// but fails at open() because there is no ALSA card and no PulseAudio
// server. On WSL2+WSLg (Win11), PulseAudio works via RDP pipes and arecord
// succeeds. We spawn with the same args as startArecordRecording() and race
// a short timer: if the process is still alive after 150ms it opened the
// device; if it exits early the stderr tells us why. Memoized — audio
// device availability does not change mid-session, and this is called on
// every voice keypress via checkRecordingAvailability().
type ArecordProbeResult = { ok: boolean; stderr: string }
let arecordProbe: Promise<ArecordProbeResult> | null = null
function probeArecord(): Promise<ArecordProbeResult> {
arecordProbe ??= new Promise(resolve => {
const child = spawn(
'arecord',
[
'-f',
'S16_LE',
'-r',
String(RECORDING_SAMPLE_RATE),
'-c',
String(RECORDING_CHANNELS),
'-t',
'raw',
'/dev/null',
],
{ stdio: ['ignore', 'ignore', 'pipe'] },
)
let stderr = ''
child.stderr?.on('data', (chunk: Buffer) => {
stderr += chunk.toString()
})
const timer = setTimeout(
(c: ChildProcess, r: (v: ArecordProbeResult) => void) => {
c.kill('SIGTERM')
r({ ok: true, stderr: '' })
},
150,
child,
resolve,
)
child.once('close', code => {
clearTimeout(timer)
// SIGTERM close (code=null) after timer fired is already resolved.
// Early close with code=0 is unusual (arecord shouldn't exit on its
// own) but treat as ok.
void resolve({ ok: code === 0, stderr: stderr.trim() })
})
child.once('error', () => {
clearTimeout(timer)
void resolve({ ok: false, stderr: 'arecord: command not found' })
})
})
return arecordProbe
}
export function _resetArecordProbeForTesting(): void {
arecordProbe = null
}
// cpal's ALSA backend writes to our process stderr when it can't find any
// sound cards (it runs in-process — no subprocess pipe to capture it). The
// spawn fallbacks below pipe stderr correctly, so skip native when ALSA has
// nothing to open. Memoized: card presence doesn't change mid-session.
let linuxAlsaCardsMemo: Promise<boolean> | null = null
function linuxHasAlsaCards(): Promise<boolean> {
linuxAlsaCardsMemo ??= readFile('/proc/asound/cards', 'utf8').then(
cards => {
const c = cards.trim()
return c !== '' && !c.includes('no soundcards')
},
() => false,
)
return linuxAlsaCardsMemo
}
export function _resetAlsaCardsForTesting(): void {
linuxAlsaCardsMemo = null
}
type PackageManagerInfo = {
cmd: string
args: string[]
displayCommand: string
}
function detectPackageManager(): PackageManagerInfo | null {
if (process.platform === 'darwin') {
if (hasCommand('brew')) {
return {
cmd: 'brew',
args: ['install', 'sox'],
displayCommand: 'brew install sox',
}
}
return null
}
if (process.platform === 'linux') {
if (hasCommand('apt-get')) {
return {
cmd: 'sudo',
args: ['apt-get', 'install', '-y', 'sox'],
displayCommand: 'sudo apt-get install sox',
}
}
if (hasCommand('dnf')) {
return {
cmd: 'sudo',
args: ['dnf', 'install', '-y', 'sox'],
displayCommand: 'sudo dnf install sox',
}
}
if (hasCommand('pacman')) {
return {
cmd: 'sudo',
args: ['pacman', '-S', '--noconfirm', 'sox'],
displayCommand: 'sudo pacman -S sox',
}
}
}
return null
}
export async function checkVoiceDependencies(): Promise<{
available: boolean
missing: string[]
installCommand: string | null
}> {
// Native audio module (cpal) handles everything on macOS, Linux, and Windows
const napi = await loadAudioNapi()
if (napi.isNativeAudioAvailable()) {
return { available: true, missing: [], installCommand: null }
}
// Windows has no supported fallback — native module is required
if (process.platform === 'win32') {
return {
available: false,
missing: ['Voice mode requires the native audio module (not loaded)'],
installCommand: null,
}
}
// On Linux, arecord (ALSA utils) is a valid fallback recording backend
if (process.platform === 'linux' && hasCommand('arecord')) {
return { available: true, missing: [], installCommand: null }
}
const missing: string[] = []
if (!hasCommand('rec')) {
missing.push('sox (rec command)')
}
const pm = missing.length > 0 ? detectPackageManager() : null
return {
available: missing.length === 0,
missing,
installCommand: pm?.displayCommand ?? null,
}
}
// ─── Recording availability ──────────────────────────────────────────
export type RecordingAvailability = {
available: boolean
reason: string | null
}
// Probe-record through the full fallback chain (native → arecord → SoX)
// to verify that at least one backend can record. On macOS this also
// triggers the TCC permission dialog on first use. We trust the probe
// result over the TCC status API, which can be unreliable for ad-hoc
// signed or cross-architecture binaries (e.g., x64-on-arm64).
export async function requestMicrophonePermission(): Promise<boolean> {
const napi = await loadAudioNapi()
if (!napi.isNativeAudioAvailable()) {
return true // non-native platforms skip this check
}
const started = await startRecording(
_chunk => {}, // discard audio data — this is a permission probe only
() => {}, // ignore silence-detection end signal
{ silenceDetection: false },
)
if (started) {
stopRecording()
return true
}
return false
}
export async function checkRecordingAvailability(): Promise<RecordingAvailability> {
// Remote environments have no local microphone
if (isRunningOnHomespace() || isEnvTruthy(process.env.CLAUDE_CODE_REMOTE)) {
return {
available: false,
reason:
'Voice mode requires microphone access, but no audio device is available in this environment.\n\nTo use voice mode, run Claude Code locally instead.',
}
}
// Native audio module (cpal) handles everything on macOS, Linux, and Windows
const napi = await loadAudioNapi()
if (napi.isNativeAudioAvailable()) {
return { available: true, reason: null }
}
// Windows has no supported fallback
if (process.platform === 'win32') {
return {
available: false,
reason:
'Voice recording requires the native audio module, which could not be loaded.',
}
}
const wslNoAudioReason =
'Voice mode could not access an audio device in WSL.\n\nWSL2 with WSLg (Windows 11) provides audio via PulseAudio — if you are on Windows 10 or WSL1, run Claude Code in native Windows instead.'
// On Linux (including WSL), probe arecord. hasCommand() is insufficient:
// the binary can exist while the device open() fails (WSL1, Win10-WSL2,
// headless Linux). WSL2+WSLg (Win11 default) works via PulseAudio RDP
// pipes — cpal fails (no /proc/asound/cards) but arecord succeeds.
if (process.platform === 'linux' && hasCommand('arecord')) {
const probe = await probeArecord()
if (probe.ok) {
return { available: true, reason: null }
}
if (getPlatform() === 'wsl') {
return { available: false, reason: wslNoAudioReason }
}
logForDebugging(`[voice] arecord probe failed: ${probe.stderr}`)
// fall through to SoX
}
// Fallback: check for SoX
if (!hasCommand('rec')) {
// WSL without arecord AND without SoX: the generic "install SoX"
// hint below is misleading on WSL1/Win10 (no audio devices at all),
// but correct on WSL2+WSLg (SoX works via PulseAudio). Since we can't
// distinguish WSLg-vs-not without a backend to probe, show the WSLg
// guidance — it points WSL1 users at native Windows AND tells WSLg
// users their setup should work (they can install sox or alsa-utils).
// Known gap: WSL with SoX but NO arecord skips both this branch and
// the probe above — hasCommand('rec') lies the same way. We optimistically
// trust it (WSLg+SoX would work) rather than probeSox() for a near-zero
// population (WSL1 × minimal distro × SoX-but-not-alsa-utils).
if (getPlatform() === 'wsl') {
return { available: false, reason: wslNoAudioReason }
}
const pm = detectPackageManager()
return {
available: false,
reason: pm
? `Voice mode requires SoX for audio recording. Install it with: ${pm.displayCommand}`
: 'Voice mode requires SoX for audio recording. Install SoX manually:\n macOS: brew install sox\n Ubuntu/Debian: sudo apt-get install sox\n Fedora: sudo dnf install sox',
}
}
return { available: true, reason: null }
}
// ─── Recording (native audio on macOS/Linux/Windows, SoX/arecord fallback on Linux) ─────────────
let activeRecorder: ChildProcess | null = null
let nativeRecordingActive = false
export async function startRecording(
onData: (chunk: Buffer) => void,
onEnd: () => void,
options?: { silenceDetection?: boolean },
): Promise<boolean> {
logForDebugging(`[voice] startRecording called, platform=${process.platform}`)
// Try native audio module first (macOS, Linux, Windows via cpal)
const napi = await loadAudioNapi()
const nativeAvailable =
napi.isNativeAudioAvailable() &&
(process.platform !== 'linux' || (await linuxHasAlsaCards()))
const useSilenceDetection = options?.silenceDetection !== false
if (nativeAvailable) {
// Ensure any previous recording is fully stopped
if (nativeRecordingActive || napi.isNativeRecordingActive()) {
napi.stopNativeRecording()
nativeRecordingActive = false
}
const started = napi.startNativeRecording(
(data: Buffer) => {
onData(data)
},
() => {
if (useSilenceDetection) {
nativeRecordingActive = false
onEnd()
}
// In push-to-talk mode, ignore the native module's silence-triggered
// onEnd. Recording continues until the caller explicitly calls
// stopRecording() (e.g. when the user presses Ctrl+X).
},
)
if (started) {
nativeRecordingActive = true
return true
}
// Native recording failed — fall through to platform fallbacks
}
// Windows has no supported fallback
if (process.platform === 'win32') {
logForDebugging('[voice] Windows native recording unavailable, no fallback')
return false
}
// On Linux, try arecord (ALSA utils) before SoX. Consult the probe so
// backend selection matches checkRecordingAvailability() — otherwise
// on headless Linux with both alsa-utils and SoX, the availability
// check falls through to SoX (probe.ok=false, not WSL) but this path
// would still pick broken arecord. Probe is memoized; zero latency.
if (
process.platform === 'linux' &&
hasCommand('arecord') &&
(await probeArecord()).ok
) {
return startArecordRecording(onData, onEnd)
}
// Fallback: SoX rec (Linux, or macOS if native module unavailable)
return startSoxRecording(onData, onEnd, options)
}
function startSoxRecording(
onData: (chunk: Buffer) => void,
onEnd: () => void,
options?: { silenceDetection?: boolean },
): boolean {
const useSilenceDetection = options?.silenceDetection !== false
// Record raw PCM: 16 kHz, 16-bit signed, mono, to stdout.
// --buffer 1024 forces SoX to flush audio in small chunks instead of
// accumulating data in its internal buffer. Without this, SoX may buffer
// several seconds of audio before writing anything to stdout when piped,
// causing zero data flow until the process exits.
const args = [
'-q', // quiet
'--buffer',
'1024',
'-t',
'raw',
'-r',
String(RECORDING_SAMPLE_RATE),
'-e',
'signed',
'-b',
'16',
'-c',
String(RECORDING_CHANNELS),
'-', // stdout
]
// Add silence detection filter (auto-stop on silence).
// Omit for push-to-talk where the user manually controls start/stop.
if (useSilenceDetection) {
args.push(
'silence', // start/stop on silence
'1',
'0.1',
SILENCE_THRESHOLD,
'1',
SILENCE_DURATION_SECS,
SILENCE_THRESHOLD,
)
}
const child = spawn('rec', args, {
stdio: ['pipe', 'pipe', 'pipe'],
})
activeRecorder = child
child.stdout?.on('data', (chunk: Buffer) => {
onData(chunk)
})
// Consume stderr to prevent backpressure
child.stderr?.on('data', () => {})
child.on('close', () => {
activeRecorder = null
onEnd()
})
child.on('error', err => {
logError(err)
activeRecorder = null
onEnd()
})
return true
}
function startArecordRecording(
onData: (chunk: Buffer) => void,
onEnd: () => void,
): boolean {
// Record raw PCM: 16 kHz, 16-bit signed little-endian, mono, to stdout.
// arecord does not support built-in silence detection, so this backend
// is best suited for push-to-talk (silenceDetection: false).
const args = [
'-f',
'S16_LE', // signed 16-bit little-endian
'-r',
String(RECORDING_SAMPLE_RATE),
'-c',
String(RECORDING_CHANNELS),
'-t',
'raw', // raw PCM, no WAV header
'-q', // quiet — no progress output
'-', // write to stdout
]
const child = spawn('arecord', args, {
stdio: ['pipe', 'pipe', 'pipe'],
})
activeRecorder = child
child.stdout?.on('data', (chunk: Buffer) => {
onData(chunk)
})
// Consume stderr to prevent backpressure
child.stderr?.on('data', () => {})
child.on('close', () => {
activeRecorder = null
onEnd()
})
child.on('error', err => {
logError(err)
activeRecorder = null
onEnd()
})
return true
}
export function stopRecording(): void {
if (nativeRecordingActive && audioNapi) {
audioNapi.stopNativeRecording()
nativeRecordingActive = false
return
}
if (activeRecorder) {
activeRecorder.kill('SIGTERM')
activeRecorder = null
}
}