--- a/mrjunejune/README.md	Mon Aug 03 11:26:30 2026 -0700
+++ b/mrjunejune/README.md	Mon Aug 03 13:14:41 2026 -0700
@@ -17,6 +17,28 @@
 corresponding list in `mrjunejune/BUILD` or `assets/BUILD`, then reference the
 generated `.webp` URL from the site.
 
+## HLS player
+
+`/tools/hls_player` is a dependency-free JavaScript HLS player. It uses native
+HLS where available and a MediaSource fallback for unencrypted VOD playlists
+with fragmented MP4 segments. A VP9/Opus HLS sample is bundled at:
+
+```text
+/public/hls-sample/master.m3u8
+```
+
+The sample is generated from `mrjunejune/assets/video/sample_hls.mp4` through
+the restored FFmpeg CLI wrapper:
+
+```bash
+bazel run //mrjunejune:generate_hls_sample
+```
+
+```bash
+bazel test //mrjunejune/test:hls_player_test
+bazel test //mrjunejune/test:theme_and_webp_test
+```
+
 ## TODO 
 
 - Add caching layer