docs: add WebVTT timing research documentation

Add comprehensive research on WebVTT timing specifications, browser
implementation constraints, and performance considerations that inform
design decisions for TCX workout data conversion. Documents the rationale
for 1-second cue intervals and cross-browser compatibility requirements.

Author: limulus

docs/webvtt-timing-research.md

@@ -0,0 +1,85 @@
+# WebVTT timing specifications for rapid cue changes
+
+**The official W3C WebVTT specification does not impose minimum cue duration limits**,
+making it technically suitable for your TCX workout file conversion tool with JSON metadata.
+However, **browser implementations and parser performance create practical constraints**
+that require careful consideration for reliable cross-platform operation.
+
+## Official specification requirements
+
+The W3C WebVTT specification is remarkably permissive regarding timing constraints. **No
+minimum cue duration is specified** - the only requirement is that end time must be greater
+than start time. The specification explicitly allows **overlapping cues and zero gaps
+between consecutive cues**, except for chapter tracks.
+
+Timestamps support **millisecond precision** using the format `HH:MM:SS.mmm` where
+milliseconds range from 000-999. Cues must be ordered by start time in the file, but their
+durations can overlap. This technical flexibility means your TCX conversion tool can
+theoretically create cues with durations as short as 1 millisecond.
+
+## Browser implementation realities reveal critical limitations
+
+While the specification is permissive, **browser implementations vary significantly** in
+handling rapid cue changes. Chrome and Firefox provide the most robust implementations, but
+both experience performance degradation with very high-frequency cue changes. **Safari
+presents the most significant challenges**, with documented issues where multiple
+simultaneous positioned cues cause display problems and synchronization drift.
+
+Research reveals that cues changing faster than every **100-200 milliseconds frequently
+cause problems**. Browsers may skip cues entirely, experience memory leaks, or lose
+synchronization between video and metadata tracks. The root cause stems from browser
+rendering pipelines not being optimized for subtitle-reading speeds faster than human
+comprehension.
+
+## Parser performance creates practical constraints
+
+WebVTT parsing libraries show **consistent performance degradation with rapid cue
+transitions**. JavaScript implementations experience floating-point precision issues when
+storing timing values as doubles, leading to timing drift in applications requiring precise
+synchronization. A documented case of a "WebVTT metronome" revealed that only Firefox's
+native video viewer handled millisecond-precision timing consistently across extended
+periods.
+
+Parser-specific constraints include strict mode validation where zero-duration cues are
+rejected, and memory overhead that scales linearly with cue frequency. **Native
+implementations in C/C++ show better performance** than JavaScript parsers for
+high-frequency scenarios, but browser-based applications are limited to JavaScript engines.
+
+## Recommendations for TCX workout data conversion
+
+For your TCX to WebVTT conversion tool, implement **1-second interval cues** as the optimal
+balance between precision and performance. This frequency provides adequate granularity for
+workout data while avoiding browser performance issues. Structure your JSON metadata using
+the `kind="metadata"` track type to prevent visual display while maintaining synchronization
+capabilities.
+
+**Technical implementation guidance:**
+
+- Use hidden metadata tracks (`track.mode = 'hidden'`) to load data without display
+- Structure cues with millisecond precision timestamps for accuracy
+- Include essential workout metrics in JSON objects within cue payloads
+- Implement JavaScript event throttling when processing `cuechange` events
+- Test extensively across browsers, particularly Safari's simultaneous cue handling
+
+## Performance boundaries and practical limits
+
+While the specification supports sub-second timing, **practical limits emerge around 100ms
+minimum cue duration** for reliable cross-browser compatibility. Cues shorter than this
+threshold risk being skipped by browser rendering engines operating at typical video frame
+rates (30-60 fps).
+
+For non-visual metadata applications like workout data synchronization, the **sweet spot
+appears to be 1Hz updates** (1-second intervals), providing responsive data updates without
+overwhelming browser processing capabilities. This frequency aligns well with typical
+workout data sampling rates and ensures consistent performance across all major browsers and
+WebVTT parser implementations.
+
+## Conclusion
+
+WebVTT's specification flexibility makes it technically viable for rapid cue changes in your
+TCX conversion tool, but browser implementation realities require a more conservative
+approach. **The format supports your use case effectively at 1-second intervals**, providing
+reliable cross-platform performance while maintaining sufficient granularity for workout
+data visualization and analysis. Focus your implementation on metadata tracks with JSON
+payloads, and you'll have a robust solution that leverages WebVTT's synchronization
+capabilities without encountering the performance pitfalls of ultra-rapid cue changes.