Making a command line countdown timer

Today, I’ll show you how to make a command line countdown timer for Bash, using Bash functions. We’ll discuss the approach behind the problem before writing any code, so that way our solution will be robust and satisfy our needs.

I made this tool when I noticed myself opening DuckDuckGo or Google and searching for “countdown timer” when I needed one. By writing a few lines of Bash, I can start a countdown timer without having to open a web browser.

Intuition

Before we start writing code, let’s think about the intuition behind making a countdown timer. We’ll want to keep in mind what common functions we already have access to in the terminal, such as date, and make use of those.

So, what is a countdown timer? Suppose you set a countdown for thirty seconds. You expect that thirty seconds after you start it, a sound will go off. But we need to translate that into something that we could write in Bash.

This is where we need to find a balance between complexity and utility. In theory, you might be able to set a countdown timer for a certain number of seconds, or minutes, or hours, or some combination of those, like one hour and five minutes. The ability to enter any arbitrary time, like 1 hour, 23 minutes, and 5 seconds, could make the input handling relatively complex. For my use case, I only needed to set minutes, and sometimes hours, but never a combination of the two. Based on these requirements, I could simply the input quite a bit.

When writing software (at least in my experience) it’s common to use seconds as a base unit of time measurement, translating that to minutes or hours by some multiplication when needed. So we can make a timer based on seconds, and then extend it to support minutes and hours relatively easily.

The other thing we should think about is how to keep track of the passing of time. A good first approach is to make use of sleep n, which pauses execution for n seconds. If you don’t need to display the remaining time, then this might be the a simple, reliable solution. But often we want to display how much time is remaining, and if you start to think about using sleep 1 and keeping track of the number of seconds that have passed, then you’ll face some trouble when trying to print the remaining time on the screen. If someone sets a timer for 80 seconds, it would make sense to display the time remaining in a proper format, starting at 01:40 and then going to 01:39, 01:38, and so on.

All of this conversion will end up making your program more of a time calculator than a simple countdown timer!

As I mentioned at the beginning, date, a utility which shows the current system time, will be useful for solving this problem because it will take care of the time formatting.

Now that we have thought about the major considerations for this problem, let’s begin writing the function that will do the majority of the work.

The main function to handle seconds

I typically put these in a separate file called .bash_functions which I then include in my .bashrc, like this:

if [ -f ~/.bash_functions ]; then
    . ~/.bash_functions
fi

I give these functions short names because they’re faster to type when you need to launch a timer.

First, we’ll figure out when the timer should stop. If we set a timer for 30 seconds, we want the time to stop 30 seconds in the future. We can get this time by getting the current Unix time and adding the number of seconds that we set.

+%s says “format the date output as the number of seconds since the Unix epoch. The $1 is the first argument that we give when calling the function. For example, if we were to run ts 10 in the terminal, $1 would be the value 10. The $() that wraps around the whole expression allows us to store the output in a variable, which we have called date.

function ts()
{
  date=$((`date +%s` + $1));
}

Next, we’ll add a loop that checks if the current Unix time is less than the end time, and if so, it prints out the amount of time remaining every second.

The while loop condition uses the -ne (not equal) comparison to perform our check. There’s a little more going on here in terms of syntax (fun fact, [ is actually a command, not simply parenthesis like in other programming languages), but for the sake of this post we won’t dive deep into the syntax of Bash.

Inside the loop, we print out the current time remaining. Essentially, we get the number of seconds remaining with subtraction and then use the date command again, this time giving it a date (in terms of seconds) to print out in the given format, +%H:%M:%S. There’s actually quite a lot going on in this one line, so let’s look at the function so far and then explore how that one line works.

function ts()
{
  date=$((`date +%s` + $1));
  while [ "$date" -ne `date +%s` ]; do
    echo -ne "  $(date -u --date @$(($date - `date +%s`)) +%H:%M:%S)\r";
    sleep 1
  done
}

Let’s start from the inside and work our way out. In $date - `date +%s`, we subtract the current date in seconds since the Unix epoch from the future date we stored in the date variable. The result is the number of seconds until the end date.

$(($date - `date +%s`)) allows us to use the resulting value in other places. In this case, it becomes the argument to the --date flag. The extra parenthesis are needed so that the inner expression fully evaluates first. Try playing around with $(4 + 3) in your terminal. You can’t do this because you can’t do arithmetic operations wherever you want in Bash. The shell will treat 4 as a command to be executed.

Then we call date with a couple flags, one of them being -u for UTC time. This prevents the +/- adjustments that the clock makes for your time zone. Hopefully you will realize that we’re kind of abusing date.

The last part of the date command is +%H:%M:%S, which prints out the date in the given format of hours : minutes : seconds.

The -ne flags for echo are not the -ne that means not equal to. These flags just happen to have the same letters, but they are really two separate flags. n tells echo to not print newlines, and e allows us to use backslashes. We need to a backslash to print the \r character, which return the “carriage” to the start of the line. You might see where this is going.

After the echo, we sleep for one second and start the loop again.

The creative \r allows us to print the remaining time in the same place on the screen, giving the appearance of a traditional countdown timer.

Playing sound

After sleep 1, I have the line play_sound ~/downloads/whatever.wav, and my play_sound function is as follows.

function play_sound()
{
  cat $1 | aplay
}

However, the method to play sound might differ depending on your operating system. This works for me on Debian.

Some helpers for minutes and hours

If you want to set a timer for minutes and hours without doing math in your head, some quick helper functions that call the original one will do the trick.

function tm()
{
  echo "Timer set for $1 minutes"
  ts $1*60
}

function th()
{
  echo "Timer set for $1 hours"
  ts $1*60*60
}

End result

Putting everything together, this is what we created:

function ts()
{
  date=$((`date +%s` + $1));
  while [ "$date" -ne `date +%s` ]; do
    echo -ne "  $(date -u --date @$(($date - `date +%s`)) +%H:%M:%S)\r";
    sleep 1
  done
  play_sound ~/downloads/whatever.wav
}

This is an example of what the output looks like, with the time remaining updating every second.

john@thinkpad ~ $ tm 4
Timer set for 4 minutes
  00:03:53

We did some clever things with date to create our own command line timer. Hopefully this gives you an idea of how to approach a programming problem as well as insights on how to use many small Unix utilities to make something useful.

Found a mistake? Edit this post.