{"id":43601743,"url":"https://github.com/podrivo/botivo","last_synced_at":"2026-02-04T06:01:24.947Z","repository":{"id":209553681,"uuid":"724300463","full_name":"podrivo/botivo","owner":"podrivo","description":"Botivo combines a Twitch chatbot with a powerful OBS overlay, enabling custom commands and fully customizable overlays built with HTML, CSS, and JavaScript. Built-in libraries makes creating animations simple and fast.","archived":false,"fork":false,"pushed_at":"2026-02-01T19:06:44.000Z","size":2141,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-02-01T23:06:27.008Z","etag":null,"topics":["anime","animejs","chatbot","expressjs","nodejs","obs-overlay","obs-studio","streaming","tmijs","twitch","twitchdev"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/podrivo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-11-27T19:59:56.000Z","updated_at":"2026-02-01T22:46:25.000Z","dependencies_parsed_at":"2023-11-28T01:32:43.047Z","dependency_job_id":"62728b7f-7a1d-4ffd-ba43-60f70b371f1b","html_url":"https://github.com/podrivo/botivo","commit_stats":null,"previous_names":["podrivo/botivo"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/podrivo/botivo","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/podrivo%2Fbotivo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/podrivo%2Fbotivo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/podrivo%2Fbotivo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/podrivo%2Fbotivo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/podrivo","download_url":"https://codeload.github.com/podrivo/botivo/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/podrivo%2Fbotivo/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29072446,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-04T03:31:03.593Z","status":"ssl_error","status_checked_at":"2026-02-04T03:29:50.742Z","response_time":62,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["anime","animejs","chatbot","expressjs","nodejs","obs-overlay","obs-studio","streaming","tmijs","twitch","twitchdev"],"created_at":"2026-02-04T06:00:27.835Z","updated_at":"2026-02-04T06:01:24.934Z","avatar_url":"https://github.com/podrivo.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cimg src=\"https://github.com/podrivo/botivo/assets/546221/217e12ad-10ab-438a-8828-0ef7bcca89ce\" width=\"400\" alt=\"Botivo logo\"\u003e\n\nBotivo combines a Twitch chatbot with a powerful OBS overlay, enabling custom commands and fully customizable overlays built with HTML, CSS, and JavaScript. Built-in libraries makes creating animations simple and fast.\n\n\nHow it works\n---\nBotivo listens to your Twitch chat, and when a command is typed it can both reply in chat and tell the overlay — a webpage loaded via Browser Source in OBS — to play an animation, video or sound.\n\nAdd infinite commands by just adding new folders and files. There are examples included to help you get started. Make sure to check how the structure works, and customize all commands you need.\n\n\nUsage\n---\nMake sure [Node.js](https://nodejs.org/) is installed in your machine. [Download](https://github.com/podrivo/botivo/releases) or clone this repository.\n\nOpen your system's terminal and navigate to the downloaded folder and install.\n```shell\ncd botivo\nnpm install\n```\n\nRename file `.env.example` to `.env` and make sure to set your environment variables.\n```dotenv\n# Your bot's Twitch username\n# The account that will send messages\nTWITCH_USERNAME=\"twitch_bot_username\"\n\n# Get your access token from:\n# https://twitchtokengenerator.com/\nTWITCH_TOKEN=\"twitch_bot_access_token\"\n\n# Channel name where the bot will listen for commands\n# Don't include the #\nTWITCH_CHANNEL=\"twitch_channel_name\"\n\n# Port nsumber for overlay server\n# Default: 8080\nSERVER_PORT=\"8080\"\n```\n\nStart the application:\n```shell\nnpm start\n```\n\nYou should see logs on your terminal:\n```shell\n█ BOTIVO starting...\n\n▒ Variables   ✓ Found .env and environment variables\n▒ Overlay     ✓ Add this URL in OBS (Browser Source) → http://localhost:8080\n▒ Events      ✓ Communication with overlay started\n▒ Twitch      ✓ Connected to channel 'podrivo', with user 'LemosTheBot'\n▒ Commands    ✓ Successfully loaded 15 custom and 2 built-in commands\n\n█ BOTIVO is ready to go!\n```\n\nAdd the overlay URL in your OBS. Go to your Twitch channel chat page and send a `!train` message. You should see a simple Kappa emote train animation from right to left.\n\nFor setup steps, see [OBS setup](docs/OBS_SETUP.md).\n\n\nHow it technically works\n---\nBotivo is initiated in `start.js`. It connects to Twitch IRC using [tmi.js](https://tmijs.com/), via an [Express](https://expressjs.com/) server.\n\nBotivo automatically discovers and loads commands from the `/commands` directory. When a command is triggered in chat, the `command.js` emits an event via [Socket.IO](https://socket.io/) to overlay, then `overlay.js` grabs the event and triggers the DOM manipulation.\n\nUse any JavaScript library and CSS to create animations and HTML5 to play audios and videos. Built-in libraries [Anime.js](https://animejs.com/), [Splitting.js](https://splitting.js.org/) and [Fitty](https://rikschennink.github.io/fitty/) for animations and text effects.\n\nTo use your overlay as a `Browser Source` in [OBS Studio](https://obsproject.com/), you need to keep the bot running in your computer and set the overlay URL that is included in your terminal log, usually `http://localhost:8080`.\n\nSee [docs/OVERLAY_LIBRARIES.md](docs/OVERLAY_LIBRARIES.md) for default options and how they're used.\n\n\nWhat it can't do\n---\nDue to how Twitch API works, this bot can only see chat messages. You won't be able to detect new followers, raids, channel points or any other Twitch functionality other than chat. It relies on [tmi.js](https://tmijs.com/) to connect with Twitch IRC, so make sure you see their [documentation](https://tmijs.com/#guide) for more details.\n\nCommands\n---\n### Structure\n```js\ncommand.js  // Server side (required)\noverlay.js  // Overlay side (optional)\nconfig.js   // Custom config (optional)\nassets/     // HTML, CSS, JS, images, audio, etc.; injected into the overlay (optional)\n```\n\n\n### Adding a new command\n1. **Copy a template** — For a **chat-only** command (no overlay): copy the `commands/hello` folder. For a **chat + overlay** command: copy the `commands/example` folder.\n2. **Rename the folder** — Rename it to your command name (e.g. `meme` → use `!meme` in chat).\n3. **Edit the chat message** — In `command.js`, change what the bot says (e.g. `twitch.say(...)`).\n4. **If you want overlay** — Edit `overlay.js` and the files in `assets/` (HTML, CSS, sounds, etc.).\n5. **Optional** — In `config.js` set cooldown, permission, or alias.\n\n\n### Built-in commands\n| Name | Description | Alias |\n|---------|-------------|---------|\n| `!commands` | Lists available commands in chat (app built-in). | — |\n| `!kill` | Stop all overlay activity (app built-in; see [Kill](#kill)). | `!stop`, `!killall`, `!kill-all` |\n\n### Example commands\n| Name | Description | Alias |\n|---------|-------------|---------|\n| `!hello` | Chat-only example (replies \"Hello, @username!\"). | — |\n| `!example` | Example command. | — |\n| `!train` | Example command (train animation). | — |\n| `!tts` | Text-to-speech (see [TTS](#tts-text-to-speech)). | — |\n| `!shape` | Control overlay shape, position, and color. | — |\n| `!brb` | Broadcaster \"be right back\" toggle. | `!back` |\n| `!youtube` | YouTube playback control. | `!yt`, `!music`, `!video` |\n| `!nice` | \"Nice!\" overlay + sound. | — |\n| `!wow` | \"Wooow!\" overlay + random sound. | — |\n| `!error` | Test/demo: overlay-only (no chat reply); shows error overlay and plays error sound. | — |\n\n### Command files\n`command.js` — **Sends Twitch chat messages via [tmi.js](https://tmijs.com/)**\n```js\n/**\n * Command handler function\n * @param {Object} twitch - Twitch client instance (tmi.js Client)\n * @param {Object} events - Socket.IO server instance for emitting events to overlay\n * @param {string} channel - Twitch channel name where the command was triggered\n * @param {Object} tags - Message tags with user info (username, display-name, mod, subscriber, badges, etc.)\n * @param {string} message - The full message text that triggered the command\n */\n\nexport default function(twitch, events, channel, tags, message) {\n  \n  // Send a message to chat\n  twitch.say(channel, `@${tags.username} used ${message}. The is the Twitch chat example message!`)\n\n  // Print log to server\n  console.log('▒ !example was used. This is a test message.')\n\n  // You can also emit additional events to the overlay\n  // This is optional\n  events.emit('extra-event-a')\n  events.emit('extra-event-b')\n}\n```\n\n`overlay.js` — **Animate DOM elements via [Anime.js](https://animejs.com/)**\n```js\nexport default function (events) {\n\n  // Get DOM element\n  let element = document.querySelector('.example-element')\n\n  // Simple fade in and scale animation\n  anime.animate(element, {\n    opacity: [0, 1],\n    marginTop: ['50px', '0px'],\n    duration: 600,\n    ease: 'outExpo',\n    onComplete: () =\u003e {\n\n      // Fade out after 2.5 seconds\n      setTimeout(() =\u003e {\n        anime.animate(element, {\n          opacity: [1, 0],\n          marginTop: ['0px', '50px'],\n          duration: 600,\n          ease: 'outExpo',\n        })\n      }, 2500)\n    }\n  })\n\n  // Grab additional events from command.js\n  // This is optional\n  events.on('additional-a',  () =\u003e {console.log(`'additional-a' received`)})\n  events.on('additional-b', () =\u003e {console.log(`'additional-b' received`)})\n}\n```\n\n`config.js` — **Custom configurations for the command**\n```js\n/**\n * Command Configuration\n *\n * Enabled:\n * - enabled: boolean           // Whether the command is available (defaults to true if not set)\n * \n * Permissions:\n * - permission: 'broadcaster'  // Only broadcaster\n * - permission: 'moderator'    // Broadcaster and moderators\n * - permission: 'vip'          // Broadcaster, moderators, and VIPs\n * - permission: 'subscriber'   // Broadcaster, moderators, VIPs, and subscribers\n * - permission: 'viewer'       // Everyone (default if not set)\n * \n * Cooldown:\n * - cooldown: number           // Time in milliseconds (defaults to cooldownGlobal if not set)\n * \n * Aliases:\n * - alias: string | string[]   // Alternative command names that trigger the same command\n *   Examples:\n *   - alias: 'demo'            // Single alias: !example and !demo both work\n *   - alias: ['demo', 'test']  // Multiple aliases: !demo and !test all work\n */\n\nexport const config = {\n  enabled: true,\n  permission: 'viewer',\n  cooldown: 5000,\n  alias: 'demo',\n}\n\n```\n\n`assets/index.html` — **HTML will be injected into the overlay**\n```html\n\u003c!-- !example command HTML --\u003e\n\u003cdiv class=\"example-element\"\u003e\n  Example command!\n\u003c/div\u003e\n```\n\n`assets/style.css` — **CSS will be loaded into the overlay**\n```css\n.example-element {\n  position: fixed;\n  top: 50%;\n  left: 50%;\n  transform: translate(-50%, -50%);\n  padding: 24px 32px;\n  background-color: rgba(0, 0, 0, 0.7);\n  color: white;\n  border-radius: 32px;\n  corner-shape: squircle;\n  font-size: 24px;\n  font-weight: 400;\n  opacity: 0;\n  z-index: 1000;\n  pointer-events: none;\n}\n```\n\n### Command reference\n\n### Commands\n\nThe `!commands` command lists available commands in chat (app built-in).\n\n### Kill\n\nThe `!kill` command (aliases: `!stop`, `!killall`, `!kill-all`) pauses and resets all audio, video, CSS animations/transitions, and Anime.js animations (it does not remove DOM elements). Useful when many commands are running at the same time and you want to quiet the overlay.\n\n### Hello\n\nThe `!hello` command is a minimal chat-only example; it replies in chat with \"Hello, @username!\". Use it as the template for commands that only send a chat message (no overlay).\n\n### Example\n\nThe `!example` command is the example command; it sends a chat reply and triggers overlay animation.\n\n### Train\n\nThe `!train` command runs the example train animation (Kappa emote train from right to left).\n\n### TTS (Text-to-speech)\n\nThe `!tts` command speaks text in the overlay using the browser's Speech Synthesis API. Use `!tts \u003cmessage\u003e` for default (English) or `!tts \u003clang\u003e \u003cmessage\u003e` for a specific language (e.g. `!tts es hola mundo`).\n\nAvailable voices depend on the viewer's operating system and browser (macOS, Windows, and Linux ship different default voices). The supported language list is kept to languages commonly present on default installs.\n\nFor the **full list of language codes** and how to **add or remove languages** (edit `commands/tts/config.js`), see [docs/TTS.md](docs/TTS.md).\n\n### Shape\n\nThe `!shape` command updates the overlay shape, position, and color in real time. Use `!shape` with no arguments to see help. Use `!shape \u003ccmd\u003e` where `\u003ccmd\u003e` is one of: `show`, `hide`, `square`, `circle`, `rect`, `color \u003cvalue\u003e`, `top`, `bottom`, `left`, `right`, `center`, `reset`.\n\n### BRB (Be right back)\n\nThe `!brb` and `!back` commands toggle a \"be right back\" overlay (broadcaster-only). Use `!brb` to turn it on (chat says \"Be right back...\"); use `!back` to turn it off (chat says \"Back to action!\" and the overlay toggles off).\n\n### YouTube\n\nThe `!youtube` command (aliases: `!yt`, `!music`, `!video`) controls YouTube playback on the overlay. Send a YouTube URL to add a video to the queue. Subcommands: `play`, `pause`, `next`, `vol 0-100`, `queue`, `zoom`.\n\n### Nice\n\nThe `!nice` command shows a \"Nice!\" overlay and plays a sound.\n\n### Wow\n\nThe `!wow` command shows a \"Wooow!\" overlay and plays a random sound.\n\n### Error\n\nThe `!error` command is a test/demo; overlay-only (no chat reply). It shows an error overlay and plays an error sound.\n\n\nGlobal configuration\n---\nIf you need to customize Botivo, you can edit `/app/config.js`.\n```js\n// Botivo configuration\nexport const CONFIG = {\n  prefix: '!',                 // Command prefix (\"!\" for !train, !example)\n  twitchReconnect: true,       // Automatically reconnect to Twitch on disconnect\n  folderCommands: 'commands',  // Directory name where commands are stored\n  folderOverlay: 'overlay',    // Directory name where overlay files are stored\n  cooldownGlobal: 5000         // Global cooldown if a command doesn't specify its own\n}\n```\n\n\nLicense\n---\nReleased under the [MIT license](LICENSE).","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpodrivo%2Fbotivo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpodrivo%2Fbotivo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpodrivo%2Fbotivo/lists"}