Guides

Learn how to set up, customize, and get the most out of Social Stream Ninja

Getting Started (Browser Extension)

1. Installation

Before you can use Social Stream Ninja, you'll need to install it first. There are multiple ways to install the browser extension:

  • Manual Installation (recommended):: For the most up-to-date version, install manually in developer mode.
  • Chrome Web Store: Install via Chrome Web Store for the easiest setup experience.

For detailed installation instructions, please visit the Download page.

2. Basic Setup

Once installed, follow these steps to start using Social Stream Ninja:

  1. Open your streaming platform's chat in a browser (or use the pop-out chat feature if available)
  2. Click the Social Stream Ninja extension icon in your browser toolbar
  3. Click "Enable Extension" to turn it on (the icon should turn green)
  4. Open the "Dashboard Link" provided in the extension popup
  5. Open the "Overlay Link" in OBS as a browser source

Note: For the best experience, keep chat windows visible (not minimized) when using the browser extension.

3. Connecting to Different Platforms

Social Stream Ninja works with 100+ platforms. Here's how to connect to the most popular ones:

YouTube

  • Open YouTube Live chat
  • Click the "Pop out chat" button in the top-right corner
  • Ensure the Social Stream Ninja extension is enabled (green icon)

Twitch

  • Open Twitch chat for your channel
  • Click the gear icon and select "Pop out chat"
  • Ensure the Social Stream Ninja extension is enabled (green icon)

Facebook

  • Open your Facebook Live broadcast (as a viewer or publisher)
  • Ensure you're connected to WiFi or Ethernet (not mobile data)
  • Ensure the Social Stream Ninja extension is enabled (green icon)

Discord, Slack, WhatsApp, etc.

  • First, enable these platforms in the extension settings (toggle switch)
  • Open the web versions of these platforms in your browser
  • Ensure the Social Stream Ninja extension is enabled (green icon)

Customization (Browser Extension)

URL Parameters

You can customize both the dashboard and overlay by adding parameters to their URL. Some examples:

Dashboard Parameters:

&darkmode - Enables dark mode for the dashboard
&scale=2 - Doubles the size/resolution of all elements
&hidesource - Hides platform icons (YouTube, Twitch, etc.)
&compact - Removes spacing between name and message
&autoshow - Auto-features messages as they appear (about 2 per 3 seconds)

Overlay Parameters:

&showtime=20000 - Auto-hides selected messages after 20 seconds
&showsource - Shows the platform icons next to usernames
&fade - Makes featured messages fade in instead of popping up
&swipe - Makes featured messages swipe in from the left
¢er - Centers featured messages on screen

For easier URL management, try our URL Parameter Editor Tool.

CSS Customization

There are several ways to customize the appearance with CSS:

Method 1: OBS Browser Source CSS

In OBS, you can add custom CSS to the browser source:

  1. Add your overlay as a Browser Source in OBS
  2. Check the "Custom CSS" option
  3. Enter your custom CSS in the text box
body { background-color: rgba(0, 0, 0, 0); margin: 0px auto; overflow: hidden; }

:root {
    --comment-color: #090;
    --comment-bg-color: #DDD;
    --comment-border-radius: 10px;
    --comment-font-size: 30px;
    --author-border-radius: 10px;
    --author-bg-color: #FF0000;
    --author-avatar-border-color: #FF0000;
    --author-font-size: 32px;
    --author-color: blue;
    --font-family: "Arial", sans-serif;
}

.hl-name {
    padding: 2px 10px !important;
}

Method 2: Extension Menu Settings

Add CSS directly through the extension menu:

  1. Click the Social Stream Ninja extension icon
  2. Find the CSS/JavaScript settings section
  3. Enter your custom CSS or JavaScript
  4. The CSS will be appended to the URL as base64 encoded data

Method 3: Use Custom Templates

Choose from pre-styled templates that include CSS built-in:

  • Browse our Templates Gallery
  • Select a template that matches your stream's style
  • Replace YOURSESSIONID in the template URL with your session ID
  • Add the template URL as a browser source in OBS

Example: https://socialstream.ninja/themes/pretty.html?session=YOURSESSIONID

Advanced Features (Browser Extension)

Text-to-Speech

Social Stream Ninja can read chat messages aloud using Text-to-Speech technology:

Setting Up TTS:

  1. Add &speech=en-US to your featured.html or dock.html URL
  2. For other languages, change the language code (e.g., &speech=fr-FR for French)
  3. Customize voice settings with parameters like &pitch=1&volume=1&rate=1

Premium TTS Options:

  • Kokoro TTS: Browser-based premium quality TTS (included free)
  • Google Cloud TTS: Professional-quality voices (requires Google API key)
  • ElevenLabs: Ultra-realistic voices with custom voice training
  • Speechify: Natural-sounding premium voices

Queuing and Pinning Messages

Organize how messages appear in your overlay:

Queuing Messages:

  1. Hold CTRL (or Cmd on Mac) while clicking messages in the dashboard
  2. Click the "Next in Queue" button to display them one by one
  3. Messages will appear in your overlay in the order they were queued

Pinning Messages:

  1. Hold ALT while clicking a message in the dashboard
  2. The message will stay pinned at the top of the dashboard
  3. To unpin, hold ALT and click the pinned message again

Troubleshooting (Browser Extension)

Solutions for common issues with the browser extension

Minimized Window Issue

Chat Stops When Background/Minimized

Chat messages stop appearing when browser windows are in the background or minimized. This happens because browsers throttle background tabs to save resources.

Disable Browser Throttling
  • Chrome/Edge/Brave:
    1. Open chrome://flags/#enable-throttle-display-none-and-visibility-hidden-cross-origin-iframes
    2. Set to "Disabled"
    3. Also disable chrome://flags/#calculate-native-win-occlusion
    4. Restart your browser
  • Disable Performance Throttling:
    1. Go to chrome://settings/performance
    2. Disable "Throttle Javascript timers in background"
Alternative Approaches
  • Keep Windows Visible: Arrange windows so they're not minimized; even a small visible portion can prevent throttling.
  • Use Virtual Desktops: On Windows, use Win+Tab to create two virtual desktops, with chat windows on one and OBS on the other.
  • Try the Standalone App: The Social Stream Ninja desktop app avoids many browser throttling issues.
Debug Bar Issue

Blue Bar Appears / Auto-Responder Not Working

A blue debugging bar appears or automated responses don't work when trying to use bot commands or auto-responses.

Check Chat Window Visibility
  • Make sure if using Youtube/Twitch that the pop-out chat window is open and visible
  • For some platforms, you may need to keep the main window open alongside the pop-out
Browser Compatibility
  • Auto-responder works best with Chromium-based browsers (Chrome, Edge, Brave)
  • Firefox has limited support for extension features

Frequently Asked Questions

Social Stream Ninja supports over 70 platforms including YouTube, Twitch, Facebook, Instagram, TikTok, Discord, Zoom, Google Meet, X (Twitter), WhatsApp, Telegram, and many more. For a complete list, see the Supported Platforms page.
The standalone app is recommended for most users as it:
  • Avoids browser throttling issues
  • Provides automatic updates
  • Offers window pinning and transparency features
  • Has better performance and stability
The browser extension is better if you:
  • Need to use it on multiple computers
  • Prefer not to install additional software
  • Want the latest updates immediately (manual installation)
No! One of the biggest advantages of Social Stream Ninja is that it doesn't require API keys or login credentials for most platforms. It works by capturing the chat data directly from the browser window or app interface. However, you do need to be logged into each platform to see the chat normally.
For the browser extension: To update the manually installed extension, download the latest version, replace the old files with the new ones, and then reload the extension or restart your browser. Do not uninstall the extension if you want to keep your settings. If using the Chrome Web Store version, it will update automatically but less frequently. For the standalone app: The app will update automatically when you restart it. You can also check for updates manually from the app's menu.
Yes! Social Stream Ninja supports two-way chat functionality for most platforms. When you're logged into a platform and have the appropriate permissions, you can send messages from the dashboard or via API commands that will appear in all connected chats simultaneously.
Absolutely! Social Stream Ninja is designed to work perfectly with OBS Studio and other streaming software. Simply add the overlay URL as a browser source in your streaming software. You can customize the appearance using CSS directly in OBS or via URL parameters.
Yes, Social Stream Ninja is completely free and open source under the GPLv3.0 License. There are no subscriptions, no hidden fees, and no feature limitations. The project is maintained by Steve Seguin with contributions from the community.
Social Stream Ninja has an active community on Discord where you can get help directly from the developer and other users. Join at discord.socialstream.ninja. You can also report issues on the GitHub repository.

Still Need Help?

Join our community Discord server where the developer and other users can help you troubleshoot issues.

Join Discord Community View Troubleshooting Guide