From 63acf4964afb4371646d75e222863b4af5514224 Mon Sep 17 00:00:00 2001
From: ari melody <ari@arimelody.space>
Date: Fri, 24 Jul 2026 17:44:17 +0100
Subject: [PATCH] add readme

---
 README.md | 44 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 44 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..f90f62c
--- /dev/null
+++ b/README.md
@@ -0,0 +1,44 @@
+# ari's stream tools
+
+handy, custom-built tools and utilities for my livestreams!
+
+## learning
+
+endpoints and views for "ari is learning!" streams.
+
+- **`GET /learning/sse`**: server-sent events:
+    - `title-update`: emits when the stream title is updated
+- **`POST /learning/title`**: update the current stream title
+- **`GET /learning/hello`**: intro view
+- **`GET /learning/brb`**: "be right back!" view
+- **`GET /learning/bye`**: stream ending view
+
+## music
+
+endpoints for a music status indicator.
+
+- **`GET /music/sse`**: server-sent events:
+    - `music`: emits when the currently playing track changes
+        - example: `{"title":"Untitled Track","artist":"Unknown Artist"}`
+    - `music-state`: emits when the playing state changes
+        - example: `{"playing":true}`
+- **`GET /music/artwork`**: serves the currently playing track artwork
+- **`GET /music`**: music status indicator
+
+## twitch
+
+endpoints for twitch events and labels.
+
+- **`GET /login`**: redirects to twitch login
+- **`GET /auth`**: twitch auth callback
+- **`GET /sse/*`**: server-sent events:
+    - **labels**: emits once at start, and every time an update occurs.
+        - `update` events contain a plain text username.
+        - `/sse/labels/latest-follower`
+        - `/sse/labels/latest-subscriber`
+        - `/sse/labels/latest-cheer`
+- **`GET /labels/<label>`**: serves a twitch label view.
+    - supported `label`s:
+        - `latest-follower`
+        - `latest-subscriber`
+        - `latest-cheer`