/**
 * 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>;