Session Timer Help

Version 2.5.1 • Visual analog clock timer with selectable completion sounds

Quick Start

👆 Long-Press for Quick Timer

Long-press anywhere on the clock face to instantly start a timer:

Circular layout: Durations arranged in a true clock-face circle with 12 positions around the perimeter
Hour positions: 5-minute increments at standard clock positions (5min at 1 o'clock, 10min at 2, etc.)
60 minutes at 12: Standard hour mark at the top, 30 minutes at bottom (6 o'clock)
Center cluster: Quick intervals (1, 3 minutes) flanking extended durations (75, 90, 105 minutes)
Micro-breaks: 1 and 3 minute options ideal for brief resets, eye breaks, or quick stretches
Timer starts immediately counting up from current time
Long-press again while running to stop

Design rationale: The circular clock-face layout directly mirrors the analog interface behind it, creating instant spatial recognition. Each 5-minute increment occupies its natural clock position, eliminating cognitive translation and leveraging spatial memory—particularly beneficial for individuals with dyscalculia or time-blindness.

Accessibility Impact: This design is particularly beneficial for users with:

Dyscalculia: Eliminates numerical calculation entirely—no need to interpret numbers or perform mental arithmetic
ADHD/Time-blindness: Provides concrete spatial anchors that externalize time awareness, reducing working memory demands
Executive function challenges: Reduces cognitive overhead through direct visual mapping instead of abstract decision-making
General accessibility: Transforms time selection from an abstract numerical choice into a physical gesture that mirrors natural clock reading—users point to the time they want, just as they would read where the minute hand points

Features

⏱️ Timer Modes

Count Up: Starts at specified time and counts forward
Count Down: Counts down to specified end time
Visual arc shows progress around the clock face
Color changes: Green → Orange (10min) → Red (3min)

📱 Mobile Gestures

Shake Device: Toggle timer on/off (start when stopped, stop when running)
- iOS Setup: On first use, tap anywhere when prompted to enable shake gestures. You'll see "Tap anywhere to enable shake gestures" → tap screen → allow motion permission → done!
- Android: Works automatically, no permission needed
- Provides haptic feedback when activated
Long Press: Hold anywhere on clock face for 1 second
- When stopped: Shows quick duration menu with circular clock-face layout
- When running: Stops the timer
Haptic Feedback: Triple-pulse vibration confirmation on all gesture actions

🔔 Completion Alerts

When a timer segment completes, you'll get:

Sound: Musical tone (E + G# harmony)
Vibration: Triple-pulse pattern
Flash: Full-screen visual indicator

Configure these in the Reconfigure Timer modal

⚙️ Advanced Features

Multi-Segment Timers: Chain multiple timers (e.g. Pomodoro: 25min work, 5min break)
Dead Second Hand: Optional 2-second pause at 12 o'clock (mimics luxury watches)
Calendar Export: Export timer schedules to ICS format or Fantastical
Custom Colors: Adjust when timer changes from green → orange → red

URL Schemes

Quick Timer URLs

Create bookmarks or shortcuts with these URL formats:

Count Up (from current time):
timer.html?s=a,HH:MM,30&mode=up

Count Down (to specific time):
timer.html?s=a,15:00,30&mode=down

Manual Start:
timer.html?s=m,12:00,25&mode=down

Custom URL Scheme (macOS)

🔗 sessiontimer:// Protocol

The custom sessiontimer:// URL scheme allows system-level integration on macOS via a native helper application.

Installation:

Build the helper app: cd macos-helper && ./build.sh
Install: cp "build/SessionTimer Helper.app" /Applications/
Register: open "/Applications/SessionTimer Helper.app"
Test: open "sessiontimer://timer?s=a,14:30,30&mode=down"

How it Works:

Helper app translates sessiontimer:// URLs to https://piarasj.github.io/timer/timer.html URLs
macOS opens the URL in your default browser or installed PWA
PWAs cannot register URL schemes — only native apps can handle custom protocols
The helper app acts as a bridge between system-level URLs and the web app

Using with the PWA:

Keep PWA open: If the PWA is already running, macOS may send the URL to the existing PWA window
Browser fallback: If PWA is not running, the URL opens in your default browser
Workflow: Install PWA for offline use, keep it open, and use sessiontimer:// URLs to send timer configurations to it
Limitation: macOS does not consistently prefer PWAs over browser tabs — behavior varies by browser and PWA installation method

Example URLs:

sessiontimer://timer?s=a,14:30,30&mode=down
sessiontimer://segments?data=09:00,25,down|09:25,5,up

💡 Tip: Use iOS Shortcuts or macOS Automator to create one-tap timer launchers with these URLs! On iOS, use direct web URLs since custom URL schemes require the macOS helper app.

PWA Installation

iOS/iPad (Safari)

Open timer in Safari
Tap Share button (square with arrow)
Select "Add to Home Screen"
Tap "Add"

macOS (Safari)

Open timer in Safari
Go to File → Add to Dock

Chrome/Edge

Click the install icon in address bar
Or menu → Install Session Timer

Keyboard Shortcuts

Space: Start/Stop timer
Escape: Close modal/menu

Tips & Tricks

Focus Sessions

Enable Do Not Disturb mode on your device
Hide cursor and dim background (optional in settings)
Dead second hand provides subtle time awareness without distraction

Display Modes

Kiosk Mode: Landscape ≤540px height - all controls hidden
Floating Window: Add ?view=popup to URL for chromeless display

Troubleshooting

Timer not updating after changes?

Clear the PWA cache:

Chrome/Edge: Uninstall PWA, clear site data, reinstall
Safari iOS: Remove from home screen, clear website data, reinstall
Desktop: Hard refresh with Cmd+Shift+R (Mac) or Ctrl+Shift+R (Windows)

Gestures not working?

Shake requires device motion permission (iOS Settings → Safari → Motion)
Long press only works on the clock face, not on buttons/menus

Privacy

Session Timer runs entirely in your browser. No data is sent to external servers. Timer configurations are stored locally using localStorage and can be cleared at any time.

Accessibility and Cognitive Load Reduction

This application is particularly suitable for individuals who experience difficulties with temporal cognition and calculation. Research indicates that people with dyscalculia often have impaired number sense and difficulties in estimating or manipulating temporal intervals (Butterworth, 2010). Similarly, those with executive function deficits, such as individuals with ADHD, frequently demonstrate "time-blindness," defined as impaired awareness of elapsed and future time, which can compromise planning and sustained task engagement (Barkley, 1997; Brown, 2005). For such populations, interpreting analogue clocks or performing time arithmetic can present unnecessary cognitive load, distracting from the primary task. By externalizing time tracking, automating calculations, and presenting progress in an intuitive visual form, this application minimizes distraction and supports task persistence.

References:

Barkley, R. A. (1997). ADHD and the Nature of Self-Control. New York: Guilford Press.
Brown, T. E. (2005). Attention Deficit Disorder: The Unfocused Mind in Children and Adults. Yale University Press.
Butterworth, B. (2010). Foundational numerical capacities and the origins of dyscalculia. Trends in Cognitive Sciences, 14(12), 534–541.

Session Timer v2.5.1
View Source on GitHub • Full README

← Back to Timer