🎵 Python sound notifications made easy
Alternatives To Chime
Project NameStarsDownloadsRepos Using ThisPackages Using ThisMost Recent CommitTotal ReleasesLatest ReleaseOpen IssuesLicenseLanguage
Ohmyzsh162,7091511 hours ago1December 07, 2014582mitShell
🙃 A delightful community-driven (with 2,100+ contributors) framework for managing your zsh configuration. Includes 300+ optional plugins (rails, git, macOS, hub, docker, homebrew, node, php, python, etc), 140+ themes to spice up your morning, and an auto-update tool so that makes it easy to keep up with the latest updates from the community.
a month ago42mit
🇫🇷 Oh my tmux! My self-contained, pretty & versatile tmux configuration made with ❤️
Fx17,41511202 days ago52May 08, 20232mitGo
Terminal JSON viewer & processor
Terminalizer14,50161010 days ago37July 15, 202393mitJavaScript
🦄 Record your terminal and generate animated gif images or share a web player
17 days ago184mitShell
The configuration framework for Zsh
77 months ago52June 03, 2019103mitPython
Browse Reddit from your terminal
Resume Cli4,29393597 months ago107October 23, 202298mitJavaScript
CLI tool to easily setup a new resume 📑
Reapp3,511337 years ago79May 13, 201539mitJavaScript
[deprecated!] Make hybrid mobile apps with power
86 months ago27April 07, 201921mitPython
Because sometimes you need to do it live
4 years ago55mitJavaScript
>_ Electron based NodeJS REPL :see_no_evil:
Alternatives To Chime
Select To Compare

Alternative Project Comparisons


Python sound notifications made easy.

Table of contents


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!


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:

>>> import chime

>>> chime.success()
>>> chime.warning()
>>> chime.error()

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

Several themes are available:

>>> chime.themes()
['big-sur', 'chime', 'future', 'mario', 'material', 'pokemon', 'sonic', 'zelda']

The theme can be changed by passing a theme name to the theme function:

>>> chime.theme('zelda')

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 'random'.

IPython/Jupyter magic

Load the extension as so:

%load_ext chime

You can wrap a line:

%chime print("I'm a line")

You can also wrap an entire cell:


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.


raise ValueError("I'm going to make some noise")

Command-line usage

You can run chime from the command-line:

$ chime

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

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 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:

  • 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:


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:

>>>, 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:

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:

>>> chime.RUN_ARGS = "--device sysdefault:CARD=PCH"

You can also specify this as a default configuration in the configuration file:

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 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 that adds the necessary .wav files to the themes directory. 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!


  • 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.
  • Thanks to d34d_m8 for adding OpenBSD support.


As you would probably expect, this is MIT licensed.

Popular Command Line Projects
Popular Theme Projects
Popular Command Line Interface Categories
Related Searches

Get A Weekly Email With Trending Projects For These Categories
No Spam. Unsubscribe easily at any time.
Command Line