/::docs::about

   ____ _            _ _
  / ___| | __ _ _ __(_) |_ _   _
 | |   | |/ _` | '__| | __| | | |
 | |___| | (_| | |  | | |_| |_| |
  \____|_|\__,_|_|  |_|\__|\__, |
                           |___/

clarity.sys — what it is

Clarity is a chat-bot for Twitch and Kick rolled into one. A single bot account (shizick666 on Twitch, sh1zick on Kick) works on any channel where it is moderator.

Clarity — это чат-бот для Twitch и Kick в одном лице. Один аккаунт бота (shizick666 на Twitch, sh1zick на Kick) умеет работать на любом канале где он назначен модератором.

what it can doчто умеет

Faceit — live elo, stats for today, last match, lobby with live score
Stream — status, uptime, change title/category by command
Music recognition — !track identifies the song playing (Shazam-like via AudD)
Economy — coins for activity, transfers, leaderboards, daily bonuses
Trivia / mini-games — quizzes with auto-start, in-chat mini-games
Giveaways / lottery — raffles through the bot
Timers — recurring chat messages
Custom commands with templating ($(random), $(choose), $(urlfetch))
Auto-moderation — link and ban-word filters with timeout
Faceit — реальное эло, статистика за сегодня, последний матч, лобби с live score
Stream — статус, аптайм, изменение названия/категории через команду
Music recognition — !трек распознаёт играющий трек (Shazam-like через AudD)
Economy — монеты за активность, переводы, топ, ежедневные бонусы
Trivia / mini-games — викторины с автозапуском, мини-игры в чате
Giveaways / lottery — розыгрыши через бота
Timers — периодические сообщения в чат
Custom commands с шаблонизатором ($(random), $(choose), $(urlfetch))
Auto-moderation — фильтр ссылок и банвордов с таймаутом

tech stackтех-стек

runtime  :: python 3.12  + asyncio
web      :: quart (async flask)
twitch   :: twitchio (irc) + helix api
kick     :: kick public api v1 + webhooks
deploy   :: vps (ubuntu) :: systemd :: nginx

/::docs::connect bot

connect bot to your channel

1. open the dashboard1. зайти в дашборд

Go to claritysync.ru/login. Pick a provider — type 1 for Twitch or 2 for Kick. Confirm in OAuth — after the redirect you'll land on the dashboard.

Открой claritysync.ru/login. На странице выбери провайдер — введи 1 для twitch или 2 для kick. Подтверди в OAuth — после редиректа окажешься в дашборде.

2. make the bot a mod2. сделать бота модератором

Many features (timeouts, message deletion, Helix sending without cooldowns) require the bot to be a moderator of your channel.

Многие фичи (тайм-ауты, удаление сообщений, отправка через Helix без кулдаунов) требуют чтобы бот был модератором канала.

# in your own chatв чате своего канала
/mod shizick666     # for twitchдля twitch
/mod sh1zick        # for kickдля kick

3. connect the bot3. подключить бота

On the main dashboard click bot: offline → online. The bot will join your chat and start working.

В дашборде на главной нажми кнопку bot: offline → online. Бот зайдёт в твой чат и начнёт работать.

If you're an admin — you can switch between all channels where the bot is added via the dropdown at the top.

Если ты админ — можешь в выпадашке сверху переключаться между всеми каналами куда добавлен бот.

4. configure4. настроить

Open the settings tab:

Открой вкладку settings:

faceit nickname — for !elo, !today, !lobby
moderation — enable auto link/banword filter
economy — enable coins
trivia autostart — auto rounds every N minutes
faceit nickname — для !elo, !today, !lobby
moderation — включить авто-фильтр ссылок/банвордов
economy — включить монеты
trivia autostart — авто-раунды каждые N минут

/::docs::dashboard

dashboard tour

top bar

>_ — logo, link to main
target dropdown (admin) — switch between channels
lang / logout — language toggle and sign out
>_ — лого, ссылка на главную
выпадашка target (admin) — переключение между каналами
lang / logout — переключение языка и выход

tabs (dock at the bottom)tabs (dock внизу)

dashboard — embedded player + chat + quick actions
streamers (admin) — all channels with bot status, add/remove
modules — custom commands, faceit, economy, moderation
giveaway — raffle controls
timers — periodic messages
settings — all toggles and fields
dashboard — embedded player + чат + быстрые действия
streamers (admin) — список всех каналов с бот-статусом, добавление/удаление
modules — кастомные команды, faceit, экономика, модерация
giveaway — управление розыгрышем
timers — периодические сообщения
settings — все тоглы и поля настройки

status bar (bottom)status bar (снизу)

clarity@dashboard | target | mode | bot:live | up:⠋ 14m | last:31.05 22:14 | tip: ctrl+k

/::docs::shell & cmd+k

shell / cmd+k palette

command palette

Press Ctrl+K (or Cmd+K on Mac) anywhere — opens fuzzy-search over actions.

Нажми Ctrl+K (или Cmd+K на Mac) откуда угодно — откроется fuzzy-поиск по действиям.

Type to filter (e.g. str finds go: streamers). ↑↓ to navigate, Enter to execute, Esc to close.

Печатай — фильтруется список (например str найдёт go: streamers). ↑↓ навигация, Enter выполнить, Esc закрыть.

shell mode

In the palette type : — switches to shell mode. Available commands:

В палитре напечатай : — переходишь в режим shell. Доступны команды:

:help                    list shell commands
:whoami                  show current user / target / mode
:go <view>               jump to view (dashboard, modules, ...)
:bot on | off            toggle bot for current target
:lang                    toggle language
:target <name>           switch target channel (admin)
:cmd add !trig <text>    add custom command
:cmd del !trig           remove custom command
:streamer add <login>    whitelist new streamer (admin)
:streamer rm <login>     remove streamer (admin)
:logout / :reload / :clear

login shell (on the login page)login shell (на странице логина)

A working interactive shell on /login. You type:

На /login рабочий interactive shell. Вводишь:

1 or twitch — auth via twitch
2 or kick — auth via kick
about — open the about modal
help, whoami, clear, ls — standard shell set
1 или twitch — auth via twitch
2 или kick — auth via kick
about — открыть about-модалку
help, whoami, clear, ls — стандартный shell-набор

As soon as you type — autocomplete popup appears. Tab inserts a command, ↑↓ navigates history.

Когда напечатаешь любой символ — popup с автокомплитом. Tab вставляет команду, ↑↓ навигация по истории.

/::docs::commands::faceit

metrics.faceit // faceit stats

Requires a faceit nickname in channel settings. Supports CS2/CS:GO.

Требуют faceit ник в настройках канала. Поддержка CS2/CS:GO.

!elo !ело

current elo and smart-elo (with today's delta)текущее эло и smart-эло (с учётом дельты за сегодня)

!today !сегодня

today's stats: W/L, ± elo, starting eloстатистика за сегодня: W/L, +/- эло, стартовое эло

!last !последний

last match result (map, score, ±elo)результат последнего матча (карта, счёт, ±эло)

!lobby !лобби

live status of current match: map, score, time, avg team elolive-статус текущего матча: карта, счёт, время, средний эло команд

!faceit

link to faceit profileссылка на профиль faceit

how to set upкак настроить

Modules → faceit → enter your faceit nickname → save. Bot pulls data via official Faceit API + unofficial endpoints for lobby.

Modules → faceit → введи свой ник на faceit → сохрани. Бот тянет данные через официальный Faceit API + неофициальные эндпоинты для лобби.

/::docs::commands::stream

helix.controller // stream info + control

!stream !стрим !статистика

status: category, viewers, uptime, today's messagesстатус: категория, зрители, аптайм, сегодняшние сообщения

!title <text>

change stream titleизменить название стрима [mod]

!game <category>

change categoryизменить категорию [mod]

!cs / !cs2 / !кс / !кс2

quick switch to Counter-Strikeбыстрая смена на Counter-Strike [mod]

!jc / !афк / !общение

quick switch to Just Chattingбыстрая смена на Just Chatting [mod]

!dota / !дота

quick switch to Dota 2быстрая смена на Dota 2 [mod]

To change title/category the streamer must be logged into the dashboard (we need their user-token).

Для смены title/category нужно чтобы стример был залогинен в дашборд (нужен его user-token).

/::docs::commands::track

audio.fingerprint // shazam-like track recognition

Shazam-like: bot listens to stream audio and identifies the playing track.

Shazam-like: бот слушает аудио стрима и определяет играющий трек.

!track !трек !song !песня !music !shazam

identify the music playing right nowраспознать музыку играющую сейчас

how it worksкак работает

Bot fetches HLS link to the stream via yt-dlp -g
ffmpeg extracts 12 seconds of audio
File is sent to AudD API for recognition
Result is cached for 90 seconds — repeat !track from viewers doesn't hit the API unnecessarily
Бот берёт HLS-ссылку на стрим через yt-dlp -g
ffmpeg вытаскивает 12 секунд аудио
Файл отправляется в AudD API для распознавания
Результат кэшируется на 90 секунд — повторные !трек от зрителей не дёргают API лишний раз

possible responsesвозможные ответы

🎵 @user now playingсейчас играет: Artist — Title 🔗 https://song.link/...
🤷 @user No music detected (or track unknown).Музыки не слышно (или трек неизвестен).
🤷 @user Stream is offline.Стрим оффлайн.

/::docs::commands::economy

coin.ledger // economy: coins, balance, transfers

Channel virtual currency (coins/tugriks). Viewers earn by being active in chat.

Виртуальная валюта канала (монеты/тугрики). Зрители получают за активность в чате.

!balance !баланс

my balanceмой баланс

!me !я

my stats: messages, days in chat, rankмоя статистика: сообщения, дни в чате, ранг

!pay @user amount !перевод

transfer coins to another viewerперевести монеты другому зрителю

!rich !богачи !top

top-10 by balanceтоп-10 по балансу

!top !топ

top-10 by message countтоп-10 по количеству сообщений

how to set upкак настроить

Modules → economy → enable. You can configure rates (coins per message, sub bonus, etc.).

Modules → economy → включить. Можно настроить ставки (сколько монет за сообщение, бонус за сабскрайб и т.д.).

/::docs::commands::trivia

q.engine // quiz dispatcher

!trivia

start roundначать раунд [mod]

!trivia stop

stop roundостановить раунд [mod]

Bot asks a question — viewers write answers in chat. First correct one gets coins.

Бот задаёт вопрос — зрители пишут ответы в чат. Первый правильный получает монеты.

autostartавтозапуск

In settings you can enable trivia autostart — bot launches rounds every N minutes (e.g. 15-30 min).

В settings можно включить trivia autostart — бот сам запускает раунды каждые N минут (например, 15-30 мин).

/::docs::commands::mini-games

entropy.lab // stochastic mini-games

Games tied to economy — stake coins, win or lose.

Игры с экономикой — ставишь монеты, выигрываешь или теряешь.

!dice <stake> !кости

dice roll — higher rolls wins, you vs botбросок костей — выпадет больше у тебя или у бота

!duel @user <stake> !дуэль

challenge another viewer to a duelвызвать другого зрителя на дуэль

!roulette <stake> <red|black|green> !рулетка

roulette with colorрусская рулетка с цветом

Full set of games and cooldowns — dashboard Modules → mini-games.

Полный набор игр и кулдауны — в дашборде Modules → mini-games.

/::docs::commands::giveaway

raffle.daemon + lottery.sampler // prize draws

giveaway

Keyword-based raffle. Streamer starts, bot collects participants, then picks a winner.

Розыгрыш с ключевым словом. Стример запускает, бот собирает участников, потом выбирает победителя.

+ (or your own keywordили своё слово)

enter the active raffleучаствовать в активном розыгрыше

Controls — dashboard giveaway tab:

Управление — в дашборде, вкладка giveaway:

set a keyword (e.g. +)
click start — bot announces in chat
real-time counter shows participants
click pick winner — bot picks a random one and writes in chat
задаёшь keyword (например +)
жмёшь start — бот объявляет в чат
счётчик в реальном времени показывает участников
жмёшь pick winner — бот выбирает случайного и пишет в чат

lottery

!lottery <stake> !лотерея

enter lotteryвойти в лотерею

!lottery start !лотерея старт

start roundначать раунд [mod]

/::docs::commands::timers

cron // periodic chat messages

Bot writes a given message to chat every N minutes. Useful for reminders (social media links, rules, etc.).

Бот раз в N минут пишет в чат заданное сообщение. Полезно для напоминаний (ссылки на соц-сети, правила, и т.д.).

how to set upкак настроить

Tab timers in the dashboard. Each timer has:

Вкладка timers в дашборде. Каждый таймер имеет:

interval — every how many minutes to send
message — what to send
you can create any number of timers per channel
interval — каждые сколько минут писать
message — что писать
можно создать сколько угодно таймеров на канал

The templating engine is supported inside timer messages.

Поддерживается шаблонизатор внутри сообщения таймера.

/::docs::commands::moderation

guard.engine // auto-moderation

Bot auto-timeouts viewers for violations. Requires mod rights on the channel.

Бот автоматически тайм-аутит зрителей за нарушения. Требует mod-права на канале.

link filterфильтр ссылок

When enabled — viewers without rights can't post links. Streamer, mods, VIPs and whitelisted users — can.

Когда включён — зрители без прав не могут писать ссылки. Стример, мод, вип, и whitelisted-пользователи — могут.

banword filterфильтр банвордов

List of forbidden words is configured in the dashboard. On trigger — timeout.

Список запрещённых слов настраивается в дашборде. При срабатывании — таймаут.

immunityиммунитет

Bot doesn't try to timeout mods and the streamer (Twitch would refuse anyway). These accounts get a joke reply in chat instead.

Бот не пытается тайм-аутить модов и стримера (Twitch всё равно бы отказал). Эти аккаунты получают шуточный ответ в чат вместо тайм-аута.

settingsнастройки

timeout duration — seconds
timeout message — what bot writes in chat
whitelist — who is allowed to post links
длительность таймаута — секунд
сообщение при таймауте — что бот пишет в чат
whitelist — кому можно писать ссылки

/::docs::commands::custom

directive.set // custom commands

Your own !commands with predefined responses.

Свои !команды с заданным ответом.

via chatчерез чат (mod)

!addcmd !trigger <response>

add commandдобавить команду

!editcmd !trigger <new response>

editизменить

!delcmd !trigger

deleteудалить

via dashboardчерез дашборд

Tab modules → custom commands. Add, edit, delete — changes apply instantly without bot restart.

Вкладка modules → раздел custom commands. Можно добавлять, редактировать, удалять — изменения применяются сразу без рестарта бота.

examplesпримеры

$ !addcmd !discord https://discord.gg/xxx
[ok] command !discord addedкоманда !discord добавлена

$ !discord
bot: https://discord.gg/xxx

/::docs::commands::templating

templating // dynamic substitutions

Inside a custom command response (and timer message) you can use templates. They are substituted on the fly.

Внутри ответа кастомной команды (и timer-сообщения) можно использовать шаблоны. Они подставляются на лету.

$(user)

name of who called the commandимя того кто вызвал команду

$(channel)

channel nameимя канала

$(touser)

name of who was mentioned (after @)имя того кого упомянули в команде (после @ )

$(random N M)

random number from N to Mслучайное число от N до M

$(choose a|b|c)

random choice from list separated by |случайный вариант из списка через |

$(urlfetch URL)

fetch text from URL and insert (for API integration)скачать текст по URL и вставить (для API)

examplesпримеры

$ !addcmd !hug $(user) hugs $(touser) 🤗
user:  !hug @viewer
bot:   user hugs viewer 🤗

$ !addcmd !dice rolled $(random 1 6) 🎲
bot:   rolled 4 🎲

$ !addcmd !shoot $(choose hit|missed|critical hit)
bot:   critical hit

$ !addcmd !hug $(user) обнимает $(touser) 🤗
user:  !hug @viewer
bot:   user обнимает viewer 🤗

$ !addcmd !dice выпало $(random 1 6) 🎲
bot:   выпало 4 🎲

$ !addcmd !shoot $(choose попал|промахнулся|критический хит)
bot:   критический хит

/::docs::studio tools::overlay.broadcast

overlay.broadcast // chat-overlays for OBS Browser Source

Ready-made HTML chat overlays for embedding in OBS. Connected as a Browser Source — separate layer on top of the scene. Support role-based colors (broadcaster / mod / vip / sub), badges, 7TV/BTTV/FFZ emotes, avatars and smooth fade-out of old messages.

Готовые HTML-оверлеи чата для встройки в OBS. Подключаются как Browser Source — отдельным слоем поверх сцены. Поддерживают цвета по ролям (broadcaster / mod / vip / sub), бейджи, 7TV/BTTV/FFZ эмодзи, аватарки и плавный fade-out старых сообщений.

how to connect in OBSкак подключить в OBS

in the dashboard open the overlays tab
pick a style you like, copy its URL
in OBS: + → Browser → URL, paste the link, width 420, height 720 (or your size)
checkbox Shutdown source when not visible — recommended (saves CPU)
в дашборде открыть вкладку overlays
выбрать понравившийся стиль из списка, скопировать его URL
в OBS: + → Browser → URL, вставить ссылку, ширина 420, высота 720 (или под себя)
галочка Shutdown source when not visible — рекомендуется (экономит CPU)

stylesстили

7 ready-made designs included — for different stream aesthetics:

В комплекте 7 готовых оформлений — для разной эстетики стрима:

cards — colored plates with avatar inside (name above, text below). The most "modern".
terminal — monochrome console style (different colors per role). Good for hacker/IT streams.
glass — semi-transparent cards with blur effect. Minimalism.
neon — neon glow and gradients. For bright scenes.
minimal — no frames, just colored nicks and text. Doesn't distract.
retro — pixel font + thick shadows. Vintage/retro games.
bubbles — big bubbles with avatar on the left (name+text in one line).
cards — цветные плашки с аватаркой внутри (имя сверху, текст ниже). Самый «современный».
terminal — монохромный консольный стиль (под клиент-роли разные цвета). Хорош для хакерских/IT-стримов.
glass — полупрозрачные карточки с blur-эффектом. Минимализм.
neon — неоновое свечение и градиенты. Под яркие сцены.
minimal — без рамок, только цветные ники и текст. Не отвлекает.
retro — пиксельный шрифт + жирные тени. Винтаж/ретро-игры.
bubbles — крупные пузыри с аватарой слева (имя+текст в одной строке).

URL parametersпараметры в URL

The dashboard has toggles that change URL parameters automatically. Full format:

В дашборде есть переключатели — они меняют параметры URL автоматически. Полный формат:

https://<host>/overlay/chat/<channel>?style=cards&fade=15&fadeAnim=slide-up&max=30

style — one of the 7 above
fade — after how many seconds a message disappears (0 = keep)
fadeAnim — fade-out animation: blur, slide-up, slide-left, scale, dissolve, glitch
max — how many messages to keep on screen at once
style — один из 7 выше
fade — через сколько секунд сообщение исчезает (0 = не убирать)
fadeAnim — анимация исчезновения: blur, slide-up, slide-left, scale, dissolve, glitch
max — сколько максимум сообщений держать одновременно

emotes (7TV/BTTV/FFZ)эмодзи (7TV/BTTV/FFZ)

Third-party emotes are loaded automatically — both global packs and your channel-specific emotes. To add memes (KEKW, OMEGALUL, Pog, etc.) — go to 7tv.app, log in via Twitch, find the emote and click Add to Active Set. Backend picks them up in ~5 minutes.

Третьесторонние эмодзи подгружаются автоматически — и глобальные пакеты, и эмодзи конкретно твоего канала. Чтобы добавить мемные (KEKW, OMEGALUL, Pog и т.д.) — заходишь на 7tv.app, логинишься через Twitch, ищешь нужный и жмёшь Add to Active Set. Бэкенд подцепит за ~5 минут.

badgesбейджи

Real Twitch badges are used (mods get a green sword, VIP — a diamond, subs — a star, etc.). Loaded via Helix API on the first chat message.

Используются настоящие бейджи Twitch (моды получают зелёный меч, VIP — алмаз, сабы — звезду и т.д.). Подгружаются через Helix API при первом сообщении в чате.

demo modeдемо-режим

If your channel is still empty — the preview runs a demo chat with fake messages: see how the style will look in real conditions. Demo emotes are global only (KEKW and similar shared emotes won't show up until you add them yourself).

Если в дашборде канал ещё пустой — в превью идёт демо-чат с фейковыми сообщениями: посмотреть как стиль будет выглядеть в реальной обстановке. Эмодзи в демо — только глобальные (KEKW и подобные shared-эмодзи не покажутся пока ты их не добавишь себе).

known issuesизвестное

Old OBS (built-in Chromium) may "sharply" cut the top of the chat instead of smooth fade. We have a JS-fallback that renders fade manually — should work. If it doesn't — update OBS to 28+.

Старая версия OBS (Chromium встроенный) может «резко» обрезать верх чата вместо плавного fade. У нас есть JS-fallback который рендерит fade вручную — должно работать. Если не работает — обнови OBS до 28+.

/::docs::studio tools::metrics.aggregator

metrics.aggregator // chat statistics dashboard

Channel chat analytics — how many messages, who chats the most, which commands are called more often. analytics tab in the dashboard. Only the channel owner sees it.

Аналитика чата канала — сколько сообщений, кто пишет больше всех, какие команды звучат чаще. Вкладка analytics в дашборде. Видит только владелец канала.

what it showsчто показывает

KPI cards — messages today / unique chatters today / messages this week / month
messages/hour chart — line chart of chat activity for 24h / 7d / 30d (toggle)
top chatters — top-10 most active viewers for day / week / month with progress bars
KPI-карточки — сообщений сегодня / уникальных чаттеров сегодня / сообщений за неделю / месяц
график messages / hour — линейный график активности чата за 24 часа / 7 дней / 30 дней (переключатель)
top chatters — топ-10 самых активных зрителей за день / неделю / месяц с прогрессбарами

how it worksкак это работает

Bot sits in IRC chat and counts every message into an in-memory buffer (no disk writes — fast, doesn't block chat). Once every 60 seconds the buffer is flushed to a SQLite database analytics.db. The dashboard shows you aggregates — no raw messages are stored.

Бот сидит в IRC-чате и считает каждое сообщение в in-memory буфер (без записи на диск — это быстро и не блокирует чат). Раз в 60 секунд буфер сливается в SQLite-базу analytics.db. На дашборде ты видишь агрегаты — никаких raw-сообщений не хранится.

what is NOT collectedчто НЕ собирается

message text (only counters)
private/whisper messages
data from other channels — each streamer sees only themselves
тексты сообщений (только счётчики)
приватные/whisper-сообщения
данные с других каналов — каждый стример видит только себя

data collection start pointс какого момента данные

Analytics starts accumulating from the moment the bot is enabled on the channel. No historical data before that — Twitch doesn't provide it. First numbers on the chart will appear 1-2 minutes after start.

Аналитика начинает копиться с момента включения бота на канале. Исторических данных за период до подключения нет — Twitch их не отдаёт. Первые цифры на графике появятся через 1-2 минуты после старта.

roadmap

phase 2 planned: activity heatmap by hour/day-of-week, top commands (!faceit, !music), top emotes, follower growth per day, per-stream breakdown (peak viewers per each stream).

в этап 2 запланированы: heatmap активности по часам/дням недели, топ команд (!faceit, !музыка), топ эмодзи, рост followers по дням, per-stream breakdown (peak viewers за каждый стрим).

/::docs::platforms::twitch

twitch integration

bot accountаккаунт бота

shizick666 — single bot account for all Twitch channels.

shizick666 — единый аккаунт бота для всех Twitch-каналов.

how to authorizeкак авторизоваться

On /login type 1 or twitch. Twitch OAuth opens — grant access.

На странице /login введи 1 или twitch. Откроется OAuth страница Twitch — разреши доступ.

messagesсообщения

Bot sends via official Helix /chat/messages endpoint — this gives your stream a bot badge in chat (same as other "Verified Bot" accounts).

Бот отправляет через официальный Helix /chat/messages endpoint — это даёт твоему стриму бот-значок в чате (как у других "Verified Bot" аккаунтов).

not supportedчто не поддерживается

Message pin — Twitch doesn't expose API for third-party (only via web cookies)
Subscriber events — partially via EventSub, not everywhere
Pin сообщений — Twitch не предоставляет API для third-party (только через web-cookies)
Subscriber events — частично через EventSub, не везде

/::docs::platforms::kick

kick integration

bot accountаккаунт бота

sh1zick — single bot account for all Kick channels.

sh1zick — единый аккаунт бота для всех Kick-каналов.

how to addкак добавить

On /login type 2 or kick
Authorize via Kick OAuth
In the dashboard switch to your Kick channel (target dropdown)
In Kick chat give bot mod rights: /mod sh1zick
На /login введи 2 или kick
Авторизуй через Kick OAuth
В дашборде переключись на свой Kick-канал (target dropdown)
В чате Kick выдай боту мод-права: /mod sh1zick

what worksчто работает

Faceit (!elo, !lobby, etc.)
Custom commands + templating
Economy
Trivia + autostart
Mini-games / lottery
Giveaways + timers
Moderation (link/banword filter)
Stream control (!title, !game, quick-cats)
Music (!track)
Faceit (!elo, !lobby и т.д.)
Кастомные команды + шаблонизатор
Экономика
Trivia + автозапуск
Mini-games / lottery
Giveaways + timers
Moderation (фильтр ссылок/банвордов)
Стрим-управление (!title, !game, quick-cats)
Music (!трек)

notesособенности

On Kick new accounts may not be allowed to post links — it's blocked by Kick itself, not our bot. Fixed by account verification or mod rights on the channel where it posts.

На Kick новые аккаунты могут не иметь права писать ссылки — это блокирует сам Kick, не наш бот. Решается верификацией аккаунта или mod-правами на канале где он пишет.

/::docs::public api::nightbot

public faceit api // for nightbot / streamelements / fossabot

Any streamer can add Faceit commands to their Nightbot (or StreamElements / Fossabot) via our public API — no registration, no auth.

Любой стример может добавить Faceit-команды в свой Nightbot (или StreamElements / Fossabot) через наш публичный API — без регистрации, без авторизации.

API returns plain text, cached for 60 seconds, limited to 400 chars (Nightbot's limit for $(urlfetch)).

API возвращает plain text, кэшируется на 60 секунд, ограничен 400 символами (лимит Nightbot для $(urlfetch)).

endpoints

/api/nb/elo

current elo + today's W/Lтекущее эло + сегодняшние W/L

/api/nb/today

today's stats (W/L and ± elo)статистика за сегодня (W/L и +/- эло)

/api/nb/last

last match (map, score, K/D)последний матч (карта, счёт, K/D)

/api/nb/lobby

live status of current match (map, score, time, avg elo)live-статус текущего матча (карта, счёт, время, avg elo)

Parameter: ?nick=FaceitNick (also ?nickname=...). Case-insensitive.

Параметр: ?nick=FaceitNick (можно также ?nickname=...). Регистр не важен.

examplesпримеры

// test in browser, replace nick with yours:проверь прямо в браузере, заменив ник на свой:
https://claritysync.ru/api/nb/elo?nick=sh1zick

// response (plain text):ответ (plain text):
⭐ Lvl 10 · 2350 elo · today: 5W-2L (+45)сегодня: 5W-2L (+45)

how to add to nightbotкак добавить в nightbot

Go to your Nightbot dashboard → Commands → Custom
Click Add Command

Fill in:

Name:    !elo
Message: $(urlfetch https://claritysync.ru/api/nb/elo?nick=YOUR_FACEIT_NICK)
Userlevel: Everyone
Cooldown: 5

Save and test in chat with !elo
Зайди в свою Nightbot dashboard → Commands → Custom
Нажми Add Command

Заполни:

Name:    !elo
Message: $(urlfetch https://claritysync.ru/api/nb/elo?nick=ТВОЙ_ФЕЙСИТ_НИК)
Userlevel: Everyone
Cooldown: 5

Сохрани и проверь в чате !elo

add via chat (faster)добавить через чат (быстрее)

In your Twitch chat tell Nightbot (replace sh1zick with your faceit nick):

В своём Twitch-чате напиши Nightbot'у (вместо sh1zick — свой faceit ник):

!addcom !elo $(urlfetch https://claritysync.ru/api/nb/elo?nick=sh1zick)
!addcom !today $(urlfetch https://claritysync.ru/api/nb/today?nick=sh1zick)
!addcom !last $(urlfetch https://claritysync.ru/api/nb/last?nick=sh1zick)
!addcom !lobby $(urlfetch https://claritysync.ru/api/nb/lobby?nick=sh1zick)

streamelements / fossabot

Works identically — use the same URL inside ${urlfetch} (SE) or (customapi) (Fossabot).

Работает идентично — используй такой же URL внутри ${urlfetch} (SE) или (customapi) (Fossabot).

streamelements exampleпример streamelements

!command add !elo ${urlfetch https://claritysync.ru/api/nb/elo?nick=sh1zick}

fossabot exampleпример fossabot

!commands add !elo $(customapi https://claritysync.ru/api/nb/elo?nick=sh1zick)

limits and stabilityлимиты и стабильность

60s cache — repeat requests within a minute return the same response instantly, no load on Faceit.
400 char limit — long responses are auto-truncated with ….
Nightbot itself sets default cooldown ~5s per command — that's fine.
Faceit API limits our bot to ~10 req/sec, but with 60s cache it's not a problem even on big channels.
Кэш 60 секунд — повторные запросы за минуту отдают тот же ответ мгновенно, без нагрузки на Faceit.
Лимит 400 символов — длинные ответы автоматически обрезаются с ….
Сам Nightbot ставит cooldown по умолчанию ~5 секунд на команду — это норм.
Faceit API ограничивает наш бот ~10 запросов/секунду, но с кэшем 60с это не проблема даже на крупных каналах.

legacy pathsустаревшие пути

Old paths /api/public/faceit/elo etc. work the same, use whichever. The new /api/nb/* are just shorter.

Старые пути /api/public/faceit/elo и т.д. — работают так же, можешь использовать любые. Новые /api/nb/* просто короче.

/::docs::troubleshoot

troubleshoot

bot doesn't respond in chatбот не отвечает в чате

Check that bot is online in the dashboard
Check that bot is a mod on your channel (/mod shizick666 on twitch)
Twitch may delay messages from new bots on new channels — wait a few minutes
Проверь что бот online в дашборде
Проверь что бот — мод твоего канала (/mod shizick666 на twitch)
Twitch может задерживать сообщения новых ботов на новых каналах — подожди несколько минут

!track says "feature not configured"!трек пишет "функция не настроена"

Server doesn't have yt-dlp or ffmpeg installed. Admin should install:

На сервере не установлен yt-dlp или ffmpeg. Админ должен установить:

apt install -y ffmpeg
pip install yt-dlp

!track says "audd: quota exceeded"!трек пишет "audd: quota exceeded"

AudD free limit (300/mo) is used up. Need to update token in .env or wait until next month.

Закончился бесплатный лимит AudD (300/мес). Надо обновить токен в .env или подождать следующего месяца.

streamer shows offline while onlineстример показывается offline хотя онлайн

Cache refreshes every 60 seconds — wait a minute. If still offline — ping us, we'll check logs.

Cache обновляется раз в 60 секунд — подожди минуту. Если всё равно offline — пиши, посмотрим логи.

/::docs::contact

contact / about

$ cat ~/about.txt

coder. ~2 years deep in python — asyncio, quart, twitchio,
some frontend (vanilla js, html, css), deploys on linux-vps,
nginx, systemd. love when everything works by itself and quietly.

clarity is my main long-term project.
started as a simple twitch-bot for my own channel, grew into
a multi-platform thing with kick integration, faceit live-summaries,
economy, mini-games, shazam-style music recognition and
a full web dashboard.

i do everything myself: backend, frontend, deploy, support, docs.
open to commercial projects, bot/integration gigs and just
interesting collabs.

кодер. ~2 года плотно в python — asyncio, quart, twitchio,
немного frontend (vanilla js, html, css), деплой на linux-vps,
nginx, systemd. люблю когда всё работает само и тихо.

clarity — мой основной долгосрочный проект.
начинал как простой twitch-бот для своего канала, вырос до
multi-platform штуки с kick-интеграцией, faceit live-сводками,
экономикой, мини-играми, шазам-распознаванием музыки и
полноценным веб-дашбордом.

делаю всё сам: backend, frontend, deploy, support, документация.
открыт к коммерческим проектам, заказам на ботов / интеграции
и просто интересным коллабам.

$ whoami --details

role     :: developer / admin / solo
nickname :: sh1zick
since    :: ~2 years in python
stack    :: python · asyncio · quart · twitchio · kick api · sqlite · aiohttp
frontend :: vanilla js · html · css (without frameworks, on purpose)
deploy   :: ubuntu vps · systemd · nginx
status   :: open for work

twitch   :: twitch.tv/shizick666
kick     :: kick.com/sh1zick
telegram :: t.me/sh1zick666
email    :: shizick@claritywork.ru