How the timer works

This page explains how the timer keeps time, when colours and sounds change, and how we check it.

Keeping accurate time

Browsers slow down or pause timers in tabs you aren't looking at. Chrome, for example, limits background timers to once per second, and after a tab has been hidden for a few minutes it can batch them to roughly once per minute. A timer that counts ticks would fall behind whenever you switch to your slides.

So this timer never counts ticks. When you press Start it records the exact moment the current phase will end, using the browser's monotonic clock (performance.now(), which isn't affected by the computer's clock being adjusted). Every time the screen updates, it subtracts the current time from that end time. However late an update runs, the time left is correct.

In station rotations each new phase is scheduled from the previous phase's end time, not from the moment the browser noticed it ended. That way a late update never adds drift across a long rotation.

Pausing stores the time left; starting again sets a new end time. Pressing +1 min moves the end time one minute later.

What the display shows

Digits round up to the whole second, so a 5 minute timer shows 5:00 when it starts and 0:01 until the very end.
The disc is the fraction of the current phase left. It starts full and shrinks clockwise.
Colours: green while more than 50% is left, yellow from 50% to 20%, red for the last 20%. Switch time between stations is purple. Turning off colour changes keeps work time green.

Sounds

A two-note warning chime when 1:00 is left, only on timers longer than 90 seconds.
Three short blips at 3, 2 and 1 seconds left.
A four-note rising chime, played twice, at the end. A different four-note sound marks each station switch.
Sounds are generated in the browser (Web Audio). Browsers only allow sound after a tap or key press, so sound starts when you press Start or the speaker button.

Station rotation math

Total time = stations × time per station + (stations − 1) × switch time. For example, 4 stations of 15 minutes with 1 minute switches is 4 × 15 + 3 × 1 = 63 minutes. There is no switch after the last station.

Screen and full screen

While the timer runs, the page asks for a screen wake lock (where the browser supports it) so the display doesn't sleep. Show to class asks for full screen; on devices that don't allow it, the page still hides every control.

How we test it

Automated tests run the timing core with updates arriving only once per minute, as in a throttled background tab, and check that the timer finishes at exactly the scheduled moment.
Tests check that a late update during a rotation does not shift the next station's end time, and that a tab asleep through several phases wakes up in the right phase with the right time left.
Rotation totals are checked against hand calculations, such as the 63 minute example above.
A browser test runs the real page with a simulated clock jumped forward by minutes at a time and checks the display and the end screen.

Questions or a timing problem? Tell us.