{"id":31433430,"url":"https://github.com/retrixuy/stbot","last_synced_at":"2026-04-20T09:34:22.170Z","repository":{"id":317129855,"uuid":"1066072447","full_name":"RetrixUY/StBot","owner":"RetrixUY","description":"Backend para overlays de streaming (alertas, chat, Spotify) para Kick, impulsado por Node.js y Streamer.bot.","archived":false,"fork":false,"pushed_at":"2025-09-29T03:51:34.000Z","size":295,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-09-29T04:09:51.140Z","etag":null,"topics":["alerts","chat-overlay","kick","nodejs","obs","song-requests","spotify","spotify-api","sse","stream-overlays","streamerbot","streaming","typescript"],"latest_commit_sha":null,"homepage":"https://github.com/RetrixUY/StBot","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/RetrixUY.png","metadata":{"files":{"readme":"README.en.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":"2025-09-29T01:32:09.000Z","updated_at":"2025-09-29T03:51:37.000Z","dependencies_parsed_at":"2025-09-29T04:10:54.046Z","dependency_job_id":"abd5e6b7-3de4-4cc0-b42b-92bff857ab12","html_url":"https://github.com/RetrixUY/StBot","commit_stats":null,"previous_names":["retrixuy/stbot"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/RetrixUY/StBot","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RetrixUY%2FStBot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RetrixUY%2FStBot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RetrixUY%2FStBot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RetrixUY%2FStBot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/RetrixUY","download_url":"https://codeload.github.com/RetrixUY/StBot/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RetrixUY%2FStBot/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":277675043,"owners_count":25857724,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-30T02:00:09.208Z","response_time":75,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["alerts","chat-overlay","kick","nodejs","obs","song-requests","spotify","spotify-api","sse","stream-overlays","streamerbot","streaming","typescript"],"created_at":"2025-09-30T11:17:46.512Z","updated_at":"2025-09-30T11:17:47.467Z","avatar_url":"https://github.com/RetrixUY.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"right\"\u003e\n  \u003ca href=\"README.md\"\u003e🇪🇸 Español\u003c/a\u003e | \u003ca href=\"README.en.md\"\u003e🇬🇧 English\u003c/a\u003e\n\u003c/div\u003e\n\n---\n\n# StBot - Streaming Overlays and Alerts\n\n[![License: CC BY-NC-SA 4.0](https://img.shields.io/badge/License-CC%20BY--NC--SA%204.0-lightgrey.svg)](https://creativecommons.org/licenses/by-nc-sa/4.0/)\n\nThis project is a Node.js backend designed to supercharge your streams. It connects with **Streamer.bot**, **Spotify**, and **Kick** to capture real-time events and display them on a set of customizable web overlays, ready to be added to OBS or any broadcasting software.\n\n![Screenshot of the overlays in action](Screenshot.png)\n\n---\n\n## ✨ Features\n\n* **Streamer.bot Integration**: Capture and process Kick events in real-time.\n* **Customizable Alerts**: Visual notifications for follows, raids, subscriptions, gifted subs, and Kicks.\n* **Chat Overlay**: Display the Kick chat directly on your stream with a modern design.\n* **Spotify Integration**:\n    * Display the currently playing song with album art, artist, and a progress bar.\n    * **Song Request** system redeemable via channel rewards.\n* **Polls \u0026 Predictions Overlays**: Visualize real-time polls and predictions from Streamer.bot.\n* **Thermal Printer Integration**: Generate and print personalized tickets upon receiving new followers or other events.\n* **Robust Backend**: Built with TypeScript, modern, and featuring automatic reconnection to services.\n* **Easy to Configure**: Everything is managed through a simple environment file.\n\n---\n\n## 🚀 Installation and Setup\n\nFollow these steps to get the project up and running.\n\n### 1. Prerequisites\n\n* **Node.js**: v18 or higher.\n* **Streamer.bot**: With the [Kick extension configured](https://github.com/Sehelitar/Kick.bot).\n* **Spotify Developer Account**: You'll need to create an application on the [Spotify Developer Dashboard](https://developer.spotify.com/dashboard) to get your credentials.\n* **Thermal Printer (Optional)**: A Bluetooth ESC/POS printer (like the [YHK-02BD](https://share.temu.com/5Jy0Dr0jJyA) or similar) if you want to use the printing feature.\n\n### 2. Installation\n\n1.  **Clone the repository**.\n2.  **Open a terminal** in the project folder.\n3.  **Install the dependencies**:\n    ```bash\n    npm install\n    ```\n\n### 3. Streamer.bot Actions\n\nThis project requires a set of actions to function. You will find them in the `Actions.txt` file.\n\n1.  **Import Actions**: In Streamer.bot, go to the `Actions` tab. In the left panel, right-click and select `Import`. Find and select the `Actions.txt` file from this project.\n2.  **Copy the IDs**: Once imported, several actions will be created. Right-click on each of them, select **`Copy Action ID`**, and paste the ID into the `.env` file you will create in the next step.\n\n### 4. Environment Configuration\n\n1.  Create a file named `.env` in the root of the project.\n2.  Copy and paste the following content, filling in the values with your credentials and the IDs of the actions you just imported.\n\n    ```env\n    # LOCAL SERVER PORT\n    PORT=4000\n\n    # -- STREAMER.BOT --\n    SB_HOST=127.0.0.1\n    SB_PORT=8080\n    SB_PASSWORD=\n\n    # -- SPOTIFY --\n    SPOTIFY_CLIENT_ID=YOUR_SPOTIFY_CLIENT_ID\n    SPOTIFY_CLIENT_SECRET=YOUR_SPOTIFY_CLIENT_SECRET\n    SPOTIFY_REDIRECT_URI=http://localhost:4000/callback\n\n    # Channel reward ID for the Song Request\n    REDEMPTION_ID=YOUR_STREAMERBOT_REWARD_ID\n\n    # IDs of the imported Streamer.bot Actions\n    ACTION_GET_REDEEMS=ID_OF_THE_GET_REDEMPTIONS_ACTION\n    ACTION_SEND_MESSAGE=ID_OF_THE_SEND_CHAT_MESSAGE_ACTION\n    ACTION_REJECT_REDEMPTION=ID_OF_THE_REJECT_REDEMPTION_ACTION\n    ACTION_ACEPT_REDEMPTION=ID_OF_THE_ACCEPT_REDEMPTION_ACTION\n\n    # -- THERMAL PRINTER (Optional) --\n    PRINTER_ENABLED=false                 # true to enable printing\n    PRINTER_PORT=COM4                     # Serial or COM Port (e.g., COM4 or /dev/rfcomm0)\n    PRINTER_FONT_REGULAR=C:/path/to/regular_font.ttf\n    PRINTER_FONT_BOLD=C:/path/to/bold_font.ttf\n    PRINTER_BT_MAC=AA:BB:CC:DD:EE:FF      # Bluetooth MAC of the printer (required on Windows/Linux)\n    PRINTER_BT_CHANNEL=2                  # RFCOMM Channel (usually 1, 2, or 11, required for binding on Linux)\n    ```\n\n### 5. Spotify Authorization (One-time only)\n\n1.  Open your browser and go to `http://localhost:4000/auth`.\n2.  Log in and authorize the application.\n\n---\n\n### 6. Thermal Printer Integration 🖨️\n\nThis integration automatically prints a personalized ticket (with the Kick avatar, if available) **every time a new user follows the channel**.\n\nThe printing function is automatically activated upon receiving the `kickFollow` event from Streamer.bot. No additional Streamer.bot action needs to be configured for this event.\n\n#### 6.1. Requirements and Hardware Configuration\n\n1.  **Enable the Feature**: Set `PRINTER_ENABLED=true` in your `.env` file.\n2.  **Port Configuration**:\n    * **Windows**: Ensure the Bluetooth printer is paired and the system has assigned a COM port (e.g., `COM4`). The application will use `PRINTER_PORT` and `PRINTER_BT_MAC` to attempt to establish the correct serial connection.\n    * **Linux**: You must configure the Bluetooth connection for the RFCOMM serial port. The `PRINTER_PORT` value should match the created device (e.g., `/dev/rfcomm0`).\n3.  **Fonts**: The `PRINTER_FONT_REGULAR` and `PRINTER_FONT_BOLD` variables must point to accessible TrueType font (`.ttf`) files for vector text generation.\n\n---\n\n## 🏃‍♂️ Running the Application\n\n* **Development Mode**:\n    ```bash\n    npm run dev\n    ```\n\n* **Production Mode**:\n    ```bash\n    npm run build\n    npm start\n    ```\n\n---\n\n## 🖥️ Adding Overlays to OBS\n\nCreate a new **Browser Source** for each of the following URLs:\n\n* **Alerts**: `http://localhost:4000/overlay/alerts.html`\n* **Chat**: `http://localhost:4000/overlay/chat.html`\n* **Now Playing (Spotify)**: `http://localhost:4000/overlay/nowplaying.html`\n* **Polls / Predictions**: `http://localhost:4000/overlay/polls.html`\n\n---\n\n## ⚖️ License\n\nThis project is licensed under the **Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International** license.\n\n[![License: CC BY-NC-SA 4.0](https://img.shields.io/badge/License-CC%20BY--NC--SA%204.0-lightgrey.svg)](https://creativecommons.org/licenses/by-nc-sa/4.0/)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fretrixuy%2Fstbot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fretrixuy%2Fstbot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fretrixuy%2Fstbot/lists"}