Skip to content

README.md

Latest commit

 

History

History
198 lines (149 loc) · 5.76 KB

README.md

File metadata and controls

198 lines (149 loc) · 5.76 KB
Raw

Track Split Calculator (Spliterator)

A mobile-optimized web application for coaches and athletes to calculate and track even race splits during track running events. Built for real-time use with one-handed operation and audio feedback.

🔗 Live Demo: Try Spliterator (GitHub Pages)

📦 Repository: github.com/adamengst/spliterator

Features

Core Functionality

  • Even Split Calculation: Automatically calculates target splits based on goal time
  • Real-Time Tracking: Record lap times with a large, easy-to-tap button
  • Audio Feedback: Distinct sounds for fast, on-target, and slow pacing
  • Visual Feedback: Color-coded differences (green = fast, red = slow)
  • Fastest/Slowest Lap Identification: Real-time highlighting during race
  • Race Statistics: Comprehensive post-race analysis

Supported Tracks

  • 400m Outdoor Track: Standard outdoor track
  • 200m Indoor Track: Standard indoor track

Supported Distances

400m Track:

  • 800m, 1500m, 1600m, Mile, 2 Mile, 3000m, 3200m, 5000m, 10000m

200m Track:

  • 600m, 800m, 1000m, 1500m, 1600m, Mile, 2 Mile, 3000m, 3200m, 5000m, 10000m

Getting Started

Installation

  1. Clone or download the project files
  2. Open index.html in a web browser
  3. No build process or dependencies required!

Usage

  1. Configure Race

    • Select track size (400m or 200m)
    • Choose race distance
    • Set goal time (minutes and seconds)
    • Tap "Start Race"

  2. During Race

    • Tap the large button at the bottom of the screen when the runner crosses the lap line
    • Audio feedback plays immediately
    • View real-time differences from target splits
    • Use "Undo" if you accidentally tap

  3. After Race

    • Review complete race statistics
    • See fastest and slowest laps
    • Share results via email or social media

Project Structure

├── index.html          # Main HTML structure
├── style.css           # Mobile-first responsive styles
├── split-engine.js     # Core calculation engine
├── audio.js            # Web Audio API feedback system
├── app.js              # Main application logic
├── manifest.json       # Progressive Web App configuration
├── test-suite.html     # Comprehensive test suite
├── PLANNING.md         # Detailed requirements document
└── README.md           # This file

Testing

Open test-suite.html in a web browser to run the comprehensive test suite. Tests cover:

  • ✅ Split calculation accuracy
  • ✅ Lap recording functionality
  • ✅ Undo operations
  • ✅ Race statistics calculations
  • ✅ Time formatting
  • ✅ Pace categorization
  • ✅ Performance requirements (< 10ms calculations)
  • ✅ Edge cases and boundary conditions

Technical Specifications

Performance Requirements

  • Response Time: < 100ms for split recording
  • Timing Accuracy: < 0.1 second variance
  • Calculation Speed: < 10ms for race configuration
  • Lap Recording: < 5ms per lap

Browser Support

  • iOS Safari (primary target)
  • Android Chrome (primary target)
  • Modern mobile browsers with Web Audio API support

Mobile Optimization

  • One-handed operation
  • Large touch targets (tap button = 20% of screen height)
  • Auto-scroll to keep current lap visible
  • Touch-optimized interface
  • No accidental zoom or scroll interference

Architecture

Split Engine (split-engine.js)

Core calculation logic including:

  • Track and race configuration data
  • Even split calculations
  • Lap time recording
  • Fastest/slowest lap identification
  • Race statistics generation

Audio System (audio.js)

Web Audio API implementation:

  • Synthetic sound generation
  • Three distinct feedback tones:
    • 880 Hz (high) = Fast pace
    • 440 Hz (medium) = Target pace
    • 220 Hz (low) = Slow pace
  • Automatic initialization on user interaction

UI Management (app.js)

Application state and interface:

  • Screen navigation (config → race → results)
  • Form handling and validation
  • Real-time UI updates
  • localStorage persistence
  • Share functionality

Data Storage

Uses browser localStorage for:

  • Race configuration
  • In-progress race data
  • Last race results

No server required - fully client-side operation.

Deployment

WordPress Integration

  1. Upload all files to your WordPress media library or hosting
  2. Embed in a page/post using iframe or direct link
  3. Works as static files - no server-side processing needed

Standalone Hosting

  1. Upload all files to any web server
  2. Serve index.html as the entry point
  3. Works on any hosting (GitHub Pages, Netlify, etc.)

Progressive Web App

The app includes a manifest.json for PWA functionality:

  • Add to home screen on mobile devices
  • Offline-capable (with service worker - future enhancement)
  • Full-screen standalone mode

Future Enhancements (Phase 2)

Planned features for native iOS app:

  • Apple Watch integration
  • Voice feedback (spoken pace differences)
  • Race history and analytics
  • iCloud synchronization
  • Multiple runner tracking
  • Custom track sizes
  • Team management features

Development

Local Development

  1. Open index.html in a browser
  2. Use browser dev tools for debugging
  3. Test on actual mobile devices for best results

Code Style

  • Vanilla JavaScript (ES6+)
  • No build process required
  • Module pattern for encapsulation
  • Performance-focused implementation

License

This project is built for personal and educational use.

Credits

Developed as a tool for track coaches and athletes to improve race pacing and performance.

Support

For issues or questions, refer to the PLANNING.md document for detailed specifications and design decisions.

Version: 1.0.0 (Phase 1 - Web Application)
Last Updated: February 2026