Clock Chimes: Documentation

System Requirements

Clock Chimes has three dependencies: bash, a scheduler and a media player.

• bash

  Clock Chimes is a bash script. The bash command interpreter is required to run it.

• Scheduler

  A scheduler such as a systemd timer or cron is required to activate the script at the necessary times.

  If using systemd, version 242 or higher is recommended. Version 242 was released in 2019 making it likely most (if not all) Linux distributions using systemd already meet this requirement.

• Media Player

  A command line application which plays media files. The default player is cvlc (the command line version of VLC), however, you can change this to an application of your preference.

Download

Clock Chimes is free to download and use. Documentation and source files are included with the archive and online. The project source and assets are also available at GitHub.

Download Clock Chimes

Installation Instructions

Installation is performed by running the following command within a Terminal application:
bash ./install.sh install

A prompt will inform you once installation has completed.

The installer places a bash script, configuration file and sound files into your home directory.

A systemd timer and service will be registered on computers using systemd.

A cron script will be installed on computers using cron.

See the Default Configuration and Installation Notes sections for information regarding defaults used during service configuration and installation.

See the file manifest page for information regarding where files are installed.

Installation Notes

The installation program defaults to using a systemd timer for scheduling.

systemd, version 242 or higher is recommended however older versions probably could be made to work. In the unlikely event an older version of systemd is in use, with modification, the clock_chimes service file could be made to work with systemd versions back to version 209 (which was released in 2014). Versions of systemd prior to 209 will not work because the timer functionality was not available. Computers using a version of systemd prior to version 209 will need to use cron as a scheduler.

The clock_chimes.sh script is written in bash and with minimal calls out to other applications. Under default conditions, the program only uses:

• date (usually at /usr/bin/date)
• sed (usually at /usr/bin/sed)
• the chosen media player which by default is cvlc (usually at /usr/bin/cvlc)
• your PAGER application which typically is less (usually at /usr/bin/less)

The install script is written in bash and calls the following programs which should be present on most computers:

• echo (typically a shell builtin or /usr/bin/echo)
• install (usually at /usr/bin/install)
• mkdir (usually at /usr/bin/mkdir)
• rm (usually at /usr/bin/rm)
• sed (usually at /usr/bin/sed)
• which (usually at /usr/bin/which)

Depending on whether scheduling systemd or cron is used, systemctl or sudo will also be called.

• systemctl (usually at /usr/bin/systemctl)
• sudo (usually at /usr/bin/sudo)

Note: It is expected Clock Chimes should work with other operating systems such as FreeBSD, MacOS, OpenBSD, et cetra, however the installer has not been tested with these environments and will likely show an error message and exit or simply not work as expected. Please see the file manifest for information regarding where to manually place files.

Usage

TLDR

I want to test the script now and hear what it sounds like, how do I do that?

Running the Clock Chimes Ring command will cause a single chime sound to play. Within a Terminal application, run:

clock_chimes.sh -r

More Information

The installer handles all necessary configuration. After the installer completes, no further action is required. With the default configuration, the chimes will sound at the beginning of each hour and thirty minutes past the hour.

Activation occurs when a systemd timer or cron job triggers clock_chimes.sh. The clock_chimes.sh script will determine whether and how many times to play the chime sound. The systemd service file or cron job should be pointed to the clock_chimes.sh script, typically stored in ~/bin or ~/.local/bin. No arguments are required.

To run or test Clock Chimes, run any of the commands shown below.

Run Clock Chimes. Within a Terminal application, run:

clock_chimes.sh

With a default configuration, nothing will appear to happen unless you are running the script at hour or thirty minutes past the hour. See Default Configuration information for details.

To run the Clock Chimes ring command, within a Terminal application, run:

clock_chimes.sh -r

To display the Clock Chimes configuration, within a Terminal application, run:

clock_chimes.sh -c

To test the default Clock Chimes configuration, within a Terminal application, run:

clock_chimes.sh -t

Note: Press Control z to abort testing. Depending on a number of factors, testing can take a long time. I won't tell anyone you pressed Control z.

Command Reference

The Clock Chimes script contains several commands which can be used to alter output.

Display Help

-h

Display the built-in help page.

Example usage: clock_chimes.sh -h

Display Configuration

-c [file path]

Display configuration information.

If no file path is specified, the default value $HOME/.config/chimes/clock_chimes.config is used.

Example usage: clock_chimes.sh -c $HOME/.config/chimes/clock_chimes.config
Example usage: clock_chimes.sh -c

Load Configuration

-l file path

Run clock_chimes.sh with specified configuration file.

Example usage: clock_chimes.sh -l $HOME/.config/chimes/clock_chimes.config

Ring the Chime

-r

Rings the chime one time.

Example usage: clock_chimes.sh -r

Test Configuration

-t

Test the default Clock Chimes configuration. Press Control z to abort testing.

Example usage: clock_chimes.sh -t

Mute/Unmute Playback

-m yes|no

Mute Clock Chimes.

Example usage: clock_chimes.sh -m yes

Unmute Clock Chimes.

Example usage: clock_chimes.sh -m no

See the Muting Guide for more information regarding available Mute functions.

MuteNext Activations

-n integer

Mute a number of future invocations of Clock Chimes.

Example usage: clock_chimes.sh -n 5

Result: The next five invocations of Clock Chimes are muted.

Example usage: clock_chimes.sh -n 0

Result: The MuteNext function is reset and future invocations of Clock Chimes will play chimes.

See the Muting Guide for more information regarding MuteNext and other available Mute functions.

Variable Configuration Guide

The behavior of Clock Chimes is governed by variables which can be changed via configuration files.

The information which follows is regarding variables contained within clock_chimes.sh.

configFile

configFile file path

Path to configuration file necessary to populate variables.

The default value is: $HOME/.config/chimes/clock_chimes.config

This variable can be configured at run time by specifying the load command (-l).

useSimpleChime

useSimpleChime yes|no

Configures whether to use a simple chime tone or melodies. When configured to yes, a simple chime is played. When configured to no, a melody is played. The default bundled melodies are the Westminster chimes melodies.

Default value is: no

Example configuration: useSimpleChime="no"

quietTime

quietTime array

Set the array quietTime with a list of hours when chimes should not play. The quietTime array requires input values in 24 hour time meaning 1 p.m. = 13, 2 p.m. = 14, 11 p.m. = 23. Midnight/12 a.m. is 0.

Default value is: quietTime=(00 1 2 3 4 5 6 7 22 23)

Example: quietTime=(22 23 0 1 2 3 4 5)

Result: Chimes will not ring between 10 p.m. and 5 a.m.

muted

muted yes|no

Configures whether chimes should play or not. This behaves similarly to quietTime but is not time dependent.

Default value is: no

Example: muted="no"

See the Muting Guide for more information regarding the Mute function.

muteNext

muteNext integer

When set, this number of future invocations of Clock Chimes will automatically be muted. This behaves similarly to muted and quietTime but is independent of both.

Default value is: 0

Example: muteNext=0

Note that when this value is configured, with each run of Clock Chimes, the value will decrement by one until reaching zero. Upon reaching zero, chimes will sound again. The length of time required to reach zero depends on the frequency with which Clock Chimes is activated. If activating hourly, a value of three would mute for three hours. Similarly, if activating every thirty minutes (such as at the beginning of the hour and 30 minutes past), a setting of 3 would mute for 90 minutes.

Additionally note, if a computer is placed in sleep mode or shutdown while this value is configured, it will resume decrementing with the next run of Clock Chimes. Note that on computers with systemd, upon waking the computer from sleep mode, the script will run once. See notes in Known Issues.txt and Question 15 in Read Me.txt.

See the Muting Guide for more information regarding MuteNext and other available Mute functions.

additionalChimeMinutes

additionalChimeMinutes array

Set the array additionalChimeMinutes with a list of minutes when a chime should be played. Accepted values are 00 - 59 and the word "all". Note that at this time, when triggered in this manner, only a simple chime is played.

Default value is: additionalChimeMinutes=()

Example: additionalChimeMinutes=( 22 )

Result: Chimes will also play at 22 minutes after the hour.

*SoundFile

• singleChimeSoundFile file path
• singleChimeFinalSoundFile file path
• hourSoundFile file path
• quarterSoundFile file path
• halfSoundFile file path
• threequarterSoundFile file path

Set the variables to point to appropriate sound files. If using a single chime, singleChimeSoundFile should be a single chime while singleChimeFinalSoundFile contains a chime with a longer fade out. If customizing to use only a single sound file, simply set both variables to the same value or set singleChimeFinalSoundFile to:

singleChimeFinalSoundFile = "$singleChimeSoundFile"

ringChimeWithHourCount

ringChimeWithHourCount yes|no

Set ringChimeWithHourCount whether the chime should ring a number of times corresponding to the hour of day.

Default value is: yes

Example: ringChimeWithHourCount="yes"

Result: At 3:00 p.m. / 15:00, the chime would ring three times

player

player path

Set player to the path of the media player application which will play the sound files. Full path is only necessary if the application does not reside within your $PATH.

Default value is: cvlc

Example: player=/usr/bin/cvlc
Example: player=cvlc

player_config

player_config string

Any additional arguments necessary for the player to run.

Default value is: player_config="--play-and-exit"

Example: player_config="--play-and-exit"
Example: player_config=""

Note: The example assumes cvlc is used. If you update the player variable, be certain to update the player_config variable accordingly. It may be necessary to consult the help or manual pages to find the correct settings.

Default Configuration

The default configuration is heavily tested and what the author has used for over a year prior to making Clock Chimes publicly available.

Clock Chimes only plays melodies and chimes between the hours of 8 a.m. and 9:30 p.m. (21:30) on the hour and half hour (30 minutes past the hour).

Activations occurring on the hour (such as at 3:00 p.m.) will play the hourly melody, followed by one or a series of chimes corresponding to the hour. For example, if it is 3 p.m., three chimes would follow the hourly melody.

Activations occurring at 30 minutes past the hour play the half hour melody.

The default melodies are composition based upon the Westminster Quarters.

The default media player is cvlc, the command line version of VLC media player.

To view the default configuration, run the following command in a Terminal application:
clock_chimes.sh -c. This produce output similar to what is shown below:

Removal Instructions

Removal can be performed by running the following command within a Terminal application:
bash ./install.sh uninstall

A prompt will inform you once removal has finished.

It is recommended you use uninstall command to remove Clock Chimes. If manual removal is necessary, see the file manifest for information regarding where files are installed.