Skip to main content

A package to play an alarm after an interval

Project description

PyBites Alarm

Play a music file or voice message after an interval of N minutes or seconds.

Install the tool

$ pip install pybites-alarm
$ alarm
usage: alarm [-h] (-s SECONDS | -m MINUTES) [-b | -d] [-l SONG_LIBRARY | -f FILE | -M MESSAGE] [-v] [-t TIMEOUT]
alarm: error: one of the arguments -s/--seconds -m/--minutes is required

Note that you'll need ffmpeg to play an alarm sound file. You'll also need libasound2-dev on Linux. On Windows you will additionally need Visual Studio tools. Currently it does not work great yet on WSL.


You can specify an interval time using seconds (-s) or minutes (-m).

By default it runs in the foreground, but on Mac/Linux (not Windows) you can run it in the background using -b.

To display the seconds countdown use -d.

There are three ways to play an alarm file:

  1. Specify one with -f.

  2. Pick a random file from your music library directory. For that use -l.

  3. Use a default file by setting ALARM_MUSIC_FILE in .env, for example:

    $ cat .env

Voice messages

It can be confusing when a music file plays so since 0.0.4 you can play a voice message instead using -M (--message).

For example:

alarm -M "stand up for a walk" -m 20 -b

A voice repeats "stand up for a walk" three times after 20 minutes. Pretty useful for programmers :)

Duration of the alarm

For long alarm files you can set a timeout to stop the alarm after N seconds using the t (--timeout) switch.

Repeating an alarm

Since version 0.0.6 you can repeat an alarm using the -r switch. For example, to track 25 minute pomodoro time blocks (as per the Pomodoro Technique), you can run this command:

alarm -m 25 -M "pomodoro completed" -r 4

A voice will notify you every 25 minutes (for 4 times) that you have completed a pomodoro.

Another use case is to have it alert you to stand up and drink more water during the day - direct health benefits :)

Here are all the supported options again:

$ alarm -h
usage: alarm [-h] (-s SECONDS | -m MINUTES) [-b | -d] [-l SONG_LIBRARY | -f FILE | -M MESSAGE] [-v] [-t TIMEOUT]

Play an alarm after N minutes

optional arguments:
  -h, --help            show this help message and exit
  -s SECONDS, --seconds SECONDS
                        Number of seconds before playing alarm (default: None)
  -m MINUTES, --minutes MINUTES
                        Number of minutes before playing alarm (default: None)
  -b, --background      Run timer in the background (default: False)
  -d, --display_timer   Show timer in console (default: False)
  -l SONG_LIBRARY, --song_library SONG_LIBRARY
                        Take a random song from a song library directory, supported formats: .mp3, .mp4, .wav (default: None)
  -f FILE, --file FILE  File path to song to play as alarm (default: None)
  -M MESSAGE, --message MESSAGE
                        Set an audio message to play for alarm (default: None)
  -v, --version         show program's version number and exit
  -t TIMEOUT, --timeout TIMEOUT
                        Stop alarm after N seconds (default: None)
  -r REPEAT, --repeat REPEAT
                        Repeat alarm cycle N times (only works in foreground) (default: 1)

Again the -b option is not available on Windows, although it seems you can get that working with:

start /b alarm -s 3 -f test.mp3

This backgrounds a process on windows and CTRL + BREAK/SCRLLCK kills it. Or use the -t option, e.g. start /b alarm -s 3 -f test.mp3 -t 20 (thanks Lee!)

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pybites-alarm-0.0.6.tar.gz (5.2 kB view hashes)

Uploaded Source

Built Distribution

pybites_alarm-0.0.6-py3-none-any.whl (8.0 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page