Owncast default Readme for Avatars

An Owncast plugin: an "Avatar" button next to Notify (with an on/off switch) opens a 32x32 pixel-art editor. This editor enables chatter to create and cusotmize their own avatar with 3 different animations(idle/walk/dance). Admins can configure settings such as frame count (6 by default), speach bubbles, dance duration and more. Some control is also given such as admin-appoved changes, user avatar banning and show all/none control. An /overlay.html page showing currently present chatter's avatars, add it as an OBS Browser Source. See INSTRUCTIONS.md for the admin-facing usage doc that ships inside the .ocpkg.

The slug is avatars, and everything below uses it as the build artifact filename and the URL prefix Owncast routes through your plugin.

New end-points

• GET /my-avatar - the signed-in viewer's own saved avatar
• GET /editor-settings - the current per-animation frame cap, for the editor
• POST /save - save/update the viewer's avatar
• POST /toggle - turn the viewer's avatar on/off on the overlay
• GET /overlay-data - avatars of viewers currently in chat plus overlay behavior tuning (bubble chance, walk/dance timing), for the overlay to render
• GET/POST /admin/api/settings - read/edit all admin settings
• POST /admin/api/avatars - search/list saved avatars
• POST /admin/api/avatar - full detail (all frames) for one avatar
• POST /admin/api/ban - ban/unban an avatar
• POST /admin/api/approve - approve/unapprove an avatar
• POST /admin/api/clean-deleted - remove avatars of Owncast users that no longer exist

Default README (not super important)

Develop

uvx owncast-plugin-py build        # emit src/plugin.py as avatars.py
uvx owncast-plugin-py test         # build, then run scenarios from __tests__/
uvx owncast-plugin-py serve        # build, then host the plugin on http://localhost:8080
uvx owncast-plugin-py package      # build, then bundle into avatars.ocpkg for distribution

uvx runs the CLI without installing anything. To get the shorter owncast-plugin-py command on your PATH, install the SDK once with uv tool install owncast-plugin-py (or pip install owncast-plugin-py), then drop the uvx prefix.

Plugins ship as source and run on the Python engine the Owncast host embeds, so there's no compile step and no toolchain to install. test/serve download and cache the host binaries on first use, and that's it.

Ship

owncast-plugin-py package produces avatars.ocpkg. Install it through the Owncast admin: open Plugins, click Upload plugin, and pick the file. (You can also copy it directly to the server's data/plugins/ directory if the admin UI isn't an option.) Toggle Enabled to load it.

Files

• src/plugin.py, your handler code. Edit this
• plugin.manifest.json, the manifest: display name, slug, version, permissions, and optional bot.displayName for the chat identity
• __tests__/plugin.test.json, a sample scenario test. Add more
• icon.png (optional), drop a square PNG here and it bundles into the .ocpkg automatically. The admin uses it in the plugin list and sidebar, no permission required. Plugins without one fall back to a generic puzzle-piece glyph.
• INSTRUCTIONS.md (optional), edit this and it bundles into the .ocpkg automatically. The admin renders it as markdown in an Instructions tab on the plugin's details page, no permission required.

Learn more

The full author guide covers every event handler, host API, permission, and testing pattern (read the API names as their Pythonic snake_case forms):

→ Owncast Plugin Author Guide

from owncast_plugin import plugin, owncast, filter is importable on your dev machine for editor support and unit tests.