Command-line hacking: paced breathing
This is another in my series of articles on doing unusual and,
perhaps, interesting things with Linux command-line tools and scripts.
This month's example is, perhaps, even more unusual that most
-- a shell script
to guide paced breathing exercises. Paced breathing is simply
breathing with a timer -- a fixed time for breathing in, and a fixed
time for breathing out. A common protocol is to breath in for four
seconds, and then out for six seconds, to give a respiration rate
of six breaths per minutes.
Exercises of this kind are often recommended for people who suffer from stress-related disorders, or just for general relaxation. Paced breathing apps for smartphones are widely available at low cost -- even at no cost, if you're prepared to tolerate the advertising. However, I thought it would be interesting to implement something for the Linux terminal, using just a shell script.
This script generates a kind of moving bargraph display, that provides
visual cues about how to time your breaths. If you have sox and
aplay available, it will also generate rising and falling
audible tones, so it can be used without looking at the terminal.
Although simple, the utility demonstrates some interesting scripting features, particularly around arithmetic.
I haven't included the full source code in this article, because it's
too long. If you're interested, the full source
for paced_breathing is available
from my GitHub repository.
Basic principle
The principle is simple: decide how wide the terminal bar-graph display will be, in terms of character cells. Divide the total length of the breath by that number of cells, to give a time between terminal updates. On each update, draw a new character in the bargraph, and sleep for the calculated time. Continue until the end of the breathing cycle, then start a new line. Repeat indefinitely. For audio playback (more on this below), start the playback of a pre-computed audio file at the start of each breathing cycle.
Arithmetic
The Bash shell does not support floating-point, or even fixed-point arithmetic. The simple solution to this problem ought to be to do all the timing in milliseconds, in the hope that all the math can be done as integers. Unfortunately, Bash does not provide any millisecond-level timing functions, and we need to be able to update the display at intervals of significantly less than one second, in order for the bargraph to get drawn smoothly.
There is not even a generally-available Linux command-line utility that
delays for a number of milliseconds or microseconds. Fedora does
have usleep, but
it is part of a deprecated software package. The standard
sleep utility will delay for a number of milliseconds -- but
it requires an argument as a fractional number of seconds. So there is
a need for at least a little fractional arithmetic in this utility.
We could have the script delegate arithmetic
to a utility like bc. However, I thought it would be fun
to implement fractional division in the shell script itself. It's
practicable to take such an approach because the only place the script
uses non-integer match is when providing a number as an argument to
other utilities (sleep and sox in this
case).
A limitation of this approach, though, is that the script can't actually work with non-integer numbers in its own calculations. So, for example, the breathing times can only be specified as whole numbers of seconds. Still, this is a demonstration of shell scripting, not a fully-featured product, so I can live with this limitation.
To implement non-integer division in a script, the basic approach is
to scale the numerator by a large power of ten, and then divide by the
denominator. For example, to divide 20/3, we might scale by a factor of
100,000, and then divide the resulting 2,000,000 by 3.
The result is 666,666 (since Bash
does this division using integers). Because this result is 100,000
times too large, we must shift the decimal point five places to the
left, to give 6.6666. This kind of string manipulation is well within
the scope of a Bash script (see the div function
in the source code). The choice of scaling factors needs a bit of
care -- a larger scaling factor will give more precision but, if it's
too large, we run the risk of an arithmetic overflow.
Note that we're doing fixed point arithmetic here. I suspect that any kind of floating point arithmetic would be magnificently impractical in a shell script, and there's no need for it in this application.
Once we have the div function, implementing a function to
wait for a number of milliseconds is trivial:
function sleep_ms
{
ms=$(div $1 1000)
sleep $ms;
}
However, as convenient and expressive as this function is, it would be
a mistake to use it. Most obviously, as this sleep_ms
function will be called
dozens of times per second, doing the scripted division that often would
be a waste of CPU resources, and introduce timing errors. Worse, the
call to div is implemented as a sub-shell. It has
to be, because Bash does not provide a way to return a string value
from a function (we're using a string because that's the only way to
pass a non-integer number in Bash).
div writes its result string to stdout in a sub-shell, and
the main script captures the data sent to stdout by the sub-shell.
The use of a sub-shell
here means that we are subject to timing inaccuracies resulting from
the Linux scheduler, quite apart from the CPU load occasioned by
spawning thousands of sub-shells.
So, rather than using the sleep_ms function, we will just
pre-calculate the (fractional) argument needed for sleep, and
call it explicitly. It's not as elegant, but it's a lot more efficient.
There are some other subtleties here that would be extremely important if we were timing air-traffic control operations. Most obviously, it's hard to get millisecond timing when the operations we are doing the timing with take a significant -- and unpredictable -- number of milliseconds themselves. Bash is not all that fast, when we get down to millisecond timing.
Audio
Bash provides no built-in audio support, and nobody would expect it to. This application really does require audio -- I use a rising pitch to indicate breathing in, and a falling pitch for breathing out. That way, the program can be used whilst doing other things, without needing to look at the terminal display.
If I were implementing this application in C, I would run an audio tone generator in a separate thread of execution, and change its pitch whenever the user interface display was updated. That way, the visual and audible cues would always be perfectly in sync.
What we can do instead in a Bash script is to use a utility like
sox to generate the rising and falling pitches in advance,
as audio files (in WAV format, perhaps). For example:
$ sox -n rising.wav synth 2.0 sine 200:400 fade 0.1 0
This invocation of sox generates a frequency sweep from
200Hz to 400Hz that lasts 2.0 seconds. The fade operation
avoids clicking noises at the start and the end of the playback.
We can then use
something like aplay to play the audio files
as the script runs.
The problem here is synchronization -- how do we keep the visual display
and audio in sync? It's not a huge problem, because we know
exactly how long the breathing-in and breathing-out times are. If the
breathing-in time is exactly two seconds, then we need to generate a
rising pitch that last two seconds.
Or do we? In practice, it's not all that clear. Invoking aplay
in a sub-shell will take a certain amount of time, and aplay
itself will take some time to set things up before it starts to play.
So the audio playback will be a little longer than the length of the tone
generated.
If the playback is longer that the breathing time generated in the
visual display, then one audio file will start to play before the
previous one has finished. Depending on the hosts system's audio configuration
that may, or may not, be allowed. Even if it's allowed, it will probably
sound odd.
On the other hand, the audio playback could be too short for the visual display. If the selected breathing time is, again, two seconds, and we want to update the display 40 times in that period, that's an update every 50 msec. But it probably takes, say, 5 msec to make the update, so the total breathing time in the visual display will actually be about 10% longer than expected.
I don't really know any foolproof solution here. On the basis that it's
less catastrophic to have the sound finish a little before the visual
display, rather than after, I've arranged for the audio output to
be shorter than the visual display in each breathing cycle by an
adjustable amount -- defaulting to 200 msec. In practice, if you
want the display and the audio to line up precisely, you'll need
to adjust this quantity (it's called tone_gen_latency
in the script) by a process of trial and error.
Further work
A useful, and simple, addition would be to allow for breath-holding periods
at the end of expiration and inspiration. Simple sleep invocations
should take care of this.
A more complicated extension would be to allow some or all of the various
configuration parameters to be set on the command line, so they can
be changed without editing the script. The Bash built-in command
getopts can simplify this kind of operation, although
it's an interesting exercise to parse a command line using only
standard scripting.
