cli-sound

A simple utility to play sounds from Node.js programs, useful for (but not limited to) CLI apps.

It can also be used directly as a terminal command:

npm i -g cli-sound
cli-sound path/to/sound.mp3

# or
npx cli-sound path/to/sound.mp3

It works by executing a locally installed audio program without a graphical interface.

This package is inspired by play-sound, but it goes to greater lengths to ensure good cross-operative-system support, provide volume control, customization, TypeScript types, ESM and CommonJS compatibility, and better reliability overall.

Install

npm install cli-sound

Example

import { Player } from "cli-sound";

const player = new Player();

await player.play("path/to/sound.mp3");

Contents

• Install
• Example
• Contents
• How it works
• Usage
  • Creating the player
  • Playing a sound
• Error handling
• Inspecting the command
• Contributing
• Author

How it works

This package will go through a list of programs, find the first one available, and attempt to use it to play the sound. It uses the exec function from the node:child_process module internally.

The default list of programs is as follows:

• ffplay - Linux, Windows, macOS
• mpv - Linux, Windows, macOS
• mpg123 - Linux, Windows, macOS
• mpg321 - Linux, macOS
• mplayer - Linux, Windows, macOS
• afplay - macOS - untested, volume control not supported
• play - Linux, macOS (SoX package) - untested
• omxplayer - Linux (specifically Raspberry Pi OS) - untested, volume control not supported
• aplay - Linux (ALSA sound system) - untested, volume control not supported
• cmdmp3 - Windows - untested, volume control not supported
• cvlc - Linux, Windows, macOS - untested
• powershell - Windows - untested, volume control not supported

Usage

Creating the player

import { Player } from "cli-sound";

const player = new Player();

When the player is created, the first available program is found and stored.

The Player constructor accepts an optional options object as an argument with the following properties:

commands - string[]

A list of commands that will be used to play the audio file.

The first executable found will be used. Commands can be specified using one of the following formats:

• command
• command <arguments> where arguments must contain %filepath% and optionally %volume%

extendCommands - (defaultCommands: string[]) => string[]

A function that will be called with the built-in commands and should return a list of commands that will be used to play the audio file.

The first executable found will be used. Commands can be specified using one of the following formats:

• command
• command <arguments> where arguments must contain %filepath% and optionally %volume%

volume - number (default: 1)

A volume value between 0 and 1, where 1 is the loudest and 0 is the quietest. Only supported by some players.

Values higher than 1 are supported by some players.

arguments - Record<string, string>

Additional arguments to pass to the audio player. Keys are the names of the audio player and values are the arguments.

The passed arguments will be prepended to the rest of the arguments.

argumentValueTransformers - ArgumentValueTransformersMap

Transformer functions for the values passed to the arguments of each audio player.

The top-level keys are the names of the audio players. The corresponding values are objects that map arguments (by name) to transformer functions.

The transformer functions will be called with the value of the argument and should return the transformed value.

The all special key can be used instead of the name of an audio player to apply its transformers to all audio players.

Playing a sound

await player.play("path/to/sound.mp3");

The play method accepts the path to the sound file as a string and returns a promise that resolves when the sound is finished playing. The resolved value is an object containing the stdout and stderr from the command's output.

The play method also accepts an optional options object as the second argument. It accepts the volume, arguments and argumentValueTransformers properties described above.

Error handling

There are two points at which an error can occur:

• Creating the player (new Player()): happens if none of the programs are available.
• Playing a sound (player.play()): happens if the program command fails for some reason, including but not limited to the file not existing or being in the wrong format.

If succeeding in playing the sound is not critical, you can wrap the code in a try/catch block to prevent the failure from crashing your app.

[!WARNING] Note that, since the package doesn't have a lot of control over the spawned programs, they may fail silently or behave in unexpected ways.

Inspecting the command

If you want to obtain the command that will be used to play the sound, you can use the createPlayCommand method:

console.log(player.createPlayCommand("path/to/sound.mp3"));

It takes the same arguments as the `play`` method, but it doesn't execute the command: it just returns it synchronously instead.

This can be useful for debugging or logging purposes, or if you want to use the command differently.

Contributing

Install bun and install dependencies with bun i.

You can run bun run test to test each of the commands on your machine, and get a report after it is done, along with success/error logs.

Contributions are welcome, especially those that add support for more programs/platforms. Bug fixes and feature additions are also highly appreciated.

Author

cli-sound was built by Dani Guardiola