Расширьте 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, федиверсом, push-уведомлениями в браузере или любым HTTPS-сервисом.
• Инструменты администратора, которые добавляют вкладку в административный интерфейс Owncast для настроек, связанных с плагинами.
• Кнопки действий, которые появляются под вашим потоком, открывая виджеты, страницы пожертвований или что-то еще, что вы обслуживаете.

Каждый пример плагина в 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. Вызывайте API Owncast. owncast.chat.send(text), owncast.kv.get(key), owncast.http.fetch(url) и десятки других, большинство из которых требуют разрешения.
4. Обслуживать HTTP. Каждый плагин может владеть пространством URL по адресу /plugins/<ваш-слуг>/... как для статических ресурсов, так и для динамических обработчиков.
5. Добавить интерфейс. Объявите страницы администратора, кнопки действий, таблицы стилей плагина, скрипты плагина или блок HTML с дополнительным содержимым в вашем манифесте, и Owncast встроит их в свой собственный интерфейс.
6. Ограничить доступ. Плагин может быть провайдером аутентификации сайта. Заставьте зрителей авторизоваться (OAuth, пароль, все, что через HTTP) перед тем, как они смогут получить доступ к странице, видео, чату или API.

Что плагин не может делать

По дизайну:

• Нет прямого доступа к файловой системе хоста, сети или процессам. Песочница гарантирует это. Плагины делают то, что открывают API хоста, и только с заявленными разрешениями.
• Нет идентификации подмены. Каждый плагин получает одну идентичность чата (бот, установленный Owncast), и исходящие сообщения федиверса приходят от аккаунта стримера.
• Нет кроссплагинового чтения. Хранилище ключ-значение каждого плагина имеет свое пространство имен.
• Нет бесконечного блокирования чата. Звонки фильтра ограничены по времени до 50 мс, и плагин, который много раз вызывает ошибку, автоматически отключается.

Вот почему администратор может установить сторонний плагин, не проверяя каждую строчку кода. Граница доверия — это список разрешений манифеста.

Куда идти дальше

• Быстрый старт. Создайте новый плагин, соберите его, установите.
• JavaScript, Python, and Native WebAssembly. Choose a language and build path.
• Справка по манифесту. Каждое поле, которое может содержать ваш plugin.manifest.json.
• Чат-плагины. Создайте ботов, инструменты модерации и фильтры чата.
• События. Каждое событие, на которое ваш плагин может подписаться, с формами полезных нагрузок.
• API Owncast. Каждый метод owncast.*, его задача и необходимые разрешения.
• Разрешения. Полный список и как работает модель безопасности.
• Обслуживание HTTP. Обслуживайте URL-адреса из вашего плагина и отправляйте события в реальном времени в браузеры.
• Внесение UI. Зарегистрируйте страницы администратора и внесите кнопки действий под стрим.
• Тестирование. Сценарные тесты, которые запускают ваш плагин через реальный процесс выполнения.
• Упаковка и публикация. Упакуйте .ocpkg, установите его и перечислите в каталоге.

Источник

• Исходный код SDK: github.com/owncast/plugin-sdk
• Example plugins: JavaScript · Python