{"id":14959575,"url":"https://github.com/maxhalford/chime","last_synced_at":"2025-04-04T10:05:23.908Z","repository":{"id":37312934,"uuid":"301187717","full_name":"MaxHalford/chime","owner":"MaxHalford","description":"🎵 Python sound notifications made easy","archived":false,"fork":false,"pushed_at":"2023-03-06T22:25:50.000Z","size":5220,"stargazers_count":310,"open_issues_count":5,"forks_count":13,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-04T10:05:17.510Z","etag":null,"topics":["audio","command-line","cross-platform","ipython","notifications","python","sound","streamlit","wav"],"latest_commit_sha":null,"homepage":"https://chime-soundboard.streamlit.app","language":"Python","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/MaxHalford.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","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},"funding":{"github":"MaxHalford"}},"created_at":"2020-10-04T17:34:48.000Z","updated_at":"2025-03-22T16:10:08.000Z","dependencies_parsed_at":"2024-01-17T06:11:14.822Z","dependency_job_id":"60a033a3-c0e7-4e49-b6bb-a726dbbdb0b6","html_url":"https://github.com/MaxHalford/chime","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MaxHalford%2Fchime","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MaxHalford%2Fchime/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MaxHalford%2Fchime/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MaxHalford%2Fchime/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MaxHalford","download_url":"https://codeload.github.com/MaxHalford/chime/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247157281,"owners_count":20893220,"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","command-line","cross-platform","ipython","notifications","python","sound","streamlit","wav"],"created_at":"2024-09-24T13:20:02.439Z","updated_at":"2025-04-04T10:05:23.881Z","avatar_url":"https://github.com/MaxHalford.png","language":"Python","readme":"\u003cdiv align=\"center\"\u003e\n  \u003ch1\u003echime\u003c/h1\u003e\n  \u003cq\u003e\u003ci\u003ePython sound notifications made easy.\u003c/i\u003e\u003c/q\u003e\n\u003c/div\u003e\n\u003cbr\u003e\n\n\u003cdiv align=\"center\"\u003e\n  \u003c!-- Tests --\u003e\n  \u003ca href=\"https://github.com/MaxHalford/chime/actions/workflows/tests.yml\"\u003e\n    \u003cimg src=\"https://github.com/MaxHalford/chime/actions/workflows/tests.yml/badge.svg?style=flat-square\" alt=\"tests\"\u003e\n  \u003c/a\u003e\n  \u003c!-- Soundboard --\u003e\n  \u003ca href=\"https://chime-soundboard.streamlit.app/\"\u003e\n    \u003cimg src=\"https://img.shields.io/website?label=soundboard\u0026style=flat-square\u0026url=https://chime-soundboard.streamlit.app/\" alt=\"soundboard\"\u003e\n  \u003c/a\u003e\n  \u003c!-- PyPI --\u003e\n  \u003ca href=\"https://pypi.org/project/chime\"\u003e\n    \u003cimg src=\"https://img.shields.io/pypi/v/chime.svg?label=release\u0026color=blue\u0026style=flat-square\" alt=\"pypi\"\u003e\n  \u003c/a\u003e\n  \u003c!-- PePy --\u003e\n  \u003ca href=\"https://pepy.tech/project/chime\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/dynamic/json?style=flat-square\u0026maxAge=86400\u0026label=downloads\u0026query=%24.total_downloads\u0026url=https%3A%2F%2Fapi.pepy.tech%2Fapi%2Fprojects%2Fchime\" alt=\"pepy\"\u003e\n  \u003c/a\u003e\n  \u003c!-- License --\u003e\n  \u003ca href=\"https://opensource.org/licenses/MIT\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square\" alt=\"license\"\u003e\n  \u003c/a\u003e\n\u003c/div\u003e\n\u003cbr\u003e\n\n## Table of contents\n\n- [Table of contents](#table-of-contents)\n- [Motivation](#motivation)\n- [Installation](#installation)\n- [Basic usage](#basic-usage)\n- [Theming](#theming)\n- [IPython/Jupyter magic](#ipythonjupyter-magic)\n- [Exception notifications](#exception-notifications)\n- [Command-line usage](#command-line-usage)\n- [Platform support](#platform-support)\n- [I can't hear anything 🙉](#i-cant-hear-anything-)\n- [Setting a default theme](#setting-a-default-theme)\n- [Command-line arguments](#command-line-arguments)\n- [Adding a new theme](#adding-a-new-theme)\n- [Things to do](#things-to-do)\n- [Acknowledgements](#acknowledgements)\n- [License](#license)\n\n## Motivation\n\nI made this because I wanted a simple auditory cue system to tell me when a long-running number crunching script had finished. I didn't want to have to fiddle with the command-line, and also wanted a cross-platform solution. Thus was born `chime`!\n\n## Installation\n\n```sh\npip install chime\n```\n\nThis library has **no dependencies**. The IPython/Jupyter functionality is only imported if you've installed the `ipython` library. It should work for any Python version above or equal to 3.6.\n\n## Basic usage\n\n`chime` puts four functions at your disposal:\n\n```py\n\u003e\u003e\u003e import chime\n\n\u003e\u003e\u003e chime.success()\n\u003e\u003e\u003e chime.warning()\n\u003e\u003e\u003e chime.error()\n\u003e\u003e\u003e chime.info()\n\n```\n\nCalling any of the above functions will play a sound. Note that the sounds are played in asynchronous processes, and are thus non-blocking. Each function should take around 2ms to execute, regardless of the sound length. You're free to use each sound notification in any way you see fit. I'm not your mama.\n\n## Theming\n\nThe sounds that are played depend on which theme is being used.\n\n```py\n\u003e\u003e\u003e chime.theme()  # return the current theme\n'chime'\n\n```\n\nSeveral themes are available:\n\n```py\n\u003e\u003e\u003e chime.themes()\n['big-sur', 'chime', 'future', 'mario', 'material', 'pokemon', 'sonic', 'zelda']\n\n```\n\nThe theme can be changed by passing a theme name to the `theme` function:\n\n```py\n\u003e\u003e\u003e chime.theme('zelda')\n\n```\n\nA couple of things to note:\n\n- You can listen to the sounds interactively via [this soundboard](https://chime-soundboard.streamlit.app/), which is made with [Streamlit](https://www.streamlit.io/).\n- A random theme will be picked each time you play a sound if you set the theme to `'random'`.\n\n## IPython/Jupyter magic\n\nLoad the extension as so:\n\n```py\n%load_ext chime\n```\n\nYou can wrap a line:\n\n```py\n%chime print(\"I'm a line\")\n```\n\nYou can also wrap an entire cell:\n\n```py\n%%chime\n\nprint(\"I'm a cell\")\n```\n\nThe magic command will call `chime.success` when the line/cell finishes successfully. Otherwise, `chime.error` is called whenever an exception is raised.\n\n## Exception notifications\n\nIf you run `chime.notify_exceptions`, then `chime.error` will be called whenever an exception is raised.\n\n```py\nchime.notify_exceptions()\n\nraise ValueError(\"I'm going to make some noise\")\n```\n\n## Command-line usage\n\nYou can run `chime` from the command-line:\n\n```sh\n$ chime\n```\n\nBy default, this will play the success sound. You can also choose which sound to play, like so:\n\n```sh\n$ chime info\n```\n\nYou can also choose which theme to use:\n\n```sh\n$ chime info --theme zelda\n```\n\nIf you're using bash, then you can use `chime` to notify you when a program finishes:\n\n```sh\n$ echo \"Hello world!\"; chime\n```\n\nThis will play the sound regardless of the fact that the first command succeeded or not. If you're running on Windows, then you can run the following equivalent:\n\n```sh\n\u003e echo \"Hello world!\" \u0026 chime\n```\n\n## Platform support\n\nUnder the hood, `chime` runs a command in the shell to play a `.wav` file. The command-line program that is used depends on the [platform](https://www.wikiwand.com/en/Computing_platform) that you're using. Platform information is available in the [`sys.platform` variable](https://docs.python.org/3/library/sys.html#sys.platform) as well as the [`platform` module](https://docs.python.org/3/library/platform.html) from the standard library. Currently, the supported platforms are:\n\n- Darwin\n- Linux\n- Windows\n\nA `UserWarning` is raised if you run a `chime` sound on an unsupported platform. Feel free to get in touch or issue a pull request if you want to add support for a specific platform. Likewise, don't hesitate if you're encountering trouble with one of the above platforms. I won't bite.\n\n## I can't hear anything 🙉\n\nDid you check if you turned your sound on? Just kidding. 😜\n\nThis library is designed to be non-invasive. By default, sounds are played asynchronously in unchecked processes. Therefore, if something goes wrong, the process dies silently. If you can't hear anything and you think that the issue is coming from `chime`, then set the `sync` parameter when you play a sound:\n\n```py\n\u003e\u003e\u003e chime.info(sync=True)\n\n```\n\nThis will play the sound synchronously and issue a warning if something goes wrong, which should allow you to debug the issue. You can also raise an exception instead of sending a warning by setting the `raise_error` parameter:\n\n```py\n\u003e\u003e\u003e chime.info(sync=True, raise_error=True)\n\n```\n\nNote that setting `raise_error` won't do anything if `sync` is set to `False`.\n\n## Setting a default theme\n\nTo change the default theme a configuration file may be created in `~/.config/chime/chime.conf` on Unix or `%APPDATA%\\chime\\chime.ini` on Windows.\n\nFor example, to change the default theme to `'zelda'`, the configuration file would contain:\n\n```ini\n[chime]\ntheme = zelda\n\n```\n\n## Command-line arguments\n\nChime works by running commands in the CLI. For instance, `aplay` is used on Linux systems, while `afplay` is used on Darwin systems. Arguments can be specified by setting the `RUN_ARGS` variable. For example, here's how to select a specific sound card, assuming a Linux system using `aplay`:\n\n```py\n\u003e\u003e\u003e chime.RUN_ARGS = \"--device sysdefault:CARD=PCH\"\n\n```\n\nYou can also specify this as a default configuration in the configuration file:\n\n```ini\n[chime]\ncli_args = '--device sysdefault:CARD=PCH'\n\n```\n\nAt present, it isn't possible to pass CLI arguments on Windows, due to a limitation of the [`winsound`](https://docs.python.org/3/library/winsound.html) module.\n\n## Adding a new theme\n\nI have toyed with the idea of allowing users to add their own theme(s), but at the moment I rather keep things minimal. However, I'm happy to integrate new themes into the library. You can propose a new theme by [opening a pull request](https://github.com/MaxHalford/chime/issues/new) that adds the necessary .wav files to the [`themes` directory](https://github.com/MaxHalford/chime/tree/main/themes). A theme is made up of four files: `success.wav`, `warning.wav`, `error.wav`, and `info.wav`. That's all you need to do: the theme will picked up be automatically once the necessary files are provided.\n\nBe creative! 👩‍🎨\n\n## Things to do\n\n- Some mechanism to automatically call `chime.warning` when a warning occurs.\n- Make it work with a remote machine. For instance a Jupyter Notebook hosted on a remote machine.\n- More themes!\n\n## Acknowledgements\n\n- Special thanks to [Michael Vlah](https://github.com/vlahm) for being a gentleman by giving up the \"chime\" name on PyPI.\n- Thanks to u/Pajke on reddit for helping me debug Windows support.\n- Thanks to [David Chen](https://github.com/dchen327) for adding Linux support by suggesting the use of [aplay](https://linux.die.net/man/1/aplay).\n- Thanks to [Vincent Warmerdam](https://twitter.com/fishnets88) for suggesting a command-line interface.\n- Calmcode made a [video introduction to chime](https://calmcode.io/chime/introduction.html) ❤️\n- Thanks to [Paulo S. Costa](https://github.com/paw-lu) for contributing in many different ways.\n- Thanks to [d34d_m8](https://github.com/d34dm8) for adding OpenBSD support.\n\n## License\n\nAs you would probably expect, this is [MIT licensed](LICENSE).\n","funding_links":["https://github.com/sponsors/MaxHalford"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaxhalford%2Fchime","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmaxhalford%2Fchime","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaxhalford%2Fchime/lists"}