Руководство по плагинам

The quickest way to build a plugin is with the JavaScript or Python SDK. Pick a tab below and follow it through installation. To use Rust, TinyGo, AssemblyScript, Zig, or another compiled language instead, see Native WebAssembly.

Предварительные требования

• Сервер Owncast, которым вы можете управлять, версии 0.3.0 или новее.

JavaScript

• Node.js 18 или новее (node --version для проверки) для инструментария @owncast/plugin-sdk.

Python

• Python 3.8 или новее, и uv или pip для установки инструментария owncast-plugin-py.

1. Создайте новый плагин

Идентификатор плагина — это его slug: строчные буквы, цифры и дефисы, начинающиеся с буквы. Он используется в качестве имени директории, имени выходного файла и префикса URL.

JavaScript

Создайте проект с помощью create-owncast-plugin, передавая slug:

npx create-owncast-plugin@latest my-plugin
cd my-plugin
npm install

Теперь у вас есть:

my-plugin/
├── package.json
├── plugin.manifest.json     display name, slug, version, permissions
├── README.md                how to build, test, package, and install it
├── INSTRUCTIONS.md          optional, rendered as a tab in the admin
├── AGENTS.md                notes for AI coding agents
├── .agents/                 a bundled skill for AI coding agents
├── src/
│   └── plugin.js            your code, with a sample handler
└── __tests__/
    └── plugin.test.js       a sample scenario test

npm install также создает node_modules/. Ничего из этого не создается автоматически, но вы можете добавить icon.png (отображается в списке плагинов администратора), каталог public/ (статические файлы, обслуживаемые по адресу /plugins/my-plugin/), и каталог assets/ (файлы, которые хост встраивает для полей манифеста).

Python

Создайте проект с помощью new, передавая slug. uvx запускает скелетонный проект прямо из PyPI без установки чего-либо:

uvx owncast-plugin-py new my-plugin
cd my-plugin
uv tool install owncast-plugin-py      # or:  pip install owncast-plugin-py — for build/test/serve/package

Теперь у вас есть:

my-plugin/
├── plugin.manifest.json     display name, slug, version, permissions
├── README.md                how to build, test, package, and install it
├── INSTRUCTIONS.md          optional, rendered as a tab in the admin
├── AGENTS.md                notes for AI coding agents
├── .agents/                 a bundled skill for AI coding agents
├── src/
│   └── plugin.py            your code, with a sample handler
└── __tests__/
    └── plugin.test.json     a sample scenario test

Манифест имеет как читаемое человеком отображаемое имя ("name": "My Plugin"), так и slug ("slug": "my-plugin"). Отображаемое имя — это то, что администраторы видят в списках. Slug — это канонический идентификатор. Смотрите справочник манифеста для правил.

2. Напишите код

Обработчик реагирует на событие. SDK получает список подписок манифеста из того, какие обработчики вы определяете, поэтому нет ничего другого, за чем нужно следить. Вот пример эхо-бота:

JavaScript

Откройте src/plugin.js:

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

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

Python

Создайте src/plugin.py:

from owncast_plugin import plugin, owncast

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

Смотрите справочник обработчиков, чтобы узнать, с чем вы можете взаимодействовать, и справочник API, чтобы узнать о каждом методе owncast.*.

3. Соберите плагин

Это приводит к созданию my-plugin.ocpkg в корне вашего проекта: один файл, содержащий ваш манифест, скомпилированный плагин и содержимое public/ и assets/. .ocpkg — это формат распространения: этот один файл является всем, что нужно администратору.

JavaScript

npm run package

Python

owncast-plugin-py package

4. Запустите тесты

Каждый сценарий запускает события через реальный рабочий процесс плагина с имитацией побочных эффектов, поэтому успешный тест означает такое же поведение в производстве. Смотрите руководство по тестированию для полной модели данных.

JavaScript

npm test

Python

owncast-plugin-py test

5. (Опционально) протестируйте на локальном сервере разработки

Обслуживает плагин по адресу http://localhost:8080/plugins/my-plugin/ для CURL-эпизодов, открытия статических страниц в браузере или запуска обработчиков событий через вспомогательные конечные точки /_dev/ (например, POST /_dev/chat). Перезапустите сервер разработки при изменении вашего кода.

JavaScript

npm run serve

Python

owncast-plugin-py serve

6. Установите на своем сервере

В администраторе Owncast откройте Плагины в боковом меню и нажмите Загрузить плагин. Выберите файл my-plugin.ocpkg, который создала ваша сборка. Плагин сразу появится в списке. Переключите Включен, чтобы загрузить его.

Или скопируйте my-plugin.ocpkg в директорию data/plugins/ вашего сервера, и на следующем сканировании он будет найден:

scp my-plugin.ocpkg user@your-owncast-server:/path/to/owncast/data/plugins/

Если плагин заявляет разрешения, администратор просматривает их на вкладке Разрешения на странице деталей плагина перед включением. Первое включение фиксирует утвержденный набор разрешений. If you later ship an update that asks for more access, the already-approved version keeps running with its existing permissions while the update waits as pending until the admin re-approves.

Что читать дальше

• Выбор SDK и его страницы JavaScript / Python для полной языковой справки.
• Справочник манифеста для полной схемы для plugin.manifest.json.
• Справочник обработчиков для каждого события, на которое вы можете подписаться.
• API Owncast для каждого метода, который вы можете вызвать из кода плагина.

Когда что-то пойдет не так

• Плагин не появляется в списке администратора. Убедитесь, что .ocpkg находится в data/plugins/, а не просто в plugins/, и имя файла заканчивается на .ocpkg. Страница администрирования Плагины имеет кнопку Обновить, если вы не хотите ждать следующего сканирования.
• Плагин появляется, но не включается. Проверьте детальный просмотр плагина администратора. Столбец Статус показывает error, если манифест недействителен или плагин не смог инициализироваться. Наведите курсор на сообщение или запускайте ваши тесты локально, чтобы поймать ту же проблему до отправки.
• Плагин включается, но ничего не делает. Убедитесь, что вы используете правильное имя обработчика (onChatMessage / on_chat_message, а не onMessage) и что соответствующее разрешение есть в вашем манифесте. A call without its permission never reaches Owncast: the denial is logged on the server and the call returns an empty or zero value, so watch the Owncast logs.
• Плагин отключается автоматически. Фильтр, который вызывает ошибку или зависает пять раз подряд, отключается на остальную часть сессии. Исправьте ошибку, соберите заново, разверните и включите снова.