CLI Sound Player

1.1.3 · active · verified Wed Apr 22

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.

Common errors

```
Error: No suitable audio player found.
```
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.

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).
```
Failed to play sound: spawn <player_command> ENOENT
```
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.

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.
```
Failed to play sound: Error: Command failed: <player_command> <sound_file>
```
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.

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.

Warnings

gotcha 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.
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`.
gotcha 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.
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`).
gotcha 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.
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.

Install

npm install cli-sound npm
yarn add cli-sound yarn
pnpm add cli-sound pnpm

Imports

Player
wrong:
```
import Player from 'cli-sound';
```
correct:
```
import { Player } from 'cli-sound';
```
The primary class for playing sounds is a named export. ESM-first usage is recommended, but CommonJS is also supported.
Player (CommonJS)
```
const { Player } = require('cli-sound');
```
For CommonJS environments, the Player class is destructured from the require call.
PlayerOptions (Type)
```
import type { PlayerOptions } from 'cli-sound';
```
When only importing types, use `import type` for better tree-shaking and to avoid bundling unnecessary code.

Quickstart

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.

import { Player } from 'cli-sound';
import { fileURLToPath } from 'url';
import path from 'path';

const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

// Provide a path to an actual audio file (e.g., MP3, WAV)
// Ensure you have an audio player like 'ffplay' or 'mpv' installed on your system.
// For demonstration, we'll use a placeholder. Replace with a real path.
const soundFilePath = process.env.SOUND_FILE_PATH ?? path.join(__dirname, 'test-sound.mp3');

async function playSound() {
  try {
    const player = new Player({
      volume: 0.5, // Play at 50% volume (if supported by player)
      // Optionally, specify custom commands or extend default ones
      // commands: ['ffplay -loglevel quiet -nodisp -volume %volume% %filepath%'],
    });

    console.log(`Attempting to play sound from: ${soundFilePath}`);
    await player.play(soundFilePath);
    console.log('Sound playback initiated.');
  } catch (error) {
    console.error('Failed to play sound:', error.message);
    console.error('Ensure you have a compatible audio player installed (e.g., ffplay, mpv) and the sound file path is correct.');
  }
}

playSound();

view raw JSON →