Use case

React to a stream while it is live

Follow a streamer's hype score, transcript and chat second by second over a WebSocket, and hear about clips the instant they are found.

Everything Clipped reads off a stream is available as it is read: the signals it scores on, what the streamer says, and every chat message. Three feeds per streamer, so a program takes only what it uses.

A feed follows a streamer, not one broadcast. Open it once and leave it open: it says waiting while they are offline and picks up by itself when they go live.

1. 1Follow the streamer first

   Feeds exist for streamers on your lineup; one for anyone else is refused with 403 not_following. GET /api/v1/streams lists who you follow with each one's three feed addresses.

   curl https://app.clipped.so/api/v1/streams -H "Authorization: Bearer $KEY"

2. 2Open a feed

   Send the key as a bearer header. Each message is one JSON object with a type; the first after started is a backlog of the recent past, marked "backlog": true.

   On analysis, seconds carries hype, the 0–100 score clips are found on, and moment is a clip found or changed, with its thumbnail once that is made.

   import WebSocket from "ws"
   
   function open() {
     const feed = new WebSocket("wss://app.clipped.so/api/v1/streams/jynxzi/analysis?audio=false", {
       headers: { Authorization: `Bearer ${process.env.CLIPPED_KEY}` },
     })
     feed.on("message", (raw) => {
       const m = JSON.parse(raw)
       if (m.type === "seconds" && !m.backlog) for (const s of m.data) if (s.hype >= 85) console.log("hype!", s.t, s.hype)
       if (m.type === "moment") console.log("clip:", m.data.id, m.data.score, m.data.title, m.data.thumbnail)
     })
     feed.on("close", () => setTimeout(open, 5000)) // reconnect: you get a fresh backlog
   }
   open()

3. 3In a browser

   A browser can't set headers on a WebSocket, so ?key= works too. Only put a key in a page you trust with it: it acts as you.

   const chat = new WebSocket("wss://app.clipped.so/api/v1/streams/jynxzi/chat?key=clip_sk_…")
   chat.onmessage = (e) => {
     const m = JSON.parse(e.data)
     if (m.type === "chat") for (const msg of m.data) console.log(msg.name + ":", msg.text)
   }

Worth knowing

• A feed only reads along. It never starts a recording or keeps one running.
• Opening a feed counts as one call, however long it stays open. An account can have 60 open at once.
• A second can be sent again as late scores land: keep the last one for each t.
• A client that stops reading is disconnected rather than buffered for.