{"id":16966,"library":"cli-sound","title":"CLI Sound Player","description":"cli-sound is a Node.js utility designed for playing audio files from command-line applications and other Node.js environments. As of version 1.1.3, it offers robust cross-platform compatibility by leveraging various locally installed, headless audio programs such as `ffplay`, `mpv`, or `mpg123`. It differentiates itself from similar packages like `play-sound` through enhanced reliability, native TypeScript types, comprehensive ESM and CommonJS support, and advanced features such as volume control and customizable audio player commands. The package operates by executing a compatible audio program found on the system via `node:child_process.exec`, automatically detecting the first available player from a predefined list. Its current release cadence appears stable, with a focus on incremental improvements and broad system compatibility.","status":"active","version":"1.1.3","language":"javascript","source_language":"en","source_url":null,"tags":["javascript","typescript"],"install":[{"cmd":"npm install cli-sound","lang":"bash","label":"npm"},{"cmd":"yarn add cli-sound","lang":"bash","label":"yarn"},{"cmd":"pnpm add cli-sound","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The primary class for playing sounds is a named export. ESM-first usage is recommended, but CommonJS is also supported.","wrong":"import Player from 'cli-sound';","symbol":"Player","correct":"import { Player } from 'cli-sound';"},{"note":"For CommonJS environments, the Player class is destructured from the require call.","symbol":"Player (CommonJS)","correct":"const { Player } = require('cli-sound');"},{"note":"When only importing types, use `import type` for better tree-shaking and to avoid bundling unnecessary code.","symbol":"PlayerOptions (Type)","correct":"import type { PlayerOptions } from 'cli-sound';"}],"quickstart":{"code":"import { Player } from 'cli-sound';\nimport { fileURLToPath } from 'url';\nimport path from 'path';\n\nconst __filename = fileURLToPath(import.meta.url);\nconst __dirname = path.dirname(__filename);\n\n// Provide a path to an actual audio file (e.g., MP3, WAV)\n// Ensure you have an audio player like 'ffplay' or 'mpv' installed on your system.\n// For demonstration, we'll use a placeholder. Replace with a real path.\nconst soundFilePath = process.env.SOUND_FILE_PATH ?? path.join(__dirname, 'test-sound.mp3');\n\nasync function playSound() {\n  try {\n    const player = new Player({\n      volume: 0.5, // Play at 50% volume (if supported by player)\n      // Optionally, specify custom commands or extend default ones\n      // commands: ['ffplay -loglevel quiet -nodisp -volume %volume% %filepath%'],\n    });\n\n    console.log(`Attempting to play sound from: ${soundFilePath}`);\n    await player.play(soundFilePath);\n    console.log('Sound playback initiated.');\n  } catch (error) {\n    console.error('Failed to play sound:', error.message);\n    console.error('Ensure you have a compatible audio player installed (e.g., ffplay, mpv) and the sound file path is correct.');\n  }\n}\n\nplaySound();","lang":"typescript","description":"Demonstrates how to create a Player instance, configure it with options like volume, and play an audio file. Includes error handling for common issues like missing players."},"warnings":[{"fix":"Ensure you have a suitable command-line audio player installed and accessible via your system's PATH. Popular choices include `ffmpeg` (which includes `ffplay`) or `mpv`.","message":"cli-sound relies on external, locally installed command-line audio players (e.g., `ffplay`, `mpv`, `mpg123`). The package will not function if no compatible audio player is found on the system's PATH.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Consult the `cli-sound` documentation or test with different players to determine volume control compatibility. For critical volume control, ensure you are using a player known to support it (e.g., `ffplay`, `mpv`).","message":"Volume control is not universally supported by all detected audio players. If a player does not support volume control, the `volume` option passed to the `Player` constructor or `play` method will be ignored.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"When using the `commands` or `extendCommands` options with user-supplied data, rigorously sanitize all inputs to prevent malicious command execution. Avoid direct concatenation of untrusted strings.","message":"The package uses `node:child_process.exec` which can be susceptible to command injection if user-provided input is directly interpolated into file paths or custom commands without proper sanitization. While `cli-sound` aims to handle file paths safely, exercise caution with custom `commands` options.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Install a compatible audio player like `ffmpeg` (which includes `ffplay`) or `mpv` via your operating system's package manager (e.g., `sudo apt install ffmpeg` on Debian/Ubuntu, `brew install ffmpeg` on macOS, or download binaries for Windows).","cause":"The system does not have any of the supported command-line audio players (e.g., ffplay, mpv, mpg123) installed or available in the system's PATH.","error":"Error: No suitable audio player found."},{"fix":"Verify that the audio player executable is correctly installed and its directory is included in your system's PATH. Try running the player manually from your terminal (e.g., `ffplay --version`). Reinstall the player if necessary.","cause":"The identified audio player program (e.g., `ffplay`) could not be found or executed. This might be due to incorrect installation, missing executable permissions, or a corrupted PATH environment variable.","error":"Failed to play sound: spawn <player_command> ENOENT"},{"fix":"Check the integrity and format of your audio file. Try playing the same audio file directly with the detected player from your terminal to get more specific error messages from the audio player itself. Ensure the file path is correct and accessible.","cause":"The audio player itself failed to play the sound. This can happen if the audio file is corrupted, in an unsupported format for that player, or if the player encounters an internal error.","error":"Failed to play sound: Error: Command failed: <player_command> <sound_file>"}],"ecosystem":"npm","meta_description":null}