<div align="center">
<h1>chime</h1>
<q><i>Python sound notifications made easy.</i></q>
</div>
<br>
<div align="center">
<!-- Tests -->
<a href="https://github.com/MaxHalford/chime/actions?query=workflow%3Atests">
<img src="https://github.com/MaxHalford/chime/workflows/tests/badge.svg?style=flat-square" alt="tests">
</a>
<!-- Soundboard -->
<a href="https://chime-soundboard.herokuapp.com/">
<img src="https://github.com/MaxHalford/chime/workflows/soundboard/badge.svg?style=flat-square" alt="soundboard">
</a>
<!-- PyPI -->
<a href="https://pypi.org/project/chime">
<img src="https://img.shields.io/pypi/v/chime.svg?label=release&color=blue&style=flat-square" alt="pypi">
</a>
<!-- PePy -->
<a href="https://pepy.tech/project/chime">
<img src="https://img.shields.io/badge/dynamic/json?style=flat-square&maxAge=86400&label=downloads&query=%24.total_downloads&url=https%3A%2F%2Fapi.pepy.tech%2Fapi%2Fprojects%2Fchime" alt="pepy">
</a>
<!-- License -->
<a href="https://opensource.org/licenses/MIT">
<img src="https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square" alt="license">
</a>
</div>
<br>
## Table of contents
- [Table of contents](#table-of-contents)
- [Motivation](#motivation)
- [Installation](#installation)
- [Basic usage](#basic-usage)
- [Theming](#theming)
- [IPython/Jupyter magic](#ipythonjupyter-magic)
- [Exception notifications](#exception-notifications)
- [Command-line usage](#command-line-usage)
- [Platform support](#platform-support)
- [I can't hear anything 🙉](#i-cant-hear-anything-)
- [Setting a default theme](#setting-a-default-theme)
- [Command-line arguments](#command-line-arguments)
- [Adding a new theme](#adding-a-new-theme)
- [Things to do](#things-to-do)
- [Acknowledgements](#acknowledgements)
- [License](#license)
## Motivation
I 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`!
## Installation
```sh
pip install chime
```
This 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.
## Basic usage
`chime` puts four functions at your disposal:
```py
>>> import chime
>>> chime.success()
>>> chime.warning()
>>> chime.error()
>>> chime.info()
```
Calling 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.
## Theming
The sounds that are played depend on which theme is being used.
```py
>>> chime.theme() # return the current theme
'chime'
```
Several themes are available:
```py
>>> chime.themes()
['big-sur', 'chime', 'mario', 'material', 'pokemon', 'sonic', 'zelda']
```
The theme can be changed by passing a theme name to the `theme` function:
```py
>>> chime.theme('zelda')
```
A couple of things to note:
- You can listen to the sounds interactively via [this soundboard](https://chime-soundboard.herokuapp.com/), which is made with [Streamlit](https://www.streamlit.io/).
- A random theme will be picked each time you play a sound if you set the theme to `'random'`.
## IPython/Jupyter magic
Load the extension as so:
```py
%load_ext chime
```
You can wrap a line:
```py
%chime print("I'm a line")
```
You can also wrap an entire cell:
```py
%%chime
print("I'm a cell")
```
The magic command will call `chime.success` when the line/cell finishes successfully. Otherwise, `chime.error` is called whenever an exception is raised.
## Exception notifications
If you run `chime.notify_exceptions`, then `chime.error` will be called whenever an exception is raised.
```py
chime.notify_exceptions()
raise ValueError("I'm going to make some noise")
```
## Command-line usage
You can run `chime` from the command-line:
```sh
$ chime
```
By default, this will play the success sound. You can also choose which sound to play, like so:
```sh
$ chime info
```
You can also choose which theme to use:
```sh
$ chime info --theme zelda
```
If you're using bash, then you can use `chime` to notify you when a program finishes:
```sh
$ echo "Hello world!"; chime
```
This 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:
```sh
> echo "Hello world!" & chime
```
## Platform support
Under 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:
- Darwin
- Linux
- Windows
A `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.
## I can't hear anything 🙉
Did you check if you turned your sound on? Just kidding. 😜
This 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:
```py
>>> chime.info(sync=True)
```
This 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:
```py
>>> chime.info(sync=True, raise_error=True)
```
Note that setting `raise_error` won't do anything if `sync` is set to `False`.
## Setting a default theme
To change the default theme a configuration file may be created in `~/.config/chime/chime.conf` on Unix or `%APPDATA%\chime\chime.ini` on Windows.
For example, to change the default theme to `'zelda'`, the configuration file would contain:
```ini
[chime]
theme = zelda
```
## Command-line arguments
Chime 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`:
```py
>>> chime.RUN_ARGS = "--device sysdefault:CARD=PCH"
```
You can also specify this as a default configuration in the configuration file:
```ini
[chime]
cli_args = '--device sysdefault:CARD=PCH'
```
At 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.
## Adding a new theme
I 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.
Be creative! 👩🎨
## Things to do
- Some mechanism to automatically call `chime.warning` when a warning occurs.
- Make it work with a remote machine. For instance a Jupyter Notebook hosted on a remote machine.
- More themes!
## Acknowledgements
- Special thanks to [Michael Vlah](https://github.com/vlahm) for being a gentleman by giving up the "chime" name on PyPI.
- Thanks to u/Pajke on reddit for helping me debug Windows support.
- 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).
- Thanks to [Vincent Warmerdam](https://twitter.com/fishnets88) for suggesting a command-line interface.
- Calmcode made a [video introduction to chime](https://calmcode.io/chime/introduction.html) ❤️
- Thanks to [Paulo S. Costa](https://github.com/paw-lu) for contributing in many different ways.
- Thanks to [d34d_m8](https://github.com/d34dm8) for adding OpenBSD support.
## License
As you would probably expect, this is [MIT licensed](LICENSE).
Raw data
{
"_id": null,
"home_page": "https://github.com/MaxHalford/chime",
"name": "chime",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6,<4.0",
"maintainer_email": "",
"keywords": "notifications,sound,wav",
"author": "Max Halford",
"author_email": "maxhalford25@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/94/bc/918e3769666d918904b70f1fbdabfc3fbc3fbe97240a2a610b98b9b3fe0e/chime-0.7.0.tar.gz",
"platform": null,
"description": "<div align=\"center\">\n <h1>chime</h1>\n <q><i>Python sound notifications made easy.</i></q>\n</div>\n<br>\n\n<div align=\"center\">\n <!-- Tests -->\n <a href=\"https://github.com/MaxHalford/chime/actions?query=workflow%3Atests\">\n <img src=\"https://github.com/MaxHalford/chime/workflows/tests/badge.svg?style=flat-square\" alt=\"tests\">\n </a>\n <!-- Soundboard -->\n <a href=\"https://chime-soundboard.herokuapp.com/\">\n <img src=\"https://github.com/MaxHalford/chime/workflows/soundboard/badge.svg?style=flat-square\" alt=\"soundboard\">\n </a>\n <!-- PyPI -->\n <a href=\"https://pypi.org/project/chime\">\n <img src=\"https://img.shields.io/pypi/v/chime.svg?label=release&color=blue&style=flat-square\" alt=\"pypi\">\n </a>\n <!-- PePy -->\n <a href=\"https://pepy.tech/project/chime\">\n <img src=\"https://img.shields.io/badge/dynamic/json?style=flat-square&maxAge=86400&label=downloads&query=%24.total_downloads&url=https%3A%2F%2Fapi.pepy.tech%2Fapi%2Fprojects%2Fchime\" alt=\"pepy\">\n </a>\n <!-- License -->\n <a href=\"https://opensource.org/licenses/MIT\">\n <img src=\"https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square\" alt=\"license\">\n </a>\n</div>\n<br>\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 \ud83d\ude49](#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>>> import chime\n\n>>> chime.success()\n>>> chime.warning()\n>>> chime.error()\n>>> 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>>> chime.theme() # return the current theme\n'chime'\n\n```\n\nSeveral themes are available:\n\n```py\n>>> chime.themes()\n['big-sur', 'chime', '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>>> 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.herokuapp.com/), 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> echo \"Hello world!\" & 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 \ud83d\ude49\n\nDid you check if you turned your sound on? Just kidding. \ud83d\ude1c\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>>> 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>>> 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>>> 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! \ud83d\udc69\u200d\ud83c\udfa8\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) \u2764\ufe0f\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",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python sound notifications made easy.",
"version": "0.7.0",
"project_urls": {
"Homepage": "https://github.com/MaxHalford/chime",
"Repository": "https://github.com/MaxHalford/chime"
},
"split_keywords": [
"notifications",
"sound",
"wav"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "84e49d2a6bbfcb11dff0bda0cd886fbf20f669260610e413c1be1537dbb4a5c1",
"md5": "154be29850bcc53bbe28ab706641ed39",
"sha256": "9626f8151cb008b1e0ffb7de6d1834b7013ba5fc4c4e3c9ba6e29dc9bf5feac6"
},
"downloads": -1,
"filename": "chime-0.7.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "154be29850bcc53bbe28ab706641ed39",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6,<4.0",
"size": 3907551,
"upload_time": "2023-02-20T10:05:16",
"upload_time_iso_8601": "2023-02-20T10:05:16.484443Z",
"url": "https://files.pythonhosted.org/packages/84/e4/9d2a6bbfcb11dff0bda0cd886fbf20f669260610e413c1be1537dbb4a5c1/chime-0.7.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "94bc918e3769666d918904b70f1fbdabfc3fbc3fbe97240a2a610b98b9b3fe0e",
"md5": "870d3e51139a948c7e34e04899f2e295",
"sha256": "ba4af8934ec8bd9a89a340b4433b2e500097b979823386432be7128e0b201f0d"
},
"downloads": -1,
"filename": "chime-0.7.0.tar.gz",
"has_sig": false,
"md5_digest": "870d3e51139a948c7e34e04899f2e295",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6,<4.0",
"size": 3923153,
"upload_time": "2023-02-20T10:05:40",
"upload_time_iso_8601": "2023-02-20T10:05:40.199673Z",
"url": "https://files.pythonhosted.org/packages/94/bc/918e3769666d918904b70f1fbdabfc3fbc3fbe97240a2a610b98b9b3fe0e/chime-0.7.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-02-20 10:05:40",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "MaxHalford",
"github_project": "chime",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "chime"
}
JSON
