[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M734FNTE1T55VXFF71KBTZP3":3,"skill-same:01M734FNTE1T55VXFF71KBTZP3":48},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":24,"commitSha":25,"skillDirectory":26,"forksCount":27,"repositoryHtmlUrl":28,"repositoryHomepageUrl":29,"ownerHtmlUrl":30,"ownerBlogUrl":31,"ownerDescription":32,"updatedAt":33,"install":34,"resources":47},"01M734FNTE1T55VXFF71KBTZP3","create-owncast-plugin-py",null,"Build a complete Owncast plugin in Python from a plain-language description and hand back an installable .ocpkg file. Use when someone wants to create, build, scaffold, or make an Owncast plugin in Python (a chat bot, chat filter\u002Fmoderation tool, stream-event responder, HTTP page\u002Foverlay\u002Fwidget, admin page, fediverse integration, etc.) without needing to know the SDK internals. If the author hasn't picked a language yet, start from create-owncast-plugin (the router) instead.","owncast\u002Fplugin-sdk","owncast","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F69942503?v=4","01M734F1G4F48EQH3Z6BN0N8TA","Owncast","01M734F1HGY63D9FQQRQKHEW8J",1,"MIT","https:\u002F\u002Fgithub.com\u002Fowncast\u002Fplugin-sdk\u002Fblob\u002Fmain\u002Fsdks\u002Fpython\u002Fowncast_plugin\u002Ftemplate\u002F.agents\u002Fskills\u002Fcreate-owncast-plugin-py\u002FSKILL.md",[],[],"2026-11-11 15:11:14",false,"---\nname: create-owncast-plugin-py\ndescription: \"Build a complete Owncast plugin in Python from a plain-language description and hand back an installable .ocpkg file. Use when someone wants to create, build, scaffold, or make an Owncast plugin in Python (a chat bot, chat filter\u002Fmoderation tool, stream-event responder, HTTP page\u002Foverlay\u002Fwidget, admin page, fediverse integration, etc.) without needing to know the SDK internals. If the author hasn't picked a language yet, start from create-owncast-plugin (the router) instead.\"\n---\n\n# Create an Owncast plugin (Python)\n\nThis skill walks any AI assistant through building a working Owncast plugin in\n**Python** for a non-expert user: gather what they want in plain language,\nscaffold the project, write the code and manifest, verify it with tests, and\nproduce the single `.ocpkg` file they upload to their Owncast server. The user\nshould never have to understand the runtime. You do that part.\n\n> **Picking a language?** Owncast plugins can be written in JavaScript or Python.\n> The two SDKs are first-class peers: the same handlers, APIs, permissions, and\n> manifest apply to both, and only the scaffolding and language syntax differ.\n> This skill is the **Python** path. For JavaScript, use `create-owncast-plugin-js`.\n> If the language isn't decided yet, start from the `create-owncast-plugin`\n> router, which gathers the author's intent and dispatches to the right one.\n\nThis file is the complete operating guide. It is written to be tool-agnostic:\nwherever it says \"ask the user,\" use whatever question mechanism your harness\noffers (a structured prompt UI, or just a plain chat question). Wherever it says\n\"run,\" use your shell\u002Fcommand tool.\n\n## What an Owncast plugin is (one paragraph)\n\nA plugin is Python that runs sandboxed inside the Owncast server. It subscribes\nto events (chat messages, stream start\u002Fstop, fediverse activity) by registering\nhandler functions with `@plugin.*` decorators, and calls back into Owncast\nthrough the `owncast.*` API (send chat, store data, fetch URLs, serve web pages,\netc.). A `plugin.manifest.json` declares the plugin's identity and the\n**permissions** it needs. Every API call requires its matching permission, or\nthe host refuses to load the plugin. The build step just emits the Python source\nas `\u003Cslug>.py` and bundles it with the manifest and assets into one `.ocpkg` file\nfor distribution.\n\n> Plugins ship as source, not a compiled binary. The Owncast host embeds one\n> Python engine and runs every Python plugin on it, so a package carries no\n> interpreter and an author never touches a wasm toolchain.\n\n## The workflow (follow in order)\n\n### Step 1: Understand what they want\n\nAsk the user, in plain language:\n\n1. **What should the plugin be called?** (e.g. \"Welcome Bot\"). Derive a **slug**\n   from it: lowercase, digits and hyphens only, must start with a letter, max 64\n   chars (e.g. `welcome-bot`). If their name can't map to a valid slug, propose\n   one and confirm.\n2. **What should it do?** Get concrete behavior, not a category. \"Greet people\n   when they join,\" \"delete messages containing a word,\" \"show a live chat\n   overlay on a web page,\" \"post to Discord when the stream goes live.\"\n\nThen map their description to capabilities using the **Capability map** below.\nThat tells you which handler(s) to write, which `owncast.*` calls to make, and\nwhich permissions the manifest must declare. If a request needs a high-trust\npermission (`fediverse.post`, `videoconfig.write`, `users.moderate`,\n`network.fetch` to arbitrary hosts, or `auth.gate`, which lets the host require\nthe plugin's login for operator-selected viewer resources), note it back to the\nuser. The server admin will have to approve it.\n\nKeep it small. Build the simplest plugin that does what they asked. You can\nalways add handlers later.\n\n### Step 2: Make sure you have a plugin project\n\n**If your working directory already contains a `plugin.manifest.json`**, you are\nalready inside a scaffolded plugin (this skill may have shipped inside it). Do\n**not** scaffold again. Skip to Step 3 and edit the project in place, using its\nexisting slug.\n\n**Otherwise, scaffold a new project** with the official scaffolder\n(non-interactive, takes the slug as an argument):\n\n```sh\nowncast-plugin-py new \u003Cslug>\n# or, without installing the SDK first:\nuvx owncast-plugin-py new \u003Cslug>\n```\n\nThis creates a `\u003Cslug>\u002F` directory with `plugin.manifest.json`,\n`src\u002Fplugin.py`, and `__tests__\u002Fplugin.test.json` already wired up. All\nsubsequent commands run **from inside that directory**.\n\n### Step 3: Write the plugin\n\nEdit two files based on what you learned in Step 1:\n\n- **`src\u002Fplugin.py`**: register only the handlers the behavior needs. See\n  **Writing handlers** and the **Capability map**.\n- **`plugin.manifest.json`**: set `name`, `description`, and the exact\n  `permissions` required by the handlers you register and APIs you call. See **The manifest**.\n\nIf the plugin serves web content, add files under `public\u002F` (web-served) or\n`assets\u002F` (host-read for inlined UI). Replace the scaffolded test in\n`__tests__\u002Fplugin.test.json` with scenarios that assert your actual behavior\n(see **Testing**).\n\n**Clear the scaffolded placeholders.** They ship verbatim, so don't leave the\ndefaults:\n\n- Set a real `description` in `plugin.manifest.json` (the scaffold leaves `\"An\n  Owncast plugin\"`).\n- **Fill in `INSTRUCTIONS.md`.** It's bundled into the `.ocpkg` and rendered as\n  an **Instructions** tab on the plugin's page in the Owncast admin. Its only\n  audience is the **person installing and running the plugin** (the Owncast\n  admin \u002F streamer), not you the developer. Write it for them, in plain\n  language: **what the plugin does and how to use it once enabled**, including any\n  settings to configure and what each does, the features it adds and how to use\n  them (e.g. chat commands like `!hello`, what happens automatically), and where\n  any page, button, or tab it adds shows up. You built the plugin, so describe\n  its real behavior concretely and accurately. Always write this to the best of\n  your ability. Don't ship the \"Write anything an Owncast admin should know…\"\n  placeholder and don't leave it empty.\n\n### Step 4: Test\n\n```sh\nowncast-plugin-py test\n```\n\nThe first run downloads and caches the host test\u002Fserve binaries (there's no wasm\ntoolchain: plugins run on the engine the host embeds). `test` emits\n`src\u002Fplugin.py` as `\u003Cslug>.py` and runs `__tests__\u002F*.test.json` against the real\nplugin runtime with mocked side effects, so a pass means the same behavior in\nproduction.\n\n**When the build or tests fail, first classify the failure. They need opposite\nresponses:**\n\n- **A behavior\u002Fassertion failure** (the test ran and the output didn't match, a\n  Python error in your handler, a missing permission for an API you call). This\n  is yours to fix: read the diff, correct `src\u002Fplugin.py`, the manifest, or the\n  expectation, and re-run. Don't package with these unresolved.\n- **A toolchain\u002Fversion-skew failure**, with host\u002Fruntime mismatch errors that fire\n  **before your test logic runs** (e.g. an import or host-function name the\n  runtime doesn't recognize). This is **not** a bug in your plugin, so don't edit\n  handlers to chase it. It means the installed SDK runtime and its bundled\n  test-host binary are out of sync. Respond by: (1) ensuring the latest version with\n  `uv tool upgrade owncast-plugin-py` (or `pip install -U owncast-plugin-py`) and re-run. (2) If\n  it persists, note that the compiled `.ocpkg` is still valid for a current\n  Owncast server (the skew is only in the local test harness), proceed to **Step\n  5**, and tell the user tests couldn't run locally due to a toolchain version\n  mismatch. Do not loop on it.\n\n(If the toolchain can't be fetched because there's no network, tell the user\nthat's required once, and continue to write correct code so they can run\n`owncast-plugin-py test && owncast-plugin-py package` themselves.)\n\n### Step 5: Package and hand off\n\n```sh\nowncast-plugin-py package\n```\n\n`package` first load-checks the plugin — the same install-time path a real\nOwncast server runs. A handler whose gating permission isn't declared in the\nmanifest (a chat filter without `chat.filter`, a fediverse handler without\n`fediverse.inbound`) aborts packaging with the exact error the server would\ngive at install. Fix the manifest, don't work around the check.\n\nThis produces **`\u003Cslug>.ocpkg`** in the project directory, a single\nself-contained file bundling the manifest, the `plugin.py` source, and any\n`public\u002F`\u002F`assets\u002F`\u002F`icon.png`\u002F`INSTRUCTIONS.md`. Give the user the path to that\nfile and tell them how to install it:\n\n> Open **Plugins** in your Owncast admin → **Upload plugin** → select\n> `\u003Cslug>.ocpkg`. Then review the **Permissions** tab and toggle **Enabled**.\n> (Alternatively, drop the file into `data\u002Fplugins\u002F` on the server.)\n\nBriefly summarize what the plugin does and which permissions the admin will be\nasked to approve, and why each is needed.\n\n---\n\n## Capability map (intent → handler + API + permission)\n\nMatch the user's described behavior to these rows. Register the listed\nhandler(s), call the listed API, and add the listed permission to the manifest.\nSeveral rows combine for richer plugins.\n\n| They want to…                                   | Handler(s)                                          | API call                                       | Permission(s)                          |\n| ----------------------------------------------- | --------------------------------------------------- | ---------------------------------------------- | -------------------------------------- |\n| React to chat messages                          | `@plugin.on_chat_message`                           | —                                              | — (add `chat.send` to reply)           |\n| Reply \u002F post in chat                            | (any handler)                                       | `owncast.chat.send(text)` \u002F `.send_action`     | `chat.send`                            |\n| Whisper privately to a sender                   | `on_chat_message` \u002F `filter_chat_message`           | `owncast.chat.reply_to(msg, text)`             | `chat.send`                            |\n| Run chat commands (`!uptime`, etc.)             | `plugin.commands({...})`                             | `ctx.reply` \u002F `ctx.reply_privately`            | `chat.send` to reply                  |\n| Inspect\u002Fmodify\u002Fdrop every message (moderation)  | `@plugin.filter_chat_message`                       | `filter.pass_\u002Fmodify\u002Fdrop`                     | `chat.filter` (required for the handler) |\n| Delete a message \u002F kick a client                | (any)                                               | `owncast.chat.delete_message` \u002F `.kick`        | `chat.moderate`                        |\n| Read recent chat \u002F list clients                 | (any)                                               | `owncast.chat.history()` \u002F `.clients()`        | `chat.history`                         |\n| React when stream goes live \u002F stops             | `@plugin.on_stream_started` \u002F `_stopped`            | —                                              | —                                      |\n| Read live stream state (title, viewers, uptime) | (any)                                               | `owncast.stream.current()`                     | `server.read`                          |\n| Read server info \u002F socials \u002F emotes \u002F tags      | (any)                                               | `owncast.server.*()`                           | `server.read`                          |\n| Store per-user or persistent state              | (any)                                               | `owncast.kv.get\u002Fset` (+ `get_json\u002Fset_json`)   | `storage.kv`                           |\n| Rank or aggregate data (private SQL database)   | (any)                                               | `owncast.sql.exec\u002Fquery\u002Fquery_row`             | `storage.sql`                          |\n| Expose admin-configurable settings              | (read at runtime)                                   | `owncast.config.get(key, fallback=None)`       | — (declare under `config` in manifest) |\n| Call an external API \u002F webhook                  | (any)                                               | `owncast.http.fetch(url, opts=None)`           | `network.fetch` + `network.allowedHosts` |\n| Do delayed \u002F periodic work                      | `@plugin.on_tick` or `owncast.timer.*`              | `owncast.timer.set_timeout\u002Fset_interval`       | — (ambient)                            |\n| Serve a web page \u002F overlay \u002F JSON endpoint      | `@plugin.get\u002Fpost\u002F...` \u002F `on_http_request` + `public\u002F` | return `{status, headers, body}`            | `http.serve`                           |\n| Push realtime updates to a browser              | (any)                                               | `owncast.sse.send(channel, event, data)`       | `http.sse`                             |\n| Add an admin settings page in the Owncast UI    | `@plugin.on_http_request` + `public\u002Fadmin\u002F...`      | —                                              | `http.serve` + `admin.pages` manifest  |\n| Add a button under the viewer's stream          | (manifest only, or `owncast.actions.add`)           | —                                              | `ui.modify` (+ `http.serve` if it opens your page) |\n| Inject CSS \u002F JS \u002F HTML into the viewer page     | (manifest `styles`\u002F`scripts`\u002F`extraPageContent`)    | dynamic `@plugin.on_page_styles` \u002F `on_page_scripts` \u002F `on_page_content` | `ui.modify`                            |\n| Add a tab to the viewer page                    | optional `@plugin.on_tab_content`                   | —                                              | `ui.modify` (+ data perms used)        |\n| Upload a file and get a public URL              | (any)                                               | `owncast.storage.upload(name, bytes)`          | `storage.upload`                       |\n| Private server-side files                       | (any)                                               | `owncast.fs.*`                                 | `storage.fs`                           |\n| Send Discord \u002F browser-push \u002F fediverse notice  | (any)                                               | `owncast.notifications.*`                      | `notifications.send`                   |\n| Post publicly to the fediverse (high-trust)     | (any)                                               | `owncast.fediverse.post(text)`                 | `fediverse.post`                       |\n| React to any verified inbound fediverse activity | `@plugin.on_fediverse` gets a non-subscriptable `_Obj` attribute view. Use `payload.raw` for the underlying dictionary and keys like `@context`. Specialized handlers: `@plugin.on_fediverse_follow\u002Flike\u002Frepost\u002Fquote\u002Fmention\u002Freply` | none | `fediverse.inbound` |\n| Read\u002Fchange video\u002Ftranscoding config            | (any)                                               | `owncast.video_config.read\u002Fwrite`              | `videoconfig.read` \u002F `videoconfig.write` |\n| Compose with other plugins via custom events    | own local hooks with `@plugin.on(...)`, emit to `\u003Crecipient-slug>.\u003Chook>` | `owncast.events.emit(type, payload)` | `events.emit` (emitter only) |\n| Gate the site behind a member login (paywall) | `@plugin.on_http_request` (login flow) + `@plugin.on_auth_check` (re-validation) | `owncast.users.register` + `owncast.auth.grant_session\u002Fend_session` | `auth.gate` + `users.register` (+ `http.serve`); model on `examples\u002Fpython\u002Fgithub-auth` |\n\n**Golden rule:** the `permissions` array must contain exactly the permissions\nrequired by the handlers you register and every `owncast.*` method you call.\nMissing one means the call throws and\u002For the host refuses to load the plugin.\nDon't add permissions you don't use, since admins judge trust by the declared list.\n\n---\n\n## Writing handlers\n\n```python\nfrom owncast_plugin import plugin, owncast, filter\n\n\n@plugin.on_chat_message\ndef greet(msg):\n    # msg has attributes: id, user, client_id, body, timestamp. msg.user is a\n    # User (msg.user.id, .display_name, .display_color, .scopes) in production, or None for\n    # a message with no associated account. Read the name defensively.\n    name = msg.user.display_name if msg.user else \"there\"\n    words = msg.body.split()\n    if words and words[0].lower() == \"hi\":\n        owncast.chat.send(f\"hello, {name}!\")\n```\n\nRegister **only** the handlers you need. The SDK derives event subscriptions\nfrom which handlers exist. Decorators: `@plugin.on_chat_message`,\n`@plugin.filter_chat_message`, `@plugin.on_chat_user_joined` \u002F `_parted` \u002F\n`_renamed`, `@plugin.on_message_moderated`, `@plugin.on_stream_started` \u002F\n`_stopped` \u002F `_title_changed`, `@plugin.on_fediverse`,\n`@plugin.on_fediverse_follow` \u002F `_like` \u002F `_repost` \u002F `_quote` \u002F `_mention` \u002F `_reply`, `@plugin.on_tick`, `@plugin.on_sse_connect` \u002F\n`_disconnect`, `@plugin.on_tab_content(\"slug\")`, `@plugin.on_page_content(\"slug\")`,\n`@plugin.on_page_styles`, `@plugin.on_page_scripts`,\nHTTP routes (`@plugin.get\u002Fpost\u002Fput\u002Fdelete\u002Fpatch(path)`, `@plugin.route`,\n`@plugin.on(\"event\")` for local custom hooks. The host registers each as\n`\u003Cyour-plugin-slug>.event`, which emitters use as the target.\n\nImportant shape\u002Fbehavior notes:\n\n- **`msg.user` is an attribute object or `None`.** Production sends a User\n  (`msg.user.id`, `msg.user.display_name`, `msg.user.display_color`, `msg.user.scopes`). A message with no\n  account is `None`. Read the name defensively: `msg.user.display_name if\n  msg.user else \"...\"`. For stable per-user state and moderator gating use\n  `msg.user.id` and `msg.user.scopes`, never the display name. Use\n  `msg.raw` for the underlying dict. Declarative command tables handle\n  moderator gating automatically.\n- **Chat text is HTML-escaped on display.** `chat.send`\u002F`send_action` take plain\n  text. The exception is `chat.system(body)`, whose body renders as HTML, so escape\n  untrusted content yourself.\n- **Filters fail open and are time-capped (50 ms).** `filter_chat_message` must\n  be fast. A filter that errors is treated as `filter.pass_()`. Five consecutive\n  failures auto-disable the plugin for the session.\n- **`filter.pass_()` has a trailing underscore** (`pass` is a Python keyword).\n- **No `time.sleep` \u002F threads for delays.** Use `owncast.timer.*`. Timers don't\n  survive a host restart.\n- **`owncast.sql.*` is one private SQLite database per plugin.** Each `exec` is\n  a single atomic transaction, so a multi-statement schema setup either lands\n  whole or not at all. An unbounded `query` that overruns the host's row or\n  result budget is an error, not a truncated result, so write a `LIMIT`, or use\n  `query_row` when you only need one row. Plugin databases are not included in\n  Owncast's backups. Worked example: `examples\u002Fpython\u002Fchat-leaderboard`.\n- **Chat commands:** declare commands with `plugin.commands({...})`. Command\n  tables support prefixes, aliases, parsed arguments, moderator gating, and\n  per-user cooldowns. Unknown and gated invocations are silent.\n\n## The manifest\n\n```json\n{\n  \"api\": \"1\",\n  \"name\": \"Welcome Bot\",\n  \"slug\": \"welcome-bot\",\n  \"version\": \"0.1.0\",\n  \"description\": \"Greets people when they join the chat\",\n  \"permissions\": [\"chat.send\"]\n}\n```\n\n- `name`: human-readable, and also the default chat-bot display name. `bot.displayName` overrides it.\n- `slug`: canonical id (URL prefix, storage namespace, filename). Auto-derived from `name` if omitted, but keep it explicit and matching the directory.\n- `permissions`: see the Capability map. Declare exactly what you use.\n- `config`: optional admin-configurable settings: `{ \"key\": { \"type\": \"string|number|boolean\", \"default\": ..., \"description\": \"...\" } }`, read via `owncast.config.get`.\n- UI fields (`actions`, `styles`, `scripts`, `extraPageContent`, `tabs`) all require `ui.modify`.\n- `tabs`: `{ \"tab-slug\": { \"title\": \"Tab label\", \"content\": \"optional.html\" } }`.\n- `admin.pages`: `{ \"\u002Fadmin\u002F*\": { \"title\": \"Settings\" } }`. The host auth-gates matching path keys.\n- **`network.fetch` also requires `network` block:** `\"network\": { \"allowedHosts\": [\"api.example.com\", \"*.weather.com\"] }`. The bare wildcard `\"*\"` is allowed but must be written explicitly. The host rejects the load if `network.fetch` is granted without `allowedHosts`.\n\n## Project layout\n\n```\n\u003Cslug>\u002F\n├── plugin.manifest.json   # identity + permissions\n├── icon.png               # optional: admin-list icon (bundled automatically)\n├── INSTRUCTIONS.md        # optional: rendered as an admin tab\n├── src\u002Fplugin.py          # your code\n├── public\u002F                # optional: served at \u002Fplugins\u002F\u003Cslug>\u002F...\n├── assets\u002F                # optional: host-read for inlined styles\u002Fscripts\u002FHTML (NOT URL-served)\n└── __tests__\u002F*.test.json  # scenario tests\n```\n\n## Testing\n\nReplace the scaffolded test with scenarios for your behavior. Each scenario is\nJSON: it dispatches events and asserts on observed side effects. The format is\nidentical to the JS SDK's and runs through the same `owncast-plugin-test` binary.\n\n```json\n[\n  {\n    \"name\": \"greets joining users\",\n    \"events\": [{ \"event\": \"chat.user.joined\", \"payload\": { \"id\": \"u1\", \"displayName\": \"alice\" } }],\n    \"expect\": { \"chatSends\": [\"welcome, alice!\"] }\n  }\n]\n```\n\nStep types: `event`, `filter` (with `expect: {action, payload?, reason?}`),\n`http` (`{method, path, expect:{status, bodyContains?}}`), `tabContent`,\n`pageContent`, `pageStyles`, `pageScripts`, and `authCheck` (drives\n`on_auth_check` for `auth.gate` plugins). Final-state assertions include `chatSends`, `chatActions`,\n`chatSystems`, `chatTo`, `sseSends`, `emits`, `kv`, `httpRequests`,\n`videoConfigWrites`. Seed inputs with `given` (`given.kv`, `given.config`,\n`given.stream`, `given.users`, `given.httpResponses`, etc.). Use `authenticated: true` or a\n`user` object on `http` steps to test admin\u002Fuser-gated endpoints.\n\nShapes that trip people up:\n\n- **A chat event's `user` is an object** (`{ \"id\", \"displayName\", \"scopes\"? }`)\n  in production. The test payload should match what your handler reads. If the\n  handler reads `msg.user.id` \u002F `.scopes` \u002F `.display_name`, pass an object\n  (`\"user\": { \"id\": \"u1\", \"displayName\": \"alice\" }`). A payload with no `user`\n  arrives as `msg.user is None`.\n- **`config` values come from the manifest defaults** unless the scenario seeds\n  admin overrides via `given.config` (`\"given\": { \"config\": { \"key\": \"value\" } }`).\n  `owncast.config.get(\"key\")` returns the override when seeded, otherwise the\n  `default` declared under `config` in `plugin.manifest.json`. Test both paths.\n- **One `given.httpResponses` entry per URL pattern.** The `url` is a glob\n  matched against the full URL (`\"https:\u002F\u002Fapi.example.com\u002Fuser*\"` covers any\n  query string) and the first match wins, so a sequence where the same URL must\n  answer differently across calls can't be modeled by fixtures.\n\nFor interactive iteration, `owncast-plugin-py serve` hosts the plugin on\n`http:\u002F\u002Flocalhost:8080\u002Fplugins\u002F\u003Cslug>\u002F` with `\u002F_dev\u002F*` endpoints to fire events.\n\n## Common recipes (copy and adapt)\n\n**Greeter** (`permissions: [\"chat.send\"]`):\n```python\n@plugin.on_chat_user_joined\ndef welcome(user):\n    owncast.chat.send(f\"welcome, {user.display_name}!\")\n```\n\n**Word filter** (`permissions: [\"chat.filter\"]`):\n```python\n@plugin.filter_chat_message\ndef block(msg):\n    return filter.drop(\"blocked\") if \"badword\" in msg.body.lower() else filter.pass_()\n```\n\n**External fetch on command** (`permissions: [\"chat.send\",\"network.fetch\"]`, `network.allowedHosts: [\"api.ipify.org\"]`):\n```python\n@plugin.on_chat_message\ndef ip(msg):\n    if msg.body.strip() != \"!ip\":\n        return\n    res = owncast.http.fetch(\"https:\u002F\u002Fapi.ipify.org?format=json\")\n    if res.status == 200:\n        owncast.chat.send(f\"IP: {json.loads(res.body)['ip']}\")\n```\n\n**Notify Discord on stream start** (`permissions: [\"notifications.send\"]`):\n```python\n@plugin.on_stream_started\ndef live(info):\n    owncast.notifications.discord(f\"Live now: {info.title or 'stream'}\")\n```\n\n## Where to go deeper\n\nThe repository's `docs\u002FPLUGIN_AUTHOR_GUIDE.md` is the exhaustive reference (every\nhandler, every API method, limits, SSE, admin pages, action buttons, viewer-page\ninjection, full testing model). Read the camelCase API names there as their\nPythonic `snake_case` forms. Worked Python examples live in `examples\u002Fpython\u002F`.\n\nThe public documentation at \u003Chttps:\u002F\u002Fowncast.online\u002Fdocs\u002Fplugins> covers the same\nground for authors who want a web reference: the\n[Python SDK](https:\u002F\u002Fowncast.online\u002Fdocs\u002Fplugins\u002Fsdks\u002Fpython),\n[Manifest](https:\u002F\u002Fowncast.online\u002Fdocs\u002Fplugins\u002Fmanifest),\n[Events](https:\u002F\u002Fowncast.online\u002Fdocs\u002Fplugins\u002Fevents),\n[Owncast APIs](https:\u002F\u002Fowncast.online\u002Fdocs\u002Fplugins\u002Fapis),\n[Permissions](https:\u002F\u002Fowncast.online\u002Fdocs\u002Fplugins\u002Fpermissions),\n[Testing](https:\u002F\u002Fowncast.online\u002Fdocs\u002Fplugins\u002Ftesting), and\n[Packaging](https:\u002F\u002Fowncast.online\u002Fdocs\u002Fplugins\u002Fpackaging) pages.\n\n## Checklist before you hand off the .ocpkg\n\n- [ ] `name`, `slug`, real `description` set (not the `\"An Owncast plugin\"` placeholder), and slug valid and matches the directory.\n- [ ] `permissions` lists exactly the APIs the code calls, no more and no less.\n- [ ] `network.allowedHosts` present if `network.fetch` is used, `ui.modify` present for any UI field, and `chat.filter` present if `filter_chat_message` is defined.\n- [ ] `INSTRUCTIONS.md` is written for the person installing\u002Frunning the plugin (what it does and how to use it once enabled), not the scaffold placeholder, and it ships in the `.ocpkg`.\n- [ ] `owncast-plugin-py test` passes, or, if it failed only on a toolchain\u002Fversion skew (not your logic), you confirmed that and said so.\n- [ ] `owncast-plugin-py package` produced `\u003Cslug>.ocpkg`, you gave the user its path and install instructions, and noted which permissions the admin must approve.\n","# Create an Owncast plugin (Python)\n\nThis skill walks any AI assistant through building a working Owncast plugin in\n**Python** for a non-expert user: gather what they want in plain language,\nscaffold the project, write the code and manifest, verify it with tests, and\nproduce the single `.ocpkg` file they upload to their Owncast server. The user\nshould never have to understand the runtime. You do that part.\n\n> **Picking a language?** Owncast plugins can be written in JavaScript or Python.\n> The two SDKs are first-class peers: the same handlers, APIs, permissions, and\n> manifest apply to both, and only the scaffolding and language syntax differ.\n> This skill is the **Python** path. For JavaScript, use `create-owncast-plugin-js`.\n> If the language isn't decided yet, start from the `create-owncast-plugin`\n> router, which gathers the author's intent and dispatches to the right one.\n\nThis file is the complete operating guide. It is written to be tool-agnostic:\nwherever it says \"ask the user,\" use whatever question mechanism your harness\noffers (a structured prompt UI, or just a plain chat question). Wherever it says\n\"run,\" use your shell\u002Fcommand tool.\n\n## What an Owncast plugin is (one paragraph)\n\nA plugin is Python that runs sandboxed inside the Owncast server. It subscribes\nto events (chat messages, stream start\u002Fstop, fediverse activity) by registering\nhandler functions with `@plugin.*` decorators, and calls back into Owncast\nthrough the `owncast.*` API (send chat, store data, fetch URLs, serve web pages,\netc.). A `plugin.manifest.json` declares the plugin's identity and the\n**permissions** it needs. Every API call requires its matching permission, or\nthe host refuses to load the plugin. The build step just emits the Python source\nas `\u003Cslug>.py` and bundles it with the manifest and assets into one `.ocpkg` file\nfor distribution.\n\n> Plugins ship as source, not a compiled binary. The Owncast host embeds one\n> Python engine and runs every Python plugin on it, so a package carries no\n> interpreter and an author never touches a wasm toolchain.\n\n## The workflow (follow in order)\n\n### Step 1: Understand what they want\n\nAsk the user, in plain language:\n\n1. **What should the plugin be called?** (e.g. \"Welcome Bot\"). Derive a **slug**\n   from it: lowercase, digits and hyphens only, must start with a letter, max 64\n   chars (e.g. `welcome-bot`). If their name can't map to a valid slug, propose\n   one and confirm.\n2. **What should it do?** Get concrete behavior, not a category. \"Greet people\n   when they join,\" \"delete messages containing a word,\" \"show a live chat\n   overlay on a web page,\" \"post to Discord when the stream goes live.\"\n\nThen map their description to capabilities using the **Capability map** below.\nThat tells you which handler(s) to write, which `owncast.*` calls to make, and\nwhich permissions the manifest must declare. If a request needs a high-trust\npermission (`fediverse.post`, `videoconfig.write`, `users.moderate`,\n`network.fetch` to arbitrary hosts, or `auth.gate`, which lets the host require\nthe plugin's login for operator-selected viewer resources), note it back to the\nuser. The server admin will have to approve it.\n\nKeep it small. Build the simplest plugin that does what they asked. You can\nalways add handlers later.\n\n### Step 2: Make sure you have a plugin project\n\n**If your working directory already contains a `plugin.manifest.json`**, you are\nalready inside a scaffolded plugin (this skill may have shipped inside it). Do\n**not** scaffold again. Skip to Step 3 and edit the project in place, using its\nexisting slug.\n\n**Otherwise, scaffold a new project** with the official scaffolder\n(non-interactive, takes the slug as an argument):\n\n```sh\nowncast-plugin-py new \u003Cslug>\n# or, without installing the SDK first:\nuvx owncast-plugin-py new \u003Cslug>\n```\n\nThis creates a `\u003Cslug>\u002F` directory with `plugin.manifest.json`,\n`src\u002Fplugin.py`, and `__tests__\u002Fplugin.test.json` already wired up. All\nsubsequent commands run **from inside that directory**.\n\n### Step 3: Write the plugin\n\nEdit two files based on what you learned in Step 1:\n\n- **`src\u002Fplugin.py`**: register only the handlers the behavior needs. See\n  **Writing handlers** and the **Capability map**.\n- **`plugin.manifest.json`**: set `name`, `description`, and the exact\n  `permissions` required by the handlers you register and APIs you call. See **The manifest**.\n\nIf the plugin serves web content, add files under `public\u002F` (web-served) or\n`assets\u002F` (host-read for inlined UI). Replace the scaffolded test in\n`__tests__\u002Fplugin.test.json` with scenarios that assert your actual behavior\n(see **Testing**).\n\n**Clear the scaffolded placeholders.** They ship verbatim, so don't leave the\ndefaults:\n\n- Set a real `description` in `plugin.manifest.json` (the scaffold leaves `\"An\n  Owncast plugin\"`).\n- **Fill in `INSTRUCTIONS.md`.** It's bundled into the `.ocpkg` and rendered as\n  an **Instructions** tab on the plugin's page in the Owncast admin. Its only\n  audience is the **person installing and running the plugin** (the Owncast\n  admin \u002F streamer), not you the developer. Write it for them, in plain\n  language: **what the plugin does and how to use it once enabled**, including any\n  settings to configure and what each does, the features it adds and how to use\n  them (e.g. chat commands like `!hello`, what happens automatically), and where\n  any page, button, or tab it adds shows up. You built the plugin, so describe\n  its real behavior concretely and accurately. Always write this to the best of\n  your ability. Don't ship the \"Write anything an Owncast admin should know…\"\n  placeholder and don't leave it empty.\n\n### Step 4: Test\n\n```sh\nowncast-plugin-py test\n```\n\nThe first run downloads and caches the host test\u002Fserve binaries (there's no wasm\ntoolchain: plugins run on the engine the host embeds). `test` emits\n`src\u002Fplugin.py` as `\u003Cslug>.py` and runs `__tests__\u002F*.test.json` against the real\nplugin runtime with mocked side effects, so a pass means the same behavior in\nproduction.\n\n**When the build or tests fail, first classify the failure. They need opposite\nresponses:**\n\n- **A behavior\u002Fassertion failure** (the test ran and the output didn't match, a\n  Python error in your handler, a missing permission for an API you call). This\n  is yours to fix: read the diff, correct `src\u002Fplugin.py`, the manifest, or the\n  expectation, and re-run. Don't package with these unresolved.\n- **A toolchain\u002Fversion-skew failure**, with host\u002Fruntime mismatch errors that fire\n  **before your test logic runs** (e.g. an import or host-function name the\n  runtime doesn't recognize). This is **not** a bug in your plugin, so don't edit\n  handlers to chase it. It means the installed SDK runtime and its bundled\n  test-host binary are out of sync. Respond by: (1) ensuring the latest version with\n  `uv tool upgrade owncast-plugin-py` (or `pip install -U owncast-plugin-py`) and re-run. (2) If\n  it persists, note that the compiled `.ocpkg` is still valid for a current\n  Owncast server (the skew is only in the local test harness), proceed to **Step\n  5**, and tell the user tests couldn't run locally due to a toolchain version\n  mismatch. Do not loop on it.\n\n(If the toolchain can't be fetched because there's no network, tell the user\nthat's required once, and continue to write correct code so they can run\n`owncast-plugin-py test && owncast-plugin-py package` themselves.)\n\n### Step 5: Package and hand off\n\n```sh\nowncast-plugin-py package\n```\n\n`package` first load-checks the plugin — the same install-time path a real\nOwncast server runs. A handler whose gating permission isn't declared in the\nmanifest (a chat filter without `chat.filter`, a fediverse handler without\n`fediverse.inbound`) aborts packaging with the exact error the server would\ngive at install. Fix the manifest, don't work around the check.\n\nThis produces **`\u003Cslug>.ocpkg`** in the project directory, a single\nself-contained file bundling the manifest, the `plugin.py` source, and any\n`public\u002F`\u002F`assets\u002F`\u002F`icon.png`\u002F`INSTRUCTIONS.md`. Give the user the path to that\nfile and tell them how to install it:\n\n> Open **Plugins** in your Owncast admin → **Upload plugin** → select\n> `\u003Cslug>.ocpkg`. Then review the **Permissions** tab and toggle **Enabled**.\n> (Alternatively, drop the file into `data\u002Fplugins\u002F` on the server.)\n\nBriefly summarize what the plugin does and which permissions the admin will be\nasked to approve, and why each is needed.\n\n---\n\n## Capability map (intent → handler + API + permission)\n\nMatch the user's described behavior to these rows. Register the listed\nhandler(s), call the listed API, and add the listed permission to the manifest.\nSeveral rows combine for richer plugins.\n\n| They want to…                                   | Handler(s)                                          | API call                                       | Permission(s)                          |\n| ----------------------------------------------- | --------------------------------------------------- | ---------------------------------------------- | -------------------------------------- |\n| React to chat messages                          | `@plugin.on_chat_message`                           | —                                              | — (add `chat.send` to reply)           |\n| Reply \u002F post in chat                            | (any handler)                                       | `owncast.chat.send(text)` \u002F `.send_action`     | `chat.send`                            |\n| Whisper privately to a sender                   | `on_chat_message` \u002F `filter_chat_message`           | `owncast.chat.reply_to(msg, text)`             | `chat.send`                            |\n| Run chat commands (`!uptime`, etc.)             | `plugin.commands({...})`                             | `ctx.reply` \u002F `ctx.reply_privately`            | `chat.send` to reply                  |\n| Inspect\u002Fmodify\u002Fdrop every message (moderation)  | `@plugin.filter_chat_message`                       | `filter.pass_\u002Fmodify\u002Fdrop`                     | `chat.filter` (required for the handler) |\n| Delete a message \u002F kick a client                | (any)                                               | `owncast.chat.delete_message` \u002F `.kick`        | `chat.moderate`                        |\n| Read recent chat \u002F list clients                 | (any)                                               | `owncast.chat.history()` \u002F `.clients()`        | `chat.history`                         |\n| React when stream goes live \u002F stops             | `@plugin.on_stream_started` \u002F `_stopped`            | —                                              | —                                      |\n| Read live stream state (title, viewers, uptime) | (any)                                               | `owncast.stream.current()`                     | `server.read`                          |\n| Read server info \u002F socials \u002F emotes \u002F tags      | (any)                                               | `owncast.server.*()`                           | `server.read`                          |\n| Store per-user or persistent state              | (any)                                               | `owncast.kv.get\u002Fset` (+ `get_json\u002Fset_json`)   | `storage.kv`                           |\n| Rank or aggregate data (private SQL database)   | (any)                                               | `owncast.sql.exec\u002Fquery\u002Fquery_row`             | `storage.sql`                          |\n| Expose admin-configurable settings              | (read at runtime)                                   | `owncast.config.get(key, fallback=None)`       | — (declare under `config` in manifest) |\n| Call an external API \u002F webhook                  | (any)                                               | `owncast.http.fetch(url, opts=None)`           | `network.fetch` + `network.allowedHosts` |\n| Do delayed \u002F periodic work                      | `@plugin.on_tick` or `owncast.timer.*`              | `owncast.timer.set_timeout\u002Fset_interval`       | — (ambient)                            |\n| Serve a web page \u002F overlay \u002F JSON endpoint      | `@plugin.get\u002Fpost\u002F...` \u002F `on_http_request` + `public\u002F` | return `{status, headers, body}`            | `http.serve`                           |\n| Push realtime updates to a browser              | (any)                                               | `owncast.sse.send(channel, event, data)`       | `http.sse`                             |\n| Add an admin settings page in the Owncast UI    | `@plugin.on_http_request` + `public\u002Fadmin\u002F...`      | —                                              | `http.serve` + `admin.pages` manifest  |\n| Add a button under the viewer's stream          | (manifest only, or `owncast.actions.add`)           | —                                              | `ui.modify` (+ `http.serve` if it opens your page) |\n| Inject CSS \u002F JS \u002F HTML into the viewer page     | (manifest `styles`\u002F`scripts`\u002F`extraPageContent`)    | dynamic `@plugin.on_page_styles` \u002F `on_page_scripts` \u002F `on_page_content` | `ui.modify`                            |\n| Add a tab to the viewer page                    | optional `@plugin.on_tab_content`                   | —                                              | `ui.modify` (+ data perms used)        |\n| Upload a file and get a public URL              | (any)                                               | `owncast.storage.upload(name, bytes)`          | `storage.upload`                       |\n| Private server-side files                       | (any)                                               | `owncast.fs.*`                                 | `storage.fs`                           |\n| Send Discord \u002F browser-push \u002F fediverse notice  | (any)                                               | `owncast.notifications.*`                      | `notifications.send`                   |\n| Post publicly to the fediverse (high-trust)     | (any)                                               | `owncast.fediverse.post(text)`                 | `fediverse.post`                       |\n| React to any verified inbound fediverse activity | `@plugin.on_fediverse` gets a non-subscriptable `_Obj` attribute view. Use `payload.raw` for the underlying dictionary and keys like `@context`. Specialized handlers: `@plugin.on_fediverse_follow\u002Flike\u002Frepost\u002Fquote\u002Fmention\u002Freply` | none | `fediverse.inbound` |\n| Read\u002Fchange video\u002Ftranscoding config            | (any)                                               | `owncast.video_config.read\u002Fwrite`              | `videoconfig.read` \u002F `videoconfig.write` |\n| Compose with other plugins via custom events    | own local hooks with `@plugin.on(...)`, emit to `\u003Crecipient-slug>.\u003Chook>` | `owncast.events.emit(type, payload)` | `events.emit` (emitter only) |\n| Gate the site behind a member login (paywall) | `@plugin.on_http_request` (login flow) + `@plugin.on_auth_check` (re-validation) | `owncast.users.register` + `owncast.auth.grant_session\u002Fend_session` | `auth.gate` + `users.register` (+ `http.serve`); model on `examples\u002Fpython\u002Fgithub-auth` |\n\n**Golden rule:** the `permissions` array must contain exactly the permissions\nrequired by the handlers you register and every `owncast.*` method you call.\nMissing one means the call throws and\u002For the host refuses to load the plugin.\nDon't add permissions you don't use, since admins judge trust by the declared list.\n\n---\n\n## Writing handlers\n\n```python\nfrom owncast_plugin import plugin, owncast, filter\n\n\n@plugin.on_chat_message\ndef greet(msg):\n    # msg has attributes: id, user, client_id, body, timestamp. msg.user is a\n    # User (msg.user.id, .display_name, .display_color, .scopes) in production, or None for\n    # a message with no associated account. Read the name defensively.\n    name = msg.user.display_name if msg.user else \"there\"\n    words = msg.body.split()\n    if words and words[0].lower() == \"hi\":\n        owncast.chat.send(f\"hello, {name}!\")\n```\n\nRegister **only** the handlers you need. The SDK derives event subscriptions\nfrom which handlers exist. Decorators: `@plugin.on_chat_message`,\n`@plugin.filter_chat_message`, `@plugin.on_chat_user_joined` \u002F `_parted` \u002F\n`_renamed`, `@plugin.on_message_moderated`, `@plugin.on_stream_started` \u002F\n`_stopped` \u002F `_title_changed`, `@plugin.on_fediverse`,\n`@plugin.on_fediverse_follow` \u002F `_like` \u002F `_repost` \u002F `_quote` \u002F `_mention` \u002F `_reply`, `@plugin.on_tick`, `@plugin.on_sse_connect` \u002F\n`_disconnect`, `@plugin.on_tab_content(\"slug\")`, `@plugin.on_page_content(\"slug\")`,\n`@plugin.on_page_styles`, `@plugin.on_page_scripts`,\nHTTP routes (`@plugin.get\u002Fpost\u002Fput\u002Fdelete\u002Fpatch(path)`, `@plugin.route`,\n`@plugin.on(\"event\")` for local custom hooks. The host registers each as\n`\u003Cyour-plugin-slug>.event`, which emitters use as the target.\n\nImportant shape\u002Fbehavior notes:\n\n- **`msg.user` is an attribute object or `None`.** Production sends a User\n  (`msg.user.id`, `msg.user.display_name`, `msg.user.display_color`, `msg.user.scopes`). A message with no\n  account is `None`. Read the name defensively: `msg.user.display_name if\n  msg.user else \"...\"`. For stable per-user state and moderator gating use\n  `msg.user.id` and `msg.user.scopes`, never the display name. Use\n  `msg.raw` for the underlying dict. Declarative command tables handle\n  moderator gating automatically.\n- **Chat text is HTML-escaped on display.** `chat.send`\u002F`send_action` take plain\n  text. The exception is `chat.system(body)`, whose body renders as HTML, so escape\n  untrusted content yourself.\n- **Filters fail open and are time-capped (50 ms).** `filter_chat_message` must\n  be fast. A filter that errors is treated as `filter.pass_()`. Five consecutive\n  failures auto-disable the plugin for the session.\n- **`filter.pass_()` has a trailing underscore** (`pass` is a Python keyword).\n- **No `time.sleep` \u002F threads for delays.** Use `owncast.timer.*`. Timers don't\n  survive a host restart.\n- **`owncast.sql.*` is one private SQLite database per plugin.** Each `exec` is\n  a single atomic transaction, so a multi-statement schema setup either lands\n  whole or not at all. An unbounded `query` that overruns the host's row or\n  result budget is an error, not a truncated result, so write a `LIMIT`, or use\n  `query_row` when you only need one row. Plugin databases are not included in\n  Owncast's backups. Worked example: `examples\u002Fpython\u002Fchat-leaderboard`.\n- **Chat commands:** declare commands with `plugin.commands({...})`. Command\n  tables support prefixes, aliases, parsed arguments, moderator gating, and\n  per-user cooldowns. Unknown and gated invocations are silent.\n\n## The manifest\n\n```json\n{\n  \"api\": \"1\",\n  \"name\": \"Welcome Bot\",\n  \"slug\": \"welcome-bot\",\n  \"version\": \"0.1.0\",\n  \"description\": \"Greets people when they join the chat\",\n  \"permissions\": [\"chat.send\"]\n}\n```\n\n- `name`: human-readable, and also the default chat-bot display name. `bot.displayName` overrides it.\n- `slug`: canonical id (URL prefix, storage namespace, filename). Auto-derived from `name` if omitted, but keep it explicit and matching the directory.\n- `permissions`: see the Capability map. Declare exactly what you use.\n- `config`: optional admin-configurable settings: `{ \"key\": { \"type\": \"string|number|boolean\", \"default\": ..., \"description\": \"...\" } }`, read via `owncast.config.get`.\n- UI fields (`actions`, `styles`, `scripts`, `extraPageContent`, `tabs`) all require `ui.modify`.\n- `tabs`: `{ \"tab-slug\": { \"title\": \"Tab label\", \"content\": \"optional.html\" } }`.\n- `admin.pages`: `{ \"\u002Fadmin\u002F*\": { \"title\": \"Settings\" } }`. The host auth-gates matching path keys.\n- **`network.fetch` also requires `network` block:** `\"network\": { \"allowedHosts\": [\"api.example.com\", \"*.weather.com\"] }`. The bare wildcard `\"*\"` is allowed but must be written explicitly. The host rejects the load if `network.fetch` is granted without `allowedHosts`.\n\n## Project layout\n\n```\n\u003Cslug>\u002F\n├── plugin.manifest.json   # identity + permissions\n├── icon.png               # optional: admin-list icon (bundled automatically)\n├── INSTRUCTIONS.md        # optional: rendered as an admin tab\n├── src\u002Fplugin.py          # your code\n├── public\u002F                # optional: served at \u002Fplugins\u002F\u003Cslug>\u002F...\n├── assets\u002F                # optional: host-read for inlined styles\u002Fscripts\u002FHTML (NOT URL-served)\n└── __tests__\u002F*.test.json  # scenario tests\n```\n\n## Testing\n\nReplace the scaffolded test with scenarios for your behavior. Each scenario is\nJSON: it dispatches events and asserts on observed side effects. The format is\nidentical to the JS SDK's and runs through the same `owncast-plugin-test` binary.\n\n```json\n[\n  {\n    \"name\": \"greets joining users\",\n    \"events\": [{ \"event\": \"chat.user.joined\", \"payload\": { \"id\": \"u1\", \"displayName\": \"alice\" } }],\n    \"expect\": { \"chatSends\": [\"welcome, alice!\"] }\n  }\n]\n```\n\nStep types: `event`, `filter` (with `expect: {action, payload?, reason?}`),\n`http` (`{method, path, expect:{status, bodyContains?}}`), `tabContent`,\n`pageContent`, `pageStyles`, `pageScripts`, and `authCheck` (drives\n`on_auth_check` for `auth.gate` plugins). Final-state assertions include `chatSends`, `chatActions`,\n`chatSystems`, `chatTo`, `sseSends`, `emits`, `kv`, `httpRequests`,\n`videoConfigWrites`. Seed inputs with `given` (`given.kv`, `given.config`,\n`given.stream`, `given.users`, `given.httpResponses`, etc.). Use `authenticated: true` or a\n`user` object on `http` steps to test admin\u002Fuser-gated endpoints.\n\nShapes that trip people up:\n\n- **A chat event's `user` is an object** (`{ \"id\", \"displayName\", \"scopes\"? }`)\n  in production. The test payload should match what your handler reads. If the\n  handler reads `msg.user.id` \u002F `.scopes` \u002F `.display_name`, pass an object\n  (`\"user\": { \"id\": \"u1\", \"displayName\": \"alice\" }`). A payload with no `user`\n  arrives as `msg.user is None`.\n- **`config` values come from the manifest defaults** unless the scenario seeds\n  admin overrides via `given.config` (`\"given\": { \"config\": { \"key\": \"value\" } }`).\n  `owncast.config.get(\"key\")` returns the override when seeded, otherwise the\n  `default` declared under `config` in `plugin.manifest.json`. Test both paths.\n- **One `given.httpResponses` entry per URL pattern.** The `url` is a glob\n  matched against the full URL (`\"https:\u002F\u002Fapi.example.com\u002Fuser*\"` covers any\n  query string) and the first match wins, so a sequence where the same URL must\n  answer differently across calls can't be modeled by fixtures.\n\nFor interactive iteration, `owncast-plugin-py serve` hosts the plugin on\n`http:\u002F\u002Flocalhost:8080\u002Fplugins\u002F\u003Cslug>\u002F` with `\u002F_dev\u002F*` endpoints to fire events.\n\n## Common recipes (copy and adapt)\n\n**Greeter** (`permissions: [\"chat.send\"]`):\n```python\n@plugin.on_chat_user_joined\ndef welcome(user):\n    owncast.chat.send(f\"welcome, {user.display_name}!\")\n```\n\n**Word filter** (`permissions: [\"chat.filter\"]`):\n```python\n@plugin.filter_chat_message\ndef block(msg):\n    return filter.drop(\"blocked\") if \"badword\" in msg.body.lower() else filter.pass_()\n```\n\n**External fetch on command** (`permissions: [\"chat.send\",\"network.fetch\"]`, `network.allowedHosts: [\"api.ipify.org\"]`):\n```python\n@plugin.on_chat_message\ndef ip(msg):\n    if msg.body.strip() != \"!ip\":\n        return\n    res = owncast.http.fetch(\"https:\u002F\u002Fapi.ipify.org?format=json\")\n    if res.status == 200:\n        owncast.chat.send(f\"IP: {json.loads(res.body)['ip']}\")\n```\n\n**Notify Discord on stream start** (`permissions: [\"notifications.send\"]`):\n```python\n@plugin.on_stream_started\ndef live(info):\n    owncast.notifications.discord(f\"Live now: {info.title or 'stream'}\")\n```\n\n## Where to go deeper\n\nThe repository's `docs\u002FPLUGIN_AUTHOR_GUIDE.md` is the exhaustive reference (every\nhandler, every API method, limits, SSE, admin pages, action buttons, viewer-page\ninjection, full testing model). Read the camelCase API names there as their\nPythonic `snake_case` forms. Worked Python examples live in `examples\u002Fpython\u002F`.\n\nThe public documentation at \u003Chttps:\u002F\u002Fowncast.online\u002Fdocs\u002Fplugins> covers the same\nground for authors who want a web reference: the\n[Python SDK](https:\u002F\u002Fowncast.online\u002Fdocs\u002Fplugins\u002Fsdks\u002Fpython),\n[Manifest](https:\u002F\u002Fowncast.online\u002Fdocs\u002Fplugins\u002Fmanifest),\n[Events](https:\u002F\u002Fowncast.online\u002Fdocs\u002Fplugins\u002Fevents),\n[Owncast APIs](https:\u002F\u002Fowncast.online\u002Fdocs\u002Fplugins\u002Fapis),\n[Permissions](https:\u002F\u002Fowncast.online\u002Fdocs\u002Fplugins\u002Fpermissions),\n[Testing](https:\u002F\u002Fowncast.online\u002Fdocs\u002Fplugins\u002Ftesting), and\n[Packaging](https:\u002F\u002Fowncast.online\u002Fdocs\u002Fplugins\u002Fpackaging) pages.\n\n## Checklist before you hand off the .ocpkg\n\n- [ ] `name`, `slug`, real `description` set (not the `\"An Owncast plugin\"` placeholder), and slug valid and matches the directory.\n- [ ] `permissions` lists exactly the APIs the code calls, no more and no less.\n- [ ] `network.allowedHosts` present if `network.fetch` is used, `ui.modify` present for any UI field, and `chat.filter` present if `filter_chat_message` is defined.\n- [ ] `INSTRUCTIONS.md` is written for the person installing\u002Frunning the plugin (what it does and how to use it once enabled), not the scaffold placeholder, and it ships in the `.ocpkg`.\n- [ ] `owncast-plugin-py test` passes, or, if it failed only on a toolchain\u002Fversion skew (not your logic), you confirmed that and said so.\n- [ ] `owncast-plugin-py package` produced `\u003Cslug>.ocpkg`, you gave the user its path and install instructions, and noted which permissions the admin must approve.\n",{"name":5,"description":7},"main","3928e52173698bd34afb9e360f500b1553d8dd2f","sdks\u002Fpython\u002Fowncast_plugin\u002Ftemplate\u002F.agents\u002Fskills\u002Fcreate-owncast-plugin-py",0,"https:\u002F\u002Fgithub.com\u002Fowncast\u002Fplugin-sdk","https:\u002F\u002Fowncast.online\u002Fdocs\u002Fplugins","https:\u002F\u002Fgithub.com\u002Fowncast","http:\u002F\u002Fowncast.online","A self-hosted live stream server with chat features.","2026-10-11 08:19:38",{"source":8,"skillName":5,"commands":35,"prompt":45,"zipAvailable":46},[36,39,42],{"tool":37,"command":38},"npx","npx skills add owncast\u002Fplugin-sdk --skill create-owncast-plugin-py",{"tool":40,"command":41},"bunx","bunx skills add owncast\u002Fplugin-sdk --skill create-owncast-plugin-py",{"tool":43,"command":44},"pnpm","pnpm dlx skills add owncast\u002Fplugin-sdk --skill create-owncast-plugin-py","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fowncast\u002Fplugin-sdk\u002Fblob\u002Fmain\u002Fsdks\u002Fpython\u002Fowncast_plugin\u002Ftemplate\u002F.agents\u002Fskills\u002Fcreate-owncast-plugin-py\u002FSKILL.md",true,[],[49,56,63,68],{"skillNo":50,"name":51,"nameZh":6,"description":52,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":53,"categories":54,"keywords":55,"publishedAt":19},"01M734FG8CQDBPQ694GDYYAEQK","create-owncast-plugin-js","Build a complete Owncast plugin in JavaScript from a plain-language description and hand back an installable .ocpkg file. Use when someone wants to create, build, scaffold, or make an Owncast plugin in JavaScript\u002FNode (a chat bot, chat filter\u002Fmoderation tool, stream-event responder, HTTP page\u002Foverlay\u002Fwidget, admin page, fediverse integration, etc.) without needing to know the SDK internals. If the author hasn't picked a language yet, start from create-owncast-plugin (the router) instead.","https:\u002F\u002Fgithub.com\u002Fowncast\u002Fplugin-sdk\u002Fblob\u002Fmain\u002Fsdks\u002Fjs\u002Fcreate-owncast-plugin\u002Ftemplate\u002F.agents\u002Fskills\u002Fcreate-owncast-plugin-js\u002FSKILL.md",[],[],{"skillNo":57,"name":58,"nameZh":6,"description":59,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":60,"categories":61,"keywords":62,"publishedAt":19},"01M734F94NDEWJNF2M4C9EHZZE","create-owncast-plugin","Use this skill whenever someone wants to create, build, scaffold, or set up an Owncast plugin, or just describes new behavior they want in their Owncast chat or server without naming it a 'plugin.' This is the entry point for any new plugin, in any language: a chat bot or auto-responder, a welcome greeter, a word\u002Flink filter or moderation action, a moderator button or admin page, a stream-going-live reaction, a fediverse follow\u002Fpost integration, or a live web overlay or widget (viewer count, chat feed). Casual asks count fully: 'I run an Owncast server and want a bot that…', 'make me something that auto-replies when…', 'add a button so mods can…'. It captures the desired behavior, settles on JavaScript or Python, then hands off to the matching language skill. Skip it only when the language is already chosen (use the JavaScript or Python skill directly), and for general Owncast streaming\u002Finstall\u002Fconfig help or bots on other platforms like Twitch or Discord.","https:\u002F\u002Fgithub.com\u002Fowncast\u002Fplugin-sdk\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fcreate-owncast-plugin\u002FSKILL.md",[],[],{"skillNo":64,"name":5,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":65,"categories":66,"keywords":67,"publishedAt":19},"01M734F6S9P0AF9JW577FZTPWD","https:\u002F\u002Fgithub.com\u002Fowncast\u002Fplugin-sdk\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fcreate-owncast-plugin-py\u002FSKILL.md",[],[],{"skillNo":69,"name":51,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":70,"categories":71,"keywords":72,"publishedAt":19},"01M734F4E68J3R8H7PJFN82EMY","https:\u002F\u002Fgithub.com\u002Fowncast\u002Fplugin-sdk\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fcreate-owncast-plugin-js\u002FSKILL.md",[],[]]