Chat and streams

Plugins see chat and stream numbers from the streams ForgeCast is watching: your channel's live stream, or the streams you follow by link in Developer mode (up to eight at once, all merged). Everything here needs chat.read, chat.middleware or stream.read in plugin.json.

Plugins only read. There is no function to post in chat.

What a chat line looks likeCopy Anchor Link

Every function below hands you a Chat table:

-- what a handler is given (this is a picture of the table, not code to run)
local chat = {
  id = "Ugx…",                  -- unique id of the line
  text = "hello everyone",      -- the message as plain text (custom emoji appear as :shortcode:)
  kind = "text",                -- see the table below
  ts = 1767225600000,           -- when it was sent, in milliseconds since 1970
  stream = "dQw4w9WgXcQ",       -- the video id of the stream it came from
  author = {
    name = "@ann",              -- display name, usually the @handle
    id = "UC…",                 -- the viewer's channel id: use this to tell people apart
    is_owner = false,           -- the streamer
    is_mod = false,             -- a moderator
    is_member = true,           -- a channel member
  },
  amount = { value = 5, currency = "USD" },   -- Super Chats and Super Stickers only
  amount_text = "$5.00",        -- the amount as YouTube shows it
  count = 5,                    -- memberships in a gift
  headline = "Member for 6 months",
  backlog = false,              -- true for history read when a stream is first opened
  simulated = false,            -- true for chat from the Test environment
}

Fields that don't apply are nil, so check before you use them: chat.amount_text or "a Super Chat". Every field is in the reference.

React to chat as it arrivesCopy Anchor Link

chats.on(event, handler) calls handler(chat) for each new line. The event names live in the global Event:

A kind event fires in addition to Event.NewChat, not instead of it. You can pass the event as text too: chats.on("chat.super_chat", fn).

-- greet new members, thank Super Chats
chats.on(Event.Member, function(chat)
  ui.notify({ title = "New member", message = chat.author.name, level = "success" })
end)

chats.on(Event.SuperChat, function(chat)
  ui.notify({ title = chat.author.name .. " sent " .. (chat.amount_text or "a Super Chat"), message = chat.text })
end)

A few things worth knowing:

• History is skipped. When a stream is first opened, ForgeCast reads its recent chat so the Dashboard isn't empty. Handlers don't get those lines, unless you ask: chats.on(Event.NewChat, fn, { backlog = true }). They arrive with chat.backlog == true.
• chats.on returns an id. chats.off(id) stops that handler.
• A handler that errors doesn't stop anything: the error and a traceback go to the plugin's console, and the other handlers and the plugin carry on.
• Handlers must be quick: a handler has 250 ms; one that runs longer is stopped and the console says so. Do slow things with timer.after or an asynchronous http call.

Read recent chatCopy Anchor Link

Plugins can look at recent chat any time, whether or not anything just happened. chats.get(query) returns the newest lines, oldest first, up to limit (default 50, at most 300). The same query works for chats.count, chats.authors and chats.random.

local last_ten = chats.get({ limit = 10 })
local supers = chats.count({ kind = "super_chat", since = 3600 })   -- in the last hour
local who = chats.authors({ since = 600 })   -- people who wrote in the last 10 minutes, most active first
-- who[1] is { id, name, avatar, count, last_ts, is_member, is_mod, is_owner }

chats.random picks a line, one per person by default so someone who types a lot doesn't win more often (set unique_author = false to turn that off). It returns nil when nothing matches, and with count = 3 it returns a list of up to three:

local winner = chats.random({ since = 600, kind = "text", exclude = { "@botname" } })
if winner then
  ui.alert(winner.author.name .. " wins!")   -- needs ui.modal
end

Filter chat before anyone sees itCopy Anchor Link

Middleware sees every new line first. What it decides is what the Dashboard, the pop-out, your alerts, your chat actions and other plugins get. It needs chat.middleware.

chats.use(function(chat)
  if chat.text:lower():find("spam", 1, true) then
    return false, "contains spam"     -- hide it; the reason shows in this plugin's console
  end
end)

What a middleware function can return:

• Middleware functions run one after another, in the order they were added. Each one sees the text as the ones before it changed it, and once one hides a line, the later ones never see it.
• Keep it fast and safe. A middleware function has 400 ms a line. One that takes longer is cut off and the line goes through. One that errors lets the line through and writes the error to the console. A plugin can never make chat stop.
• Middleware only reads the line. Look people up with chat.author.id, not the display name, which people can change.
• Do the counting in middleware and the drawing somewhere else (a timer): the Chat filter example shows how.
• Lines from the Test environment go through middleware exactly like real ones, with chat.simulated == true.

StreamsCopy Anchor Link

stream.list() returns the streams being watched, one table each:

-- one entry of stream.list() (a picture of the table, not code to run)
local s = {
  id = "dQw4w9WgXcQ",     -- video id ("simulator" for the Test environment's)
  title = "Friday night", -- the stream's title
  phase = "live",         -- "connecting", "live", "upcoming", "ended" or "error"
  viewers = 120,          -- watching now (nil when YouTube doesn't say)
  peak_viewers = 150,
  likes = 40,
  total_views = 900,
  started_at = 1767225600000,  -- in milliseconds since 1970
  chat = "on",            -- "off", "connecting", "on", "limited" or "unavailable"
  simulated = false,      -- true for the Test environment's make-believe stream
}

stream.state() adds them up: { streams, live, title, viewers, likes, total_views, started_at }. With one stream that is the stream; with several, viewers and likes are sums and title is "3 streams".

stream.on(event, handler) listens for changes. The handler gets the stream's table:

-- cheer at 100 viewers, once per stream
local cheered = {}
stream.on(Event.StreamUpdate, function(s)
  if s.simulated or cheered[s.id] or (s.viewers or 0) < 100 then return end
  cheered[s.id] = true
  ui.notify({ title = "100 people are watching", message = s.title or s.id, level = "success" })
end)