Python sound notifications made easy.
Table of contents
- Table of contents
- Basic usage
- IPython/Jupyter magic
- Exception notifications
- Command-line usage
- Platform support
- I can't hear anything 🙉
- Changing the default theme
- Adding a new theme
- Things to do
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
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.
chime puts four functions at your disposal:
>>> 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.
The sounds that are played depend on which theme is being used.
>>> chime.theme() # return the current theme 'chime'
Several themes are available:
>>> chime.themes() ['big-sur', 'chime', 'mario', 'material', 'zelda']
The theme can be changed by passing a theme name to the
A couple of things to note:
- You can listen to the sounds interactively via this soundboard, which is made with Streamlit.
- A random theme will be picked each time you play a sound if you set the theme to
Load the extension as so:
You can wrap a line:
%chime print("I'm a line")
You can also wrap an entire cell:
%%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.
If you run
chime.error will be called whenever an exception is raised.
chime.notify_exceptions() raise ValueError("I'm going to make some noise")
You can run
chime from the command-line:
By default, this will play the success sound. You can also choose which sound to play, like so:
$ chime info
You can also choose which theme to use:
$ chime info --theme zelda
If you're using bash, then you can use
chime to notify you when a program finishes:
$ 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:
> echo "Hello world!" & chime
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 that you're using. Platform information is available in the
sys.platform variable as well as the
platform module from the standard library. Currently, the supported platforms are:
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:
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
>>> chime.info(sync=True, raise_error=True)
Note that setting
raise_error won't do anything if
sync is set to
Changing the 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:
[chime] theme = zelda
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 that adds the necessary .wav files to the
themes directory. A theme is made up of four files:
info.wav. Be creative! 👩🎨
Things to do
- Some mechanism to automatically call
chime.warningwhen a warning occurs.
- More themes!
- Special thanks to Michael Vlah 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 for adding Linux support by suggesting the use of aplay.
- Thanks to Vincent Warmerdam for suggesting a command-line interface.
- Calmcode made a video introduction to chime ❤️
- Thanks to Paulo S. Costa for contributing in many different ways.
As you would probably expect, this is MIT licensed.
Release history Release notifications | RSS feed
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
|Filename, size||File type||Python version||Upload date||Hashes|
|Filename, size chime-0.6.0-py3-none-any.whl (2.3 MB)||File type Wheel||Python version py3||Upload date||Hashes View|
|Filename, size chime-0.6.0.tar.gz (2.3 MB)||File type Source||Python version None||Upload date||Hashes View|