cli-sound

library1.1.3jsnpmunverified

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.

communication

npm install cli-sound

package ↗

INSTALL

IMPORT

SIG · CLI-SOUND

cli-sound

communicationjavascriptv1.1.3

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Player

✓ import { Player } from 'cli-sound';

✗ 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.

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();

Debug

Known issues

gotchacli-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`.

affects: >=1.0.0

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

affects: >=1.0.0

gotchaThe 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.

affects: >=1.0.0

Errors

Common errors & fixes

Error: No suitable audio player found.

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

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>

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.

Upgrade

Version history

1.1.3latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

29 hits · last 30 days

node

OpenAI (training)

Resources

packagehttps://www.npmjs.com/package/cli-sound ↗