# YouTube Commands ### Command Syntax All YouTube commands use: * **Primary:** `/streamlink youtube ` * **Alias:** `/sl youtube ` {% hint style="info" %} **Permissions:** All YouTube commands are available to all players by default (no OP required). {% endhint %} {% hint style="warning" %} **Active Stream Required:** YouTube integration only works when you have an active live stream with chat enabled. You cannot connect to offline channels or scheduled streams. {% endhint %} *** ### Available Commands #### `/sl youtube setup` Configure your YouTube Data API v3 Key for authentication. **Syntax:** ``` /sl youtube setup ``` **Parameters:** * `` - Your Google Cloud API Key with YouTube Data API v3 enabled **What It Does:** * Saves API Key to your player data * Credentials persist across server restarts * Required for accessing YouTube Live Chat API * Used for validating and connecting to live streams **Example:** ``` /sl youtube setup AIzaSyAbc123Def456Ghi789Jkl012Mno345Pqr ``` **Response:** ``` [StreamLink] YouTube API Key saved! [StreamLink] Next: Set your channel with /streamlink youtube set ``` *** #### `/sl youtube set` Set your YouTube Channel ID for live chat integration. **Syntax:** ``` /sl youtube set ``` **Parameters:** * `` - Your 24-character YouTube Channel ID (starts with `UC`) **What It Does:** * Saves Channel ID to your player data * Used to find your active live streams * Used to connect to live chat * Persists across server restarts **Example:** ``` /sl youtube set UCa1b2c3d4e5f6g7h8i9j0k1l2m3n ``` **Response:** ``` [StreamLink] YouTube channel ID set to: UCa1b2c3d4e5f6g7h8i9j0k1l2m3n ``` **Important Notes:** * Must be exactly 24 characters * Must start with `UC` * This is NOT your channel name or custom URL * This is NOT your `@handle` * Required before connecting *** #### `/sl youtube connect` Connect to your YouTube Live chat stream. **Syntax:** ``` /sl youtube connect ``` **Prerequisites:** * API Key configured via `/sl youtube setup` * Channel ID set via `/sl youtube set` * Active live stream running on YouTube * Live chat enabled on your stream **What It Does:** **1. API Key Validation** (\~100 API units, \~2 seconds) * Verifies API Key is valid * Checks YouTube Data API v3 is enabled * Tests API access **2. Live Stream Detection** (\~100 API units, \~2 seconds) * Searches for active live broadcasts on your channel * Retrieves live stream video ID * Gets live chat ID from stream details **3. Chat Connection** (\~1 second) * Connects to YouTube Live Chat API * Starts polling system * Sets polling interval (typically 5 seconds) **4. Message Polling** (3 API units per poll, every \~5 seconds) * Polls for new messages * Batches messages together * Displays in-game * First poll skipped (prevents spam) **Total Connection Time:** \~5-7 seconds **Example:** ``` /sl youtube connect ``` **Success Messages:** ``` [StreamLink] Validating credentials... [StreamLink] API Key validated! [StreamLink] Connecting to YouTube live chat... [StreamLink] Connected to YouTube live chat ``` **What You'll See:** ``` [YOUTUBE] [OWNER] YourChannel : Welcome everyone! [YOUTUBE] [MOD] ModeratorName : Great stream today! [YOUTUBE] [MEMBER] MemberName : Thanks for the content! [YOUTUBE] ViewerName : Hello from YouTube! ``` **Error Messages:** | Error | Cause | Solution | | ----------------------------- | --------------------- | ---------------------------------- | | "Set your channel ID first" | No channel configured | Run `/sl youtube set ` | | "Run setup first" | Missing API key | Run `/sl youtube setup ` | | "Already connected!" | Already active | Run `/sl youtube disconnect` first | | "Invalid or expired API key" | Bad API key | Regenerate key, verify API enabled | | "No active live stream found" | Not streaming | Start live stream on YouTube | | "Live chat is not enabled" | Chat disabled | Enable chat in stream settings | **Connection Requirements:** * YouTube Studio showing stream as "Live" * Stream chat enabled (not disabled) * Public or Unlisted stream (Private untested) * Stream fully started (wait 30-60 seconds after "Go Live") **API Usage During Connection:** * Initial connection: 201 units (100 + 100 + 1) * Per hour streaming: \~2,160 units (3 × 720 polls) * Total per session: \~2,361 units/hour **Polling Behavior:** * **Interval:** \~5000ms (5 seconds), set by YouTube * **Adaptive:** YouTube may adjust based on activity * **First Poll:** Skipped to avoid message spam * **Message Delay:** \~5-10 seconds between YouTube and in-game **Connection States:** * 🔴 **Disconnected:** Before connection * 🟡 **Connecting:** During validation and setup (\~5-7 seconds) * 🟢 **Connected:** Polling active, receiving messages **What's NOT Supported:** * Event notifications (no follows, subs, memberships, Super Chats) * Real-time WebSocket (polling only) * Emote images (text only) * Anonymous viewing (API key required) * Offline chat (stream must be live) *** #### `/sl youtube disconnect` Disconnect from YouTube Live chat integration. **Syntax:** ``` /sl youtube disconnect ``` **What It Does:** **1. Stop Polling** * Cancels active polling loop * Stops API requests to YouTube * No more quota usage **2. Close Connection** * Disconnects from Live Chat API * Cleans up polling thread **Example:** ``` /sl youtube disconnect ``` **Response:** ``` [StreamLink] Disconnected from YouTube live chat ``` **What Stops:** * Chat messages no longer appear * API polling stops * API quota usage stops * Network connections closed **What Stays:** * API Key remains saved * Channel ID remains saved * No need to re-setup * Can reconnect anytime with `/sl youtube connect` **When to Disconnect:** * **Ending your stream** (most important!) * Taking a break * Switching platforms * Troubleshooting connection issues * **Conserving API quota** (critical!) * Before logging out (optional - auto-disconnects anyway) **API Quota Savings:** * Stops 3 units per 5 seconds * Saves \~2,160 units per hour * Extends daily quota availability * Allows longer streaming sessions **Performance Impact:** * Stops 1 polling thread * Closes HTTP connections * Reduces server load slightly **Automatic Disconnection:** You'll be automatically disconnected when: * You log out of the server * Server shuts down * Live stream ends * Connection error occurs **Reconnecting:** ``` /sl youtube connect ``` Uses saved credentials - no need to run setup again! **Why Manual Disconnect Matters:** * YouTube has strict API quotas (10,000 units/day) * Leaving connected wastes quota (\~2,160 units/hour) * Disconnecting immediately saves quota for future streams * Prevents hitting daily limits **Troubleshooting:** If disconnect fails or hangs: 1. Wait 10 seconds for timeout 2. Relog to force cleanup 3. Check server console for errors *** ### Related Documentation * [**YouTube Setup Guide →**](/streamlink/guides/youtube-setup-guide.md) - Initial configuration --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://kentatetsu.gitbook.io/streamlink/commands/youtube-commands.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.