dingpy 1.0.6

parameter name standardize

DingPy 🛎

A Python package that plays an audio alert when your program finishes, especially helpful for long running jobs and impatient developers.

Examples

import dingpy

dingpy.ding()  # plays the default alarm 'japanese_temple_bell'

# to use a different alarm sound:
dingpy.ding(sound='music_box')

# to list all available alarms
dingpy.list_alarms()

Alarm Options

Dingpy comes pre-loaded with 10 royalty free alarm sounds (downloaded from http://soundbible.com/) and you can choose which one to use via the sound parameter.

• 'beep'
• 'bell_tibetan'
• 'birds'
• 'clock_chimes'
• 'computer_magic'
• 'japanese_temple_bell'
• 'music_box'
• 'school_bell'
• 'service_bell'
• 'tinkle'

The 10 audio files are packaged and downloaded when you install dingpy. You can further customize dingpy by asking it to use a mp3 file from your local directory via the path parameter:

dingpy.ding(path='/absolute_path_to_file/sound.mp3')

If you'd like to contribute your mp3 file for other dingpy users to access, you can upload it to the public dingpy s3 bucket:

# sound_name needs to be globally unique
dingpy.upload_alarm(
    file_path='/absolute_path_to_file/sound.mp3', 
    sound_name='beeep') 

# verify that your upload is successful by calling list_alarms again
# and tell it to look for all alarms 
# (without all=True list_alarms will only return the 10 pre-built sounds)
dingpy.list_alarms(all=True)

After your mp3 file is uploaded, they can be used by other people if they pass in the sound name and set the s3 parameter to be True:

dingpy.ding(sound='beeep', s3=True)

Note that the mp3 file will be downloaded each time dingpy.ding() is called.

To delete an uploaded alarm (the 10 pre-loaded alarms can't be deleted):

dingpy.delete_alarm('beeep')

Installation

DingPy can be installed via pip like this

$ pip install dingpy

or from the source code like this

$ pip install git+https://github.com/tinahbu/dingpy.git

or this

$ git clone [e-mail]:tinahbu/dingpy.git
$ cd dingpy
$ python setup.py install

Prerequisite

For the pydub library to work with non-wav files like mp3, you will need to have ffmpeg or libav installed locally.

$ # install ffmpeg
$ # for Mac
$ brew install ffmpeg --with-theora
$ 
$ # for Linux
$ apt-get install ffmpeg libavcodec-extra

$ # install libav
$ # for Mac
$ brew install libav --with-libvorbis --with-sdl --with-theora
$ 
$ # for Linux
$ apt-get install libav-tools libavcodec-extra

As stated above, the 10 default alarms are packaged with dingpy but user uploaded alarms are hosted in a public s3 bucket. So if you'd like to use the customization feature you will have to have aws cli configured. To do that, follow the doc here.

dingpy only works with Python3.

Future Work

• Make available on conda
• Support other audio formats besides mp3
• Support text to speech alerts
• Integrate with pync to send MacOS notifications
• Local ding for jobs running on remote machines

Inspirations

I always wanted a Python package that notifies me with a ding when my code completes so I can go about doing other work in the meantime. I couldn't really find one after quite some research so I decided to create dingpy for myself. And hopefully it will be helpful to you as well. That being said, if most of your work happens in the terminal or if you prefer to have a pop-up MacOS notification than an audible alarm, do checkout the projects below:

• pync a Python package to send MacOS notifications (Mac only) (it claims to offer sound notification with the pop-up notification but I couldn't make it work)
• ding a CLI alarm tool for local and remote jobs (it seems that you will have to provide your own alarm audio file and keep a terminal open running this code the whole time for the alarm to work. not a python package that can be imported)
• woof a set of CLI tools to send notifications (options: music, growl notification, text message, tweet, twitter DM, email, and text-to-speech) (Mac only) (have to save alarm audio locally and modify bash profile to set proper paths, only works in the terminal)
• notify2 a Python package that sends a MacOS notification (seems not maintained, after installation I got import error for dbus and wasn't able to install dbus properlly to test it out)