feat: add HLS streaming support with --hls option

- Add HLSSegmenter class for WebVTT segmentation with 60-second default segments
- Implement M3U8 playlist generation with HLS Version 6 for subtitle support
- Add --hls CLI option accepting directory path for multi-file output
- Include comprehensive unit tests achieving 100% coverage
- Add HLS.js browser integration tests for compatibility validation
- Support multi-segment streams with proper duration and timing
- Generate X-TIMESTAMP-MAP headers for HLS compatibility
- Create ADR-002 documenting decision to implement custom segmentation

Resolves limitations with Apple's mediasubtitlesegmenter tool which cannot
handle JSON metadata lines exceeding character limits.

Author: limulus

/fileSequence0.webvtt

@@ -0,0 +1,164 @@
+WEBVTT
+X-TIMESTAMP-MAP=MPEGTS:900000,LOCAL:00:00:00.000
+
+00:00:00.000 --> 00:00:01.000
+[{"metric":"distance","value":2.7}]
+
+00:00:01.000 --> 00:00:02.000
+[{"metric":"heartRate","value":88}]
+
+00:00:02.000 --> 00:00:03.000
+[{"metric":"distance","value":11.8}]
+
+00:00:03.000 --> 00:00:04.000
+[{"metric":"cadence","value":25}]
+
+00:00:04.000 --> 00:00:05.000
+[{"metric":"heartRate","value":90}]
+
+00:00:05.000 --> 00:00:06.000
+[{"metric":"power","value":121}]
+
+00:00:06.000 --> 00:00:07.000
+[{"metric":"distance","value":20.7}]
+
+00:00:07.000 --> 00:00:08.000
+[{"metric":"cadence","value":24}]
+
+00:00:08.000 --> 00:00:09.000
+[{"metric":"heartRate","value":93}]
+
+00:00:09.000 --> 00:00:10.000
+[{"metric":"power","value":126}]
+
+00:00:10.000 --> 00:00:11.000
+[{"metric":"distance","value":27.8}]
+
+00:00:11.000 --> 00:00:12.000
+[{"metric":"cadence","value":24}]
+
+00:00:12.000 --> 00:00:13.000
+[{"metric":"heartRate","value":97}]
+
+00:00:13.000 --> 00:00:14.000
+[{"metric":"power","value":126}]
+
+00:00:14.000 --> 00:00:15.000
+[{"metric":"distance","value":38.5}]
+
+00:00:15.000 --> 00:00:16.000
+[{"metric":"cadence","value":24}]
+
+00:00:16.000 --> 00:00:17.000
+[{"metric":"heartRate","value":103}]
+
+00:00:17.000 --> 00:00:18.000
+[{"metric":"power","value":117}]
+
+00:00:18.000 --> 00:00:19.000
+[{"metric":"distance","value":45.3}]
+
+00:00:19.000 --> 00:00:20.000
+[{"metric":"cadence","value":24}]
+
+00:00:20.000 --> 00:00:21.000
+[{"metric":"heartRate","value":108}]
+
+00:00:21.000 --> 00:00:22.000
+[{"metric":"power","value":117}]
+
+00:00:22.000 --> 00:00:23.000
+[{"metric":"distance","value":56.1}]
+
+00:00:23.000 --> 00:00:24.000
+[{"metric":"cadence","value":23}]
+
+00:00:24.000 --> 00:00:25.000
+[{"metric":"heartRate","value":110}]
+
+00:00:25.000 --> 00:00:26.000
+[{"metric":"power","value":124}]
+
+00:00:26.000 --> 00:00:27.000
+[{"metric":"distance","value":64.9}]
+
+00:00:27.000 --> 00:00:28.000
+[{"metric":"cadence","value":24}]
+
+00:00:28.000 --> 00:00:29.000
+[{"metric":"heartRate","value":110}]
+
+00:00:29.000 --> 00:00:30.000
+[{"metric":"power","value":119}]
+
+00:00:30.000 --> 00:00:31.000
+[{"metric":"distance","value":73.6}]
+
+00:00:31.000 --> 00:00:32.000
+[{"metric":"cadence","value":24}]
+
+00:00:32.000 --> 00:00:33.000
+[{"metric":"heartRate","value":110}]
+
+00:00:33.000 --> 00:00:34.000
+[{"metric":"power","value":115}]
+
+00:00:34.000 --> 00:00:35.000
+[{"metric":"distance","value":82.3}]
+
+00:00:35.000 --> 00:00:36.000
+[{"metric":"cadence","value":24}]
+
+00:00:36.000 --> 00:00:37.000
+[{"metric":"heartRate","value":110}]
+
+00:00:37.000 --> 00:00:38.000
+[{"metric":"power","value":113}]
+
+00:00:38.000 --> 00:00:39.000
+[{"metric":"distance","value":91}]
+
+00:00:39.000 --> 00:00:40.000
+[{"metric":"cadence","value":24}]
+
+00:00:40.000 --> 00:00:41.000
+[{"metric":"heartRate","value":109}]
+
+00:00:41.000 --> 00:00:42.000
+[{"metric":"power","value":118}]
+
+00:00:42.000 --> 00:00:43.000
+[{"metric":"distance","value":99.9}]
+
+00:00:43.000 --> 00:00:44.000
+[{"metric":"cadence","value":24}]
+
+00:00:44.000 --> 00:00:45.000
+[{"metric":"heartRate","value":110}]
+
+00:00:45.000 --> 00:00:46.000
+[{"metric":"power","value":119}]
+
+00:00:46.000 --> 00:00:47.000
+[{"metric":"distance","value":108.3}]
+
+00:00:47.000 --> 00:00:48.000
+[{"metric":"cadence","value":23}]
+
+00:00:48.000 --> 00:00:49.000
+[{"metric":"heartRate","value":114}]
+
+00:00:49.000 --> 00:00:50.000
+[{"metric":"power","value":108}]
+
+00:00:50.000 --> 00:00:51.000
+[{"metric":"distance","value":116.6}]
+
+00:00:51.000 --> 00:00:52.000
+[{"metric":"cadence","value":24}]
+
+00:00:52.000 --> 00:00:53.000
+[{"metric":"heartRate","value":116}]
+
+00:00:53.000 --> 00:00:54.000
+[{"metric":"power","value":99}]

/index.m3u8

@@ -0,0 +1,8 @@
+#EXTM3U
+#EXT-X-VERSION:6
+#EXT-X-TARGETDURATION:54
+#EXT-X-MEDIA-SEQUENCE:0
+#EXT-X-PLAYLIST-TYPE:VOD
+#EXTINF:54.00000,	
+fileSequence0.webvtt
+#EXT-X-ENDLIST

docs/decisions/ADR-002-add-hls-output-support.md

@@ -0,0 +1,88 @@
+---
+status: accepted
+date: 2025-06-20
+decision-makers: @limulus
+---
+
+# Add HLS Output Support with --hls Option
+
+## Context and Problem Statement
+
+Users need to output WebVTT files in HLS-compatible segmented format for HTTP Live Streaming, but tcx2webvtt currently only outputs single files to stdout. This prevents using the tool's output directly for HLS streaming scenarios where multiple segment files and a playlist are required.
+
+## Decision Drivers
+
+- Need for HLS streaming compatibility with Safari and HLS.js
+- Current stdout-only output is insufficient for multi-file HLS format requirements
+- Apple's `mediasubtitlesegmenter` tool (from HTTP Live Streaming Tools) fails with tcx2webvtt output due to inability to handle lines longer than ~200 characters (JSON metadata lines exceed this limit)
+- Requirement for directory-based output to accommodate multiple HLS segment files
+- Need for proper testing infrastructure for this functionality
+
+## Considered Options
+
+- Use `mediasubtitlesegmenter` as post-processing step
+- Create separate HLS conversion tool in media-tools repo
+- Implement custom HLS segmentation logic within tcx2webvtt
+
+## Decision Outcome
+
+Chosen option: "Implement custom HLS segmentation logic within tcx2webvtt", because it provides an integrated solution with proper testing infrastructure, avoids the line length limitations of `mediasubtitlesegmenter`, and feels like a natural extension of the tool's functionality.
+
+### Consequences
+
+- Good, because users get a complete HLS solution without needing external post-processing
+- Good, because we can implement proper test coverage for the HLS functionality
+- Good, because we avoid the line length limitations that prevent using Apple's segmentation tool
+- Good, because the feature feels like a natural fit for tcx2webvtt's purpose
+- Neutral, because this adds complexity to the tool but keeps it focused on WebVTT generation
+- Bad, because we need to implement and maintain custom segmentation logic instead of using existing tools
+
+### Confirmation
+
+Implementation compliance will be confirmed through:
+- Integration testing with HLS.js for browser compatibility verification
+- Testing with Safari and other HLS-compatible browsers
+- Unit tests covering segmentation logic and edge cases
+- Validation that generated HLS streams work correctly with seeking and playback
+
+## Pros and Cons of the Options
+
+### Use `mediasubtitlesegmenter` as post-processing step
+
+Apple's HTTP Live Streaming Tools include `mediasubtitlesegmenter` which is designed specifically for this purpose.
+
+- Good, because it uses Apple's official HLS tooling
+- Good, because it would require minimal changes to tcx2webvtt
+- Bad, because it fails with tcx2webvtt output due to JSON metadata lines exceeding ~200 character limit
+- Bad, because it requires users to have additional tools and processing steps
+
+### Create separate HLS conversion tool in media-tools repo
+
+A standalone tool could handle the conversion from tcx2webvtt output to HLS format.
+
+- Good, because it separates concerns and keeps tcx2webvtt focused
+- Good, because media-tools repo already has HLS-related scripts
+- Neutral, because it would work for this specific use case
+- Bad, because media-tools repo lacks testing infrastructure for this type of functionality
+- Bad, because it creates an additional tool dependency for users
+- Bad, because it would likely be used only for this specific case, unlike other Apple HLS tools
+
+### Implement custom HLS segmentation logic within tcx2webvtt
+
+Add `--hls <directory>` option to tcx2webvtt with custom segmentation.
+
+- Good, because it provides an integrated solution for users
+- Good, because we can implement proper test coverage
+- Good, because we can handle the JSON metadata line length requirements
+- Good, because the feature feels like a natural extension of WebVTT generation
+- Neutral, because it adds complexity but keeps the tool focused on its core purpose
+- Bad, because we need to implement and maintain custom segmentation logic
+
+## More Information
+
+The HLS implementation will need to:
+- Generate 60-second WebVTT segments with proper HLS headers
+- Create an `index.m3u8` playlist file
+- Handle empty segments appropriately
+- Work with Safari and HLS.js for broad compatibility
+- Support the existing JSON metadata format without line length restrictions

package-lock.json

@@ -69,6 +69,7 @@
     "concurrently": "^9.1.2",
     "del-cli": "^6.0.0",
     "eslint": "^9.28.0",
+    "hls.js": "^1.6.5",
     "husky": "^9.1.7",
     "is-ci": "^4.1.0",
     "mkdirp": "^3.0.1",