Self-hosted YouTube song request queue for Twitch streams. No cloud, no .env editing, no config files to hand-edit - everything is set up through a web control panel.
Viewers request songs in Twitch chat, StreamQueue searches YouTube, filters out unwanted videos, manages the queue, and plays it through an OBS Browser Source overlay. When the queue is empty, a fallback YouTube playlist keeps music going between requests.
- 🎵 Song request queue - search YouTube or paste a video URL, duplicate detection, per-user request limits, queue size limits, and admin controls
- 📺 Native Twitch integration - connect Twitch directly from the control panel without Streamer.bot; configurable chat commands, permissions, cooldowns, and Channel Points redemptions
- 🎁 Channel Points rewards - create and edit request rewards, configure cost/limits/cooldowns/color, select the reward used for song requests, and control automatic fulfillment
- 🚫 Blocklist - block tracks from Activity, Queue, or the fallback list; blocked tracks cannot be re-added and are skipped automatically
- 🎛 Web control panel - live queue, playback controls, fallback playlist, Twitch settings, filters, overlay options, blocklist, activity, and configuration
- 📺 OBS overlay - a
/overlayBrowser Source that plays the queue and shows a compact Now Playing badge with configurable position and size - 🔁 Fallback playlist - use any YouTube playlist as background music with shuffle and repeat, with automatic refresh
- 📋 Saved playlists - keep a library of playlists and switch the active fallback playlist from the control panel
- 📈 Activity log - see accepted, rejected, blocked, and failed requests with structured failure reasons
- 📱 LAN access - QR code and local network access for managing the queue from another device
- 🌍 RU/EN interface
- 🖥️ Windows standalone build - packaged
Service.exeruns without Node.js installed; optional .NET 10 WinForms tray launcher provides a normal double-click workflow - 💾 Local storage - queue, settings, playlists, blocklist, and cache stay on disk next to the application
Twitch chat / Channel Points
│
▼
Native Twitch integration
│
▼
StreamQueue request handling
│
▼
YouTube Data API ── search + filters ──▶ queue
│
▼
OBS Browser Source (/overlay)
The easiest way to run StreamQueue on Windows is the standalone ZIP release.
- Download the latest release ZIP from GitHub Releases.
- Extract it to a folder.
- Run
Service.exeor the optionalStreamQueue.exetray launcher. - Open the control panel shown by the application.
- Go to Settings and add your YouTube Data API key.
- Connect Twitch from the Twitch settings.
- Add the StreamQueue
/overlayURL as an OBS Browser Source.
The packaged build includes the Twitch client ID, so the released Windows build does not require you to create or enter a Twitch client secret.
The application is portable: data/, cache/, and logs/ are created next to the executable. No Node.js installation is required.
- Node.js 24+
- A .NET 10 SDK on Windows if you want to build the optional tray launcher
- A YouTube Data API v3 key
git clone https://github.com/choompuy/stream-queue.git
cd stream-queue
npm install
npm run devThe server uses port 4747; if it is busy, the next free port is taken and remembered, so the overlay link stays the same afterwards. To pick another port, edit data/server.json. Configure the YouTube API key from the web control panel; it is stored locally and takes effect without a restart.
npm run build:seaThis produces dist-sea/Service.exe, a self-contained Node.js Single Executable Application. npm run build:release goes one step further and assembles the release/ folder (exe with icon and version on Windows, public/, license) that is ready to run or to zip. Node.js 24 or newer is needed to build.
For a no-terminal-window experience, build the optional .NET 10 WinForms tray launcher in tray/. It starts and stops the service in the background and provides shortcuts for opening the panel, logs, application folder, restart, and exit.
To build the tray launcher:
cd tray
dotnet publish -c Release -r win-x64 --self-contained true -p:PublishSingleFile=true -p:IncludeNativeLibrariesForSelfExtract=trueThe tray launcher is self-contained, so the published executable does not require a separate .NET runtime installation.
npm test
npm run test:smoke- Add a Browser Source in OBS.
- Copy the URL from Settings → Overlay → OBS Browser Source URL.
- Set the Browser Source size to match your overlay layout. 362×283 is a reasonable starting size.
The overlay can show the current video plus a compact Now Playing badge containing the title, requester, and progress. Its position can be configured in the control panel.
StreamQueue can connect directly to Twitch without requiring Streamer.bot.
From the control panel you can:
- connect and disconnect a Twitch account;
- configure chat commands for requests, queue/now-playing information, skip, pause, and resume;
- configure command permissions and cooldowns;
- create and edit Channel Points rewards;
- select which configured reward creates song requests;
- configure reward limits, cooldowns, cost, color, and automatic fulfillment;
- receive request and playback status messages directly in Twitch chat.
The released Windows build contains the Twitch client ID. Twitch OAuth tokens are stored locally with the rest of the application state.
A viewer can request a song through the configured Twitch command, for example:
!sr never gonna give you up
StreamQueue searches YouTube, validates the result against the configured filters, and either adds it to the queue or starts playback when the queue is empty.
Requests can be rejected for reasons such as duplicate tracks, queue limits, user limits, blocked videos, invalid/unavailable videos, duration/view filters, or YouTube API quota limits. Responses are localized and include a structured failure reason for the control panel and integrations.
Most configuration is editable from the web control panel.
| Setting | Default |
|---|---|
| Minimum views | 10,000 |
| Minimum duration | 60s |
| Maximum duration | 480s (8 min) |
| Max queue size | 20 |
| Max active requests per user | 4 |
| Region | none |
| Allow Shorts | disabled |
| Allow live streams | disabled |
| Fallback playlist | disabled until configured |
YouTube requests are restricted to music-category, embeddable and syndicated videos by default, with additional validation for duration, availability, and other configured filters.
Configuration updates support field-level validation: valid values can be saved even when another submitted field is rejected.
Use the Blocklist controls from Activity, Queue, or fallback entries to block a track.
Blocked tracks are:
- rejected when requested again;
- removed from the active queue when applicable;
- skipped when encountered during fallback playback;
- prevented from being selected again until they are unblocked.
The activity log records block and playback events so moderation actions remain visible after the fact.
StreamQueue handles common playback failures without leaving the queue in a stuck state.
- Player failures are reported with the affected video.
- Duplicate failure reports are ignored.
- Failed fallback tracks can advance to another track.
- Blocked tracks are skipped during playback.
- Playback and queue state are persisted locally.
- The overlay reports player errors back to the local service.
StreamQueue is designed to run locally on your own machine.
Application state is stored as JSON next to the executable:
data/
config.json
playlists.json
secrets.json
cache/
queue-state.json
youtube-cache.json
logs/
Your YouTube API key and Twitch OAuth state are stored locally. The application communicates with external services only when needed for its integrations, primarily the YouTube Data API and Twitch APIs.
Node.js · TypeScript · Express · vanilla JavaScript · YouTube Data API v3 · YouTube IFrame Player API · Twitch APIs · Twitch EventSub WebSocket · optional C#/WinForms tray launcher for Windows (.NET 10)
MIT - © choompuy