使用插件扩展 Owncast

Owncast 可以通过 插件 进行扩展：小程序在运行时由服务器加载，以响应聊天消息、流事件、联邦宇宙活动和 HTTP 请求。 它们在沙盒内运行，因此插件可以崩溃而不会导致服务器崩溃，宿主强制执行明确的权限模型，因此管理员始终可以知道插件可以访问的内容。

Plugins require Owncast v0.3.0

插件是全新的功能，在 Owncast 0.3.0 中引入，API 仍在发展中。 如果您遇到错误或有建议，请 打开问题 或 与社区实时聊天。

You can write a plugin with the JavaScript SDK, the Python SDK, or as a native WebAssembly module. The two SDKs are the recommended paths for most plugins. Native WebAssembly is an advanced option for compiled languages and direct access to the plugin wire protocol.

您可以构建的内容

• 响应关键字或命令的聊天机器人，发布提醒，进行投票或管理垃圾邮件。
• 在到达观众之前重写或丢弃聊天消息的过滤器。
• 在您的流上方呈现的覆盖，连接到您的插件的 HTTP 端点。
• 桥接 Owncast 与 Discord、联邦宇宙、浏览器推送或任何 HTTPS 服务的集成。
• 向 Owncast 管理 UI 添加标签，用于插件特定设置的管理工具。
• 在您的流下方出现的操作按钮，启动小部件、捐赠页面或您提供的任何其他内容。

SDK 中的每个示例插件都是您可以复制的完整起点。

Choose an authoring path

All three paths produce the same .ocpkg format and use the same manifest, permissions, events, and Owncast APIs.

• JavaScript 通过 @owncast/plugin-sdk。 Scaffold with npx create-owncast-plugin, write definePlugin({ ... }), and build with npm run package.
• Python 通过 owncast-plugin-py。 Scaffold with uvx owncast-plugin-py new, write decorated functions, and build with owncast-plugin-py package.
• Native WebAssembly with Rust, TinyGo, AssemblyScript, Zig, or another compiled language. Implement the wire protocol directly and package the compiled module as plugin.wasm.

The same echo bot in each SDK:

// JavaScript
const { definePlugin, owncast } = require('@owncast/plugin-sdk');

module.exports = definePlugin({
  onChatMessage(msg) {
    owncast.chat.send(`echo: ${msg.body}`);
  },
});

# Python
from owncast_plugin import plugin, owncast

@plugin.on_chat_message
def echo(msg):
    owncast.chat.send(f"echo: {msg.body}")

它是如何结合在一起的

插件是一个包含您插件清单、编译代码和任何静态资产的单 .ocpkg 文件。 管理员将文件放入 Owncast 的 data/plugins/ 目录，并从 插件 页面启用它。

启用后，插件在 Owncast 进程内运行。 您定义的处理程序在匹配事件发生时触发。 您调用的 API（发送聊天、读取配置、获取 URL）通过宿主，宿主检查您在清单中声明的权限。

Each enabled plugin uses more server memory. JavaScript and Python share one runtime per language, so the first plugin in either language has a larger one-time cost. A native WebAssembly plugin loads its own compiled module instead of a shared language runtime.

插件可以做什么

1. 订阅事件。 聊天消息、流开始和停止、联邦宇宙关注、新聊天用户加入。 定义处理程序方法，SDK 将推导订阅。
2. 过滤聊天。 在广播之前查看每条聊天消息，修改或丢弃它。
3. 调用 Owncast API。 owncast.chat.send(text)、owncast.kv.get(key)、owncast.http.fetch(url) 以及数十个更多，通常需要声明的权限。
4. 提供 HTTP 服务。 每个插件可以拥有 /plugins/<your-slug>/... 的 URL 空间，用于静态资产和动态处理程序。
5. 添加 UI。 在您的清单中声明管理页面、操作按钮、插件样式表、插件脚本或额外内容 HTML 块，Owncast 会将它们嵌入自己的 chrome。
6. 限制访问。 插件可以是网站的身份验证提供者。 让观众登录（OAuth、密码、任何通过 HTTP 进行的身份验证）之前才能访问页面、视频、聊天或 API。

插件不能做什么

按设计：

• 无法直接访问主机文件系统、网络或进程。 沙盒强制执行这一点。 插件做主机 API 所公开的事情，并且只需声明的权限。
• 不能伪装身份。 每个插件获得一个聊天身份（Owncast 在安装时提供的机器人），来自流媒体的外发联邦宇宙帖子来自主播的个人账户。
• 无法跨插件读取。 每个插件的键值存储是命名空间的。
• 不能无限期封锁聊天。 过滤调用的时间限制为 50 毫秒，重复抛出的插件会自动禁用。

这就是为什么管理员可以安装第三方插件而无需审计每一行代码。 信任边界是清单的权限列表。

接下来去哪里

• 快速入门。 构建一个新的插件，构建它，安装它。
• JavaScript, Python, and Native WebAssembly. Choose a language and build path.
• 清单参考。 您的 plugin.manifest.json 可以包含的每个字段。
• 聊天插件。 构建机器人、审核工具和聊天过滤器。
• 事件。 您的插件可以订阅的每个事件及其负载形状。
• Owncast API。 每个 owncast.* 方法，它的功能以及需要的权限。
• 权限。 完整列表以及安全模型的工作方式。
• 提供 HTTP 服务。 从您的插件提供 URL 并向浏览器推送实时事件。
• 贡献 UI。 注册管理页面，并在流下方提供操作按钮。
• 测试。 通过实际运行时驱动您的插件的场景测试。
• 打包和发布。 打包 .ocpkg，安装它，并在目录中列出它。

源代码

• SDK 源代码：github.com/owncast/plugin-sdk
• Example plugins: JavaScript · Python