Packaging & publishing plugins

Форматом распространения плагина является файл .ocpkg: единый бандл, содержащий ваш plugin.manifest.json, код плагина, директории public/ и assets/, а также опционально иконку и файл с инструкциями. Этот один файл — всё, что нужно администратору сервера для установки вашего плагина.

Сборка пакета

JavaScript

npm run package

npm run package only rebuilds when the bundle is missing. After changing source, run npm run build first so the package doesn't ship stale code.

Python

owncast-plugin-py package my-plugin

Native WebAssembly

Use your language toolchain to compile the module, then package it as a ZIP with the canonical plugin.wasm filename. The Native WebAssembly guide includes build commands for Rust, TinyGo, and AssemblyScript.

The resulting \<your-slug>.ocpkg contains the manifest and runnable code. It can also include the plugin's public/ and assets/ directories.

The JavaScript and Python packagers run the built plugin through owncast-plugin-test --load-only before writing the archive. This uses the same install-time load path as a real server, covering register(), manifest and runtime agreement, and permission-gated subscriptions. Native WebAssembly authors run owncast-plugin-test directly before packaging. See Native WebAssembly: Test before installing.

Файл самодостаточен. Делитесь им любым удобным способом:

• Прикрепите его к релизу на GitHub
• Разместите его на собственном сервере
• Передайте его администратору через чат или по электронной почте

Иконка плагина

Поместите icon.png в корень проекта (рядом с plugin.manifest.json), и упаковщик автоматически добавит её в .ocpkg. Админский интерфейс получает её по /api/plugins/\<your-slug>/icon и отображает в списке плагинов и в записи в боковой панели для любого плагина, имеющего страницу администратора.

my-plugin/
├── plugin.manifest.json
├── icon.png              bundled automatically
├── src/
├── public/
└── assets/

Примечания:

• Разрешения не требуются. Хост отдает иконку напрямую. Вам не нужен http.serve.
• Иконка отделена от иконок кнопок действий, которые находятся в public/ (обслуживаются веб-сервером) и ссылаются через поле icon в записи actions[]. См. Интерфейс: Кнопки действий.

Инструкции

Поместите INSTRUCTIONS.md в корень проекта (рядом с plugin.manifest.json), и упаковщик автоматически добавит его в .ocpkg. Админский интерфейс получает его по /api/admin/plugins/\<your-slug>/instructions и отображает как markdown на вкладке Инструкции на странице с подробностями плагина.

my-plugin/
├── plugin.manifest.json
├── INSTRUCTIONS.md          bundled automatically
├── src/
├── public/
└── assets/

Используйте это для шагов настройки, заметок по конфигурации, указания, какие разрешения запрашиваются и почему, а также всего остального, что администратору нужно знать после установки. Плагины без файла не отображают вкладку «Инструкции». Имя файла фиксировано (INSTRUCTIONS.md). Не требуется разрешение http.serve.

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

Что внутри .ocpkg

• plugin.manifest.json
• One code entry: plugin.js, plugin.py, or plugin.wasm
• icon.png, если вы его предоставили
• INSTRUCTIONS.md, если вы его предоставили
• Содержимое вашей директории public/, если она есть (обслуживается по вебу по адресу /plugins/\<slug>/)
• Содержимое директории assets/, если она есть (читается хостом для полей манифеста, в которые встроено содержимое)

The code filename selects the runtime. A native module must be named plugin.wasm inside the archive, regardless of the plugin slug.

Build inputs such as node_modules, package.json, pyproject.toml, Cargo.toml, and uncompiled source do not belong in the package. They produce the code entry that the server runs.

Loose native WebAssembly files

During development, a native module can be installed without creating an .ocpkg. Copy the module and manifest into data/plugins/ with the same basename:

data/plugins/
├── my-plugin.wasm
└── my-plugin.manifest.json

Owncast scans for the .wasm file and reads the matching .manifest.json. The packaged .ocpkg format is still recommended for distribution because it keeps the code, manifest, and optional assets together.

Установка на сервере

В админке Owncast откройте Plugins в боковой панели и нажмите Upload plugin. Выберите ваш .ocpkg, и сервер установит его на месте. Новый плагин сразу появляется в списке.

Если админский интерфейс недоступен (автоматизация, нет доступа к браузеру, скриптовые развертывания), вы также можете положить .ocpkg прямо в директорию data/plugins/ сервера:

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

Сервер периодически сканирует эту директорию. Плагин появится на странице Plugins в админке в течение нескольких секунд.

В любом случае завершите установку в админке:

1. Кликните по плагину в списке, чтобы открыть его подробную страницу.
2. Просмотрите вкладку Permissions. Это точно то, что указано в вашем манифесте.
3. Переключите Enabled, чтобы загрузить плагин. Первое включение также сохраняет одобренный набор разрешений.

Обновление установленного плагина

To ship an update, replace the package file in data/plugins/ directly, or install the new version from the admin's Browse tab if you publish to the directory. The manifest's slug is the identity key: the new contents replace the existing entry with the same slug, whatever the file was called. Чтобы принудительно сразу перезагрузить включённый плагин, нажмите Reload в его строке.

Uploading from the admin's Plugins page only installs a new plugin. An upload whose slug already belongs to an installed plugin is rejected ("uninstall it before uploading another plugin with the same slug"), so uninstall the old one first if the admin upload is your only update path.

Two files in data/plugins/ that declare the same slug are also a conflict. Owncast keeps the first one it finds, ignores the other, and logs which package was skipped.

Что происходит при изменении разрешений

• Вы удалили разрешения. Без уведомлений. Плагин перезагружается с уменьшенным набором.
• Вы добавили разрешения. The old approved version keeps running (it holds only the approved permissions) and the new package waits as pending, with a "needs re-approval" badge in the plugin list. The admin reviews the new permissions in the Permissions tab (new entries are tagged) and clicks Approve to accept the expanded set and load the update.

Эффективные возможности плагина никогда не расширяются без явного согласия администратора, даже при обновлениях.

Повышение версии

Обновляйте version в plugin.manifest.json при каждом выпуске. It's what admins see in the plugin list and what the registry uses to tell releases apart. The host doesn't gate loading on it: update identity is the slug, and the load-time check compares slug and permissions, not version.

Версионирование — для людей. Semver рекомендуется, но не требуется.

Отключение и удаление

• Disable оставляет плагин установленным, но прекращает его загрузку. Выбор администратора сохраняется при перезапусках. Переключите Enabled обратно, чтобы загрузить его снова.
• Uninstall полностью удаляет плагин. На странице Plugins в админке нажмите иконку корзины в строке плагина и подтвердите. (Вы также можете удалить .ocpkg напрямую из data/plugins/, и при следующем сканировании удаление будет зафиксировано.)

Контрольный список распространения

Перед публикацией плагина:

• Манифест декларирует только то, что вы используете. Уберите неиспользуемые разрешения. Чем уже набор запрашиваемых разрешений, тем проще администратору принять решение о доверии.
• description заполнено. Администраторы видят это в списке плагинов и при установке. Одно предложение, описывающее, что делает плагин.
• version соответствует тому, что вы поставляете. Semver является общепринятым.
• README в вашем репозитории объясняет, что он делает, какие разрешения запрашивает и почему, а также что нужно настроить (переменные окружения, настройки на странице администратора и т. д.).
• Тесты проходят. Команда тестирования в вашем SDK должна выполняться успешно.
• Иконка включена, если она у вас есть.
• INSTRUCTIONS.md должен содержать всё, что администратору нужно знать после установки: шаги настройки, заметки по конфигурации, почему запрашивается каждое разрешение. Плагины с неочевидным поведением или требующейся конфигурацией должны включать такой файл. Тривиальные плагины (например, обработчик чата "hello-world") не нуждаются в нём.

Публикация в каталоге

Размещение вашего плагина в публичном каталоге на owncast.directory не обязательно. Файл .ocpkg самодостаточен, поэтому вы всегда можете передать его администратору напрямую. Каталог делает ваш плагин обнаруживаемым и даёт администраторам установку и обновления в один клик.

Пара полей манифеста формируют вашу запись, поэтому заполните их в первую очередь: name (отображаемое имя), version (увеличивайте при каждом обновлении), slug (ваш постоянный идентификатор, см. Манифест), description (однострочное резюме на вашей карточке), permissions (держите их минимальными, администраторы их проверяют), и опциональный icon.png.

Вход

Каталог использует вход без пароля через магическую ссылку. Перейдите на owncast.directory/plugins/login, введите свою почту и нажмите ссылку в письме. Ваша почта — это ваша идентичность автора, привязанная к плагинам, которыми вы владеете. На странице аккаунта вы можете задать необязательное отображаемое имя, которое будет появляться как автор в ваших записях.

Отправить

Перейдите на owncast.directory/plugins/submit и загрузите ваш .ocpkg. Каталог считывает ваш манифест, валидирует пакет и публикует версию. Подача осуществляется через веб-сайт, в настоящее время нет шага публикации через командную строку. Форма также принимает несколько дополнительных необязательных данных: превью-изображение (скриншот, PNG или JPEG до 5 МБ), ссылку на домашнюю страницу, теги для поиска и краткое описание, которое заменяет описание из манифеста.

Право собственности и обновления

• Первый, кто отправит, становится владельцем slug. Когда вы впервые публикуете slug, он привязывается к вашему аккаунту, и никто другой не может публиковать под ним. Отправка для slug, принадлежащего другому автору, отклоняется.
• Каждая версия публикуется единожды. Чтобы выпустить обновление, увеличьте version в манифесте, пересоберите пакет и отправьте снова.
• Управляйте своими плагинами на owncast.directory/plugins/account, где вы можете увидеть всё, что опубликовали, и удалить запись.

Что видят операторы

В представлении Browse каталога ваш плагин показывает своё имя, автора, описание, иконку, последнюю версию и превью, если вы загрузили его. Когда администратор устанавливает его, Owncast показывает запрашиваемые вашим манифестом разрешения, отображает ваш INSTRUCTIONS.md и перечисляет любые зарегистрированные вами команды чата. Эти метаданные — то, что оператор использует, чтобы решить, доверять ли и включать ваш плагин, поэтому формулируйте их с учётом оператора.

Дальше

• См. Справочник по манифесту для полного списка полей манифеста.
• См. Разрешения для модели доверия и полного списка разрешений.
• Example plugins: JavaScript · Python.