@juspay/neurolink
Version:
The pipe layer of an AI nervous system: one interface connecting provider neurons to your application, across three inference types — generate, stream and decide. `decide` returns typed, calibrated judgements from a non-generative model (~400ms, ~$0.00002
73 lines (72 loc) • 3.31 kB
TypeScript
/**
* Audio playback utilities for CLI
*
* Provides functionality for playing TTS audio using platform-specific
* CLI tools with proper cleanup and error handling.
*
* @module cli/utils/audioPlayer
*/
import type { TTSAudioFormat, CliAudioPlayerCommand } from "../../types/index.js";
/**
* Get the file extension for an audio format
*
* @param format - Audio format
* @returns File extension string (e.g., "mp3", "wav")
*/
export declare function getAudioExtension(format: TTSAudioFormat): string;
/**
* Escape a value for interpolation inside a single-quoted PowerShell string.
* PowerShell's single-quoted strings only treat `''` as a literal `'` — unlike
* shell/execFile argv, this string is parsed by powershell.exe itself, so an
* unescaped quote (e.g. a Windows username like `O'Brien` under `%TEMP%`)
* would break out of the string and let the remainder run as PS code.
*/
export declare function escapePowerShellSingleQuoted(value: string): string;
/**
* Build the ordered list of player commands to try for a file.
*
* The list is tried in order until one succeeds; a missing binary (ENOENT) or a
* decode failure simply advances to the next candidate.
*
* The Linux ordering is the crux of the mp3-playback fix (#1138): `paplay`
* (PulseAudio) and `aplay` (ALSA) only decode libsndfile/PCM formats and
* **cannot** decode mp3/AAC. Since `--tts-format` defaults to mp3, compressed
* formats must lead with real decoders (ffplay/mpv/mpg123/cvlc); paplay/aplay
* remain only as last-resort fallbacks (and still work for wav/ogg).
*
* @param filePath - Path to the audio file
* @param format - Audio format
* @param platform - Platform id (defaults to `process.platform`; injectable for tests)
* @returns Ordered player commands; empty for unsupported platforms
*/
export declare function getPlayerCandidates(filePath: string, format: TTSAudioFormat, platform?: NodeJS.Platform): CliAudioPlayerCommand[];
/**
* Build a helpful, format-aware error message when no player could decode the file.
*
* Exported for testing: the message a user sees when Linux mp3 playback finds no
* decoder must name the real fix (ffmpeg/mpv/mpg123/VLC or `--tts-format wav`),
* not the misleading "install PulseAudio" that paplay-only routing produced (#1138).
*/
export declare function buildPlaybackErrorMessage(platform: NodeJS.Platform, format: TTSAudioFormat, attempts: string[]): string;
/**
* Play audio from a buffer using platform-specific CLI tools
*
* Writes the buffer to a temporary file, plays it using the first available
* system audio player that can decode the format, and cleans up the temp file.
*
* Supported platforms:
* - macOS: `afplay` (built-in; decodes mp3/wav/aac/flac)
* - Linux: real decoders (ffplay/mpv/mpg123/cvlc) for compressed formats,
* aplay/paplay for wav — falling through the list until one works
* - Windows: PowerShell SoundPlayer (wav) or WMPlayer.OCX (compressed)
*
* @param buffer - Audio data buffer
* @param format - Audio format (mp3, wav, ogg, opus)
* @throws Error if no available player can play the audio, or platform is unsupported
*
* @example
* ```typescript
* await playAudio(audioBuffer, "mp3");
* ```
*/
export declare function playAudio(buffer: Buffer, format: TTSAudioFormat): Promise<void>;