Плагины чата

Если вы хотите создать плагин, который будет взаимодействовать в чате, реагировать на зрителей или модерировать сообщения, это страница, с которой стоит начать. Примеры кода представлены на обоих поддерживаемых языках. Сначала настройте вашу цепочку инструментов на странице SDK для JavaScript или Python.

Owncast предоставляет функционал чата на трех уровнях:

Обработчики событий чата, чтобы ваш плагин мог реагировать, когда люди разговаривают, присоединяются, выходят или меняют своё имя.
API чата и пользователей, чтобы ваш плагин мог отправлять сообщения, проверять состояние чата и модерировать пользователей.
Фильтры чата, чтобы ваш плагин мог переписывать или удалять сообщения до того, как их увидят зрители.

Что вы можете создать

Чат-боты, которые отвечают на команды или ключевые слова.
Приветственные боты, которые приветствуют людей, когда они присоединяются.
Боты-напоминалисты, которые отправляют сообщения, когда начинается трансляция.
Боты обратного отсчета и таймеры, работающие на основе owncast.timer или обработчика тиков.
Помощники модерации, которые скрывают сообщения, отключают клиентов или отключают агрессивных пользователей.
Фильтры, которые переписывают, переводят или удаляют сообщения перед их трансляцией.

Бот-ответчик - это всего лишь один обработчик:

JavaScript
Python

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

module.exports = definePlugin({
  onChatMessage(msg) {
    const name = msg.user?.displayName ?? "someone";
    owncast.chat.send(`${name} said: ${msg.body}`);
  },
});

from owncast_plugin import plugin, owncast

@plugin.on_chat_message
def echo(msg):
    name = msg.user.display_name if msg.user else "someone"
    owncast.chat.send(f"{name} said: {msg.body}")

Реакция на чат

Определите onChatMessage (@plugin.on_chat_message в Python), чтобы видеть каждое сообщение после проверки фильтров и перед его трансляцией зрителям:

JavaScript
Python

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

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

Поля, к которым вы чаще всего обращаетесь, это msg.body (сырой текст), msg.user (идентичность отправителя, с user.id для состояния по каждому пользователю и user.scopes для проверки модератора), и msg.timestamp (детерминированный, поэтому предпочитайте его часам при сравнении прошедшего времени или утверждении в тестах). Не привязывайте состояние или разрешения к отображаемым именам.

Для полного содержимого сообщений и каждого другого события, на которое может подписаться чат-плагин (вход и выход пользователей, переименование, модерация и т. д.), смотрите Справочник событий.

Отправка сообщений в чате

`owncast.chat.send`

Отправить сообщение в чате. Отправляется от имени бота вашего плагина. Принимает обычный текст, а не разметку: пользовательский интерфейс чата экранирует его при отображении, поэтому такие символы, как \<, &, и " отображаются как текст, а не HTML.

JavaScript
Python

owncast.chat.send("hello chat");
owncast.chat.sendAction("waves");        // /me-style action message
owncast.chat.system("Stream starting in 5 minutes");

owncast.chat.send("hello chat")
owncast.chat.send_action("waves")        # /me-style action message
owncast.chat.system("Stream starting in 5 minutes")

Требует chat.send.

`owncast.chat.sendAction`

Отправить сообщение в стиле действия (/me): sendAction на JavaScript, send_action на Python. Как и send, принимает обычный текст и экранирован HTML пользовательским интерфейсом чата при отображении.

Требует chat.send.

`owncast.chat.system`

Отправить сообщение серверного объявления. Идентичность бота не прикреплена. Содержимое отображается встроенным HTML. Используйте это для коротких уведомлений, атрибутированных сервером, таких как "Трансляция начнется через 5 минут". Считайте содержимое ненадежным HTML-кодом: не интерполируйте контролируемый зрителем вход, не экранируя его.

Требует chat.send.

Идентичность чата

У каждого плагина есть ровно одна идентичность чата: бот, который Owncast предоставляет при установке вашего плагина. Его отображаемое имя — это bot.displayName вашего манифеста, если оно установлено, иначе name.

Оба send и sendAction отправляют от этого имени через нормальную цепочку чата Owncast, включая фильтры, ограничения по частоте и модерацию. Плагины не могут отправлять сообщения под произвольными именами или выдавать себя за реальных пользователей.

Пользователь бота определяется по slug плагина, поэтому идентичность сохраняется даже после редактирования манефеста в части name или bot.displayName. Если вам нужно несколько персонажей чата, доставьте несколько плагинов.

Чтение состояния чата

`owncast.chat.history`

Вернуть самые последние сообщения чата (необязательное ограничение по умолчанию — 50). Каждая запись имеет форму { id, user?, clientId?, body, timestamp }.

Требует chat.history.

`owncast.chat.clients`

Return the list of currently connected chat clients: { id, userId?, displayName?, connectedAt?, userAgent?, ipAddress?, messageCount? }. id - это идентификатор клиента на соединение, используемый owncast.chat.kick.

Требует chat.history.

`owncast.server.emotes`

Читать индивидуальные чат-емодзи сервера ({ имя, url }), когда ваш бот хочет ссылаться на или воспроизводить каталог емодзи.

Требует server.read.

`owncast.users.list` и `owncast.users.get`

Читать список пользователей чата или одну запись пользователя по id.

Требует users.read.

API модерации

Это deleteMessage / kick / sendTo / replyTo на JavaScript и delete_message / kick / send_to / reply_to на Python.

`owncast.chat.deleteMessage`

Скрыть сообщение чата от зрителей по идентификатору сообщения.

Требует chat.moderate.

`owncast.chat.kick`

Отключить клиента чата по идентификатору клиента.

Требует chat.moderate.

`owncast.chat.sendTo`

Отправить личное сообщение одному подключенному клиенту по идентификатору клиента.

Требует chat.send.

`owncast.chat.replyTo`

Отправить ответ обратно тому, кто отправил сообщение в чате. Вы можете передать либо полный объект сообщения из обработчика чат-сообщений / фильтра, либо только идентификатор клиента, если это все, что у вас есть. Возвращает ложное значение, когда соединение отправителя больше не известно, что позволяет вам спокойно вернуться к публичному сообщению.

JavaScript
Python

module.exports = definePlugin({
  onChatMessage(msg) {
    if (!owncast.chat.replyTo(msg, "psst: got your message")) {
      owncast.chat.send("got your message"); // sender already disconnected
    }
  },
});

@plugin.on_chat_message
def whisper(msg):
    if not owncast.chat.reply_to(msg, "psst: got your message"):
        owncast.chat.send("got your message")  # sender already disconnected

Требует chat.send.

Команды

Для команд чата объявите таблицу команд с псевдонимами, периодами ожидания, контролем модераторов и автоматическими списками !help. Смотрите Команды чата.

Модерация пользователей

`owncast.users.setEnabled`

Включить или отключить пользователя чата по идентификатору, с необязательной причиной: setEnabled на JavaScript, set_enabled на Python.

Требует users.moderate.

`owncast.users.banIP`

Запретить IP-адрес на вход в чат: banIP на JavaScript, ban_ip на Python.

Требует users.moderate.

Фильтры чата

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

`filterChatMessage`

Принимает ту же форму ChatMessage, что и обработчик сообщений чата, и возвращает один из трех результатов, построенных с помощью помощника filter:

pass: пропустить сообщение без изменений.
modify: заменить его новым содержимым.
drop: удалить его (с причиной). Цепочка останавливается здесь.

JavaScript
Python

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

module.exports = definePlugin({
  filterChatMessage(msg) {
    if (msg.body.includes("spam")) return filter.drop("spam keyword");
    if (msg.body.includes("damn")) {
      return filter.modify({ ...msg, body: msg.body.replace("damn", "****") });
    }
    return filter.pass();
  },
});

from owncast_plugin import plugin, filter

@plugin.filter_chat_message
def clean(msg):
    if "spam" in msg.body:
        return filter.drop("spam keyword")
    if "damn" in msg.body:
        return filter.modify({**msg.raw, "body": msg.body.replace("damn", "****")})
    return filter.pass_()  # trailing underscore: pass is a keyword

Требуется разрешение chat.filter. Хост отклоняет загрузку, если плагин определяет обработчик фильтра без объявления этого разрешения.

Приоритет фильтра (необязательный)

Меньшие номера выполняются первыми. По умолчанию 100. Set it with filterPriority (JavaScript) on the plugin definition, or by calling plugin.set_filter_priority(priority) (Python).

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

Безопасность фильтров

Ошибки рассматриваются как пропуск. Фильтр, который бросает исключение, никогда не блокирует чат.
Фильтры имеют временные ограничения на выполнение в 50 мс. Медленный фильтр отменяется и рассматривается как пропуск.
После 5 последовательных ошибок (ошибки или таймауты) плагин автоматически отключается на остальную часть сеанса. Успешный вызов фильтра сбрасывает счетчик.

Ограничения, установленные хостом, которые важны для плагинов чата

Несколько лимитов хоста заслуживают внимания при проектировании:

время выполнения фильтра: 50 мс на сообщение
время выполнения обработчика событий (сообщение чата, пользователь присоединился и т. д.): 500 мс на вызов
жесткий лимит на вызов: 10 с
размер вывода фильтра: 1 MiB
ожидающие таймеры: 64 одновременно
диапазон задержек таймера: 100 мс до 24 ч

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

Разрешения, которые вам обычно понадобятся

chat.send: отправлять сообщения в чате и личные ответы.
chat.history: читать последние сообщения в чате и подключенных клиентов.
chat.moderate: скрывать сообщения и отключать клиентов.
chat.filter: переписывать или удалять сообщения перед трансляцией.
users.read: проверять записи пользователей.
users.moderate: отключать пользователей чата или блокировать IP-адреса.

Смотрите Разрешения для полной модели безопасности.

Примеры чат-плагинов

SDK плагина поставляется с небольшими примерами, ориентированными на чат, которые тесно соответствуют шаблонам на этой странице (каждый имеет как версию на JavaScript, так и версию на Python):

echo-bot: самый маленький возможный ответный бот, использующий обработчик чат-сообщений + owncast.chat.send.
chat-logger: регистрирует каждое чат-сообщение без ответа.
stream-tracker: объединяет чат-команды, обработчики жизненного цикла пользователей чата и объявления действий.
profanity-filter: переписывает сообщения, не удаляя их.
slow-mode: удаляет сообщения, используя msg.timestamp для ограничения скорости.
engagement-bot: модерация путем удаления сообщения.
timer-bot: боты-напоминания/обратного отсчета, управляемые из чата, с использованием таймеров и обработчика тиков.

Просмотрите их на examples/js · examples/python.

Где это вписывается в другие документы плагинов

Выбор SDK и страницы JavaScript / Python охватывают настройку, CLI и синтаксис, специфичные для языка.
Чат-команды охватывает таблицы команд, автоматический !help и смешивание команд с вашими собственными обработчиками чата.
Обработчики событий — это полный справочник обработчиков для всех событий плагина.
API Owncast — это полный справочник API для всех методов owncast.*.
Справочник манифеста охватывает разрешения, поля идентичности бота и каждое свойство манифеста.
Участие в пользовательском интерфейсе охватывает пользовательский интерфейс со стороны зрителя, наложения, кнопки, скрипты и стили, если ваш чат-плагин также включает frontend компоненты.

Если вы начинаете с нуля, сначала прочитайте Быстрый старт, а затем вернитесь сюда.

Improve this page

See something missing or incorrect? Edit this page and improve the documentation for everyone.

Contributors to this documentation

Gabe Kangas

Что вы можете создать​

Реакция на чат​

Отправка сообщений в чате​

owncast.chat.send​

owncast.chat.sendAction​

owncast.chat.system​

Идентичность чата​

Чтение состояния чата​

owncast.chat.history​

owncast.chat.clients​

owncast.server.emotes​

owncast.users.list и owncast.users.get​

API модерации​

owncast.chat.deleteMessage​

owncast.chat.kick​

owncast.chat.sendTo​

owncast.chat.replyTo​

Команды​

Модерация пользователей​

owncast.users.setEnabled​

owncast.users.banIP​

Фильтры чата​

filterChatMessage​

Приоритет фильтра (необязательный)​

Безопасность фильтров​

Ограничения, установленные хостом, которые важны для плагинов чата​

Разрешения, которые вам обычно понадобятся​

Примеры чат-плагинов​

Где это вписывается в другие документы плагинов​

Improve this page

Что вы можете создать

Реакция на чат

Отправка сообщений в чате

`owncast.chat.send`

`owncast.chat.sendAction`

`owncast.chat.system`

Идентичность чата

Чтение состояния чата

`owncast.chat.history`

`owncast.chat.clients`

`owncast.server.emotes`

`owncast.users.list` и `owncast.users.get`

API модерации

`owncast.chat.deleteMessage`

`owncast.chat.kick`

`owncast.chat.sendTo`

`owncast.chat.replyTo`

Команды

Модерация пользователей

`owncast.users.setEnabled`

`owncast.users.banIP`

Фильтры чата

`filterChatMessage`

Приоритет фильтра (необязательный)

Безопасность фильтров

Ограничения, установленные хостом, которые важны для плагинов чата

Разрешения, которые вам обычно понадобятся

Примеры чат-плагинов

Где это вписывается в другие документы плагинов