{"id":20797185,"url":"https://github.com/daniguardiola/cli-sound","last_synced_at":"2026-04-12T03:03:29.369Z","repository":{"id":206583096,"uuid":"717148048","full_name":"DaniGuardiola/cli-sound","owner":"DaniGuardiola","description":"Play a sound from your CLI app.","archived":false,"fork":false,"pushed_at":"2023-12-22T22:02:06.000Z","size":181,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-01-18T11:42:16.705Z","etag":null,"topics":["audio","cli","javascript","nodejs","scripting","sound","terminal","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/DaniGuardiola.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2023-11-10T17:05:54.000Z","updated_at":"2023-11-16T19:39:59.000Z","dependencies_parsed_at":"2023-11-16T21:07:15.665Z","dependency_job_id":null,"html_url":"https://github.com/DaniGuardiola/cli-sound","commit_stats":null,"previous_names":["daniguardiola/cli-sound"],"tags_count":2,"template":false,"template_full_name":"DaniGuardiola/package-template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DaniGuardiola%2Fcli-sound","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DaniGuardiola%2Fcli-sound/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DaniGuardiola%2Fcli-sound/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DaniGuardiola%2Fcli-sound/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DaniGuardiola","download_url":"https://codeload.github.com/DaniGuardiola/cli-sound/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243141243,"owners_count":20242817,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["audio","cli","javascript","nodejs","scripting","sound","terminal","typescript"],"created_at":"2024-11-17T16:32:53.766Z","updated_at":"2025-12-27T06:35:05.434Z","avatar_url":"https://github.com/DaniGuardiola.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg alt=\"The cli-sound logo\" src=\"https://github.com/DaniGuardiola/cli-sound/raw/main/logo.png\"\u003e\n\u003c/p\u003e\n\nA simple utility to play sounds from Node.js programs, useful for (but not limited to) CLI apps.\n\nIt can also be used directly as a terminal command:\n\n```sh\nnpm i -g cli-sound\ncli-sound path/to/sound.mp3\n\n# or\nnpx cli-sound path/to/sound.mp3\n```\n\nIt works by executing a locally installed audio program without a graphical interface.\n\nThis package is inspired by [play-sound](https://github.com/shime/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.\n\n## \u003ca name='Install'\u003e\u003c/a\u003eInstall\n\n```\nnpm install cli-sound\n```\n\n## \u003ca name='Example'\u003e\u003c/a\u003eExample\n\n```ts\nimport { Player } from \"cli-sound\";\n\nconst player = new Player();\n\nawait player.play(\"path/to/sound.mp3\");\n```\n\n## \u003ca name='Contents'\u003e\u003c/a\u003eContents\n\n\u003c!-- vscode-markdown-toc --\u003e\n\n- [Install](#install)\n- [Example](#example)\n- [Contents](#contents)\n- [How it works](#how-it-works)\n- [Usage](#usage)\n  - [Creating the player](#creating-the-player)\n  - [Playing a sound](#playing-a-sound)\n- [Error handling](#error-handling)\n- [Inspecting the command](#inspecting-the-command)\n- [Contributing](#contributing)\n- [Author](#author)\n\n\u003c!-- vscode-markdown-toc-config\n\tnumbering=false\n\tautoSave=true\n\t/vscode-markdown-toc-config --\u003e\n\u003c!-- /vscode-markdown-toc --\u003e\n\n## \u003ca name='Howitworks'\u003e\u003c/a\u003eHow it works\n\nThis 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.\n\nThe default list of programs is as follows:\n\n- `ffplay` - Linux, Windows, macOS\n- `mpv` - Linux, Windows, macOS\n- `mpg123` - Linux, Windows, macOS\n- `mpg321` - Linux, macOS\n- `mplayer` - Linux, Windows, macOS\n- `afplay` - macOS - _untested, volume control not supported_\n- `play` - Linux, macOS (SoX package) - _untested_\n- `omxplayer` - Linux (specifically Raspberry Pi OS) - _untested, volume control not supported_\n- `aplay` - Linux (ALSA sound system) - _untested, volume control not supported_\n- `cmdmp3` - Windows - _untested, volume control not supported_\n- `cvlc` - Linux, Windows, macOS - _untested_\n- `powershell` - Windows - _untested, volume control not supported_\n\n## \u003ca name='Usage'\u003e\u003c/a\u003eUsage\n\n### \u003ca name='Creatingtheplayer'\u003e\u003c/a\u003eCreating the player\n\n```ts\nimport { Player } from \"cli-sound\";\n\nconst player = new Player();\n```\n\nWhen the player is created, the first available program is found and stored.\n\nThe `Player` constructor accepts an optional `options` object as an argument with the following properties:\n\n**`commands`** - `string[]`\n\nA list of commands that will be used to play the audio file.\n\nThe first executable found will be used. Commands can be specified using\none of the following formats:\n\n- `command`\n- `command \u003carguments\u003e` where arguments must contain `%filepath%` and\n  optionally `%volume%`\n\n**`extendCommands`** - `(defaultCommands: string[]) =\u003e string[]`\n\nA function that will be called with the built-in commands and should return\na list of commands that will be used to play the audio file.\n\nThe first executable found will be used. Commands can be specified using\none of the following formats:\n\n- `command`\n- `command \u003carguments\u003e` where arguments must contain `%filepath%` and\n  optionally `%volume%`\n\n**`volume`** - `number` (default: `1`)\n\nA volume value between 0 and 1, where 1 is the loudest and 0 is the\nquietest. Only supported by some players.\n\nValues higher than 1 are supported by some players.\n\n**`arguments`** - `Record\u003cstring, string\u003e`\n\nAdditional arguments to pass to the audio player. Keys are the names of the\naudio player and values are the arguments.\n\nThe passed arguments will be prepended to the rest of the arguments.\n\n**`argumentValueTransformers`** - `ArgumentValueTransformersMap`\n\nTransformer functions for the values passed to the arguments of each audio\nplayer.\n\nThe top-level keys are the names of the audio players. The corresponding\nvalues are objects that map arguments (by name) to transformer functions.\n\nThe transformer functions will be called with the value of the argument and\nshould return the transformed value.\n\nThe `all` special key can be used instead of the name of an audio player to\napply its transformers to all audio players.\n\n### \u003ca name='Playingasound'\u003e\u003c/a\u003ePlaying a sound\n\n```ts\nawait player.play(\"path/to/sound.mp3\");\n```\n\nThe `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.\n\nThe `play` method also accepts an optional `options` object as the second argument. It accepts the `volume`, `arguments` and `argumentValueTransformers` properties described above.\n\n## \u003ca name='Errorhandling'\u003e\u003c/a\u003eError handling\n\nThere are two points at which an error can occur:\n\n- Creating the player (`new Player()`): happens if none of the programs are available.\n- 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.\n\nIf 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.\n\n\u003e [!WARNING]\n\u003e 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.\n\n## \u003ca name='Inspectingthecommand'\u003e\u003c/a\u003eInspecting the command\n\nIf you want to obtain the command that will be used to play the sound, you can use the `createPlayCommand` method:\n\n```ts\nconsole.log(player.createPlayCommand(\"path/to/sound.mp3\"));\n```\n\nIt takes the same arguments as the `play`` method, but it doesn't execute the command: it just returns it synchronously instead.\n\nThis can be useful for debugging or logging purposes, or if you want to use the command differently.\n\n## \u003ca name='Contributing'\u003e\u003c/a\u003eContributing\n\nInstall [bun](https://bun.sh/) and install dependencies with `bun i`.\n\nYou 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.\n\nContributions are welcome, especially those that add support for more programs/platforms. Bug fixes and feature additions are also highly appreciated.\n\n## \u003ca name='Author'\u003e\u003c/a\u003eAuthor\n\n`cli-sound` was built by [Dani Guardiola](https://dio.la/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdaniguardiola%2Fcli-sound","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdaniguardiola%2Fcli-sound","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdaniguardiola%2Fcli-sound/lists"}