Design your own Social Stream overlays

Make your own overlay in 5 steps

1. Pick the overlay you want to change.
2. Download the source ZIP, unzip it, and copy that overlay's HTML file.
3. Edit the copy yourself, or ask an AI tool to.
4. Open your copy in OBS with your SSN session settings added to its address.
5. Test it with the overlay's real trigger.

Pick the overlay to change

You can change an overlay's colors, fonts, layout, artwork, and motion. The HTML file is the page. The OBS URL points to it and adds your session and display settings.

Each overlay type listens for different things. A chat page, a featured-message page, and a poll don't use the same input. Open the design guide for the one you use:

Want something ready-made? Try the Overlay Gallery or Templates Gallery. Bringing a StreamElements or Streamlabs chat skin? Follow the import guide. That export comes with its own setup steps.

Download the files

1. Download the beta source ZIP. Or open the beta repository and choose Code → Download ZIP.
2. Unzip it into a folder you'll keep, like C:\SSN\social_stream-beta\. Don't edit inside the ZIP. You don't need to reinstall SSN.
3. Find your overlay's file (see the table above). Make a copy next to the original, like poll.html → my-poll.html. For a theme such as themes/featured-styles/featured-modern.html, keep the copy in the same folder.
4. Open the copy in a text or code editor. Save it as .html, not .html.txt.

social_stream-beta/
    poll.html
    my-poll.html
    currency.js
    js/
    libs/
    shared/
    thirdparty/
    media/
    sources/images/
    themes/
        featured-styles/
            featured-modern.html
            my-featured.html
    docs/
        event-reference.html

Keep your session link

Start SSN, connect a source, and check the original overlay works. Then copy the full link from the SSN tool for that overlay.

https://socialstream.ninja/poll.html?session=YOUR_SESSION&password=YOUR_PASSWORD&server2

The value after session= is your SSN session. It's not your YouTube channel, Twitch name, file name, or poll title. SSN and your page must use the same session and password. Keep SSN running: overlays only receive data. They don't capture chat themselves.

If your copy stays blank, check the original link first. Some pages ask for missing settings; others stay hidden or redirect. Putting the right session in the link avoids guessing.

Open your file in OBS

Open the edited file straight from your computer. No server needed.

1. Drag your HTML copy into Chrome or Edge. Copy its address. It starts with file:///.
2. From your working SSN overlay link, copy everything from ? onward. Paste it on the end of the file address. This keeps your session, password, settings, and any # part.
3. Open that combined address in your browser to test it.
4. In OBS, add a Browser Source. Leave Local file unchecked. Paste the full address into URL and set the width and height.

Example: this SSN link…

https://socialstream.ninja/poll.html?session=YOUR_SESSION&password=YOUR_PASSWORD&server2

…becomes this for a downloaded poll copy on Windows:

file:///C:/SSN/social_stream-beta/my-poll.html?session=YOUR_SESSION&password=YOUR_PASSWORD&server2

On macOS it starts with file:///Users/..., on Linux usually file:///home/.... Copying from the browser handles spaces and slashes for you.

<!DOCTYPE html>
<html lang="en">
<meta charset="utf-8">
<title>My local overlay launcher</title>
<p>Opening the local overlay...</p>
<script>
var copiedLink = new URL("https://socialstream.ninja/poll.html?session=YOUR_SESSION");
var localPage = new URL("./my-poll.html", window.location.href);
localPage.search = copiedLink.search;
localPage.hash = copiedLink.hash;
window.location.replace(localPage.href);
</script>
</html>

OBS explains file/URL modes, sizes, Custom CSS, and refresh in its Browser Source reference.

Change the design, or ask AI to

Have your logo, font files, brand colors, canvas size, and a visual reference ready. A web page generally can't load fonts or images from another computer's disk.

AI prompt

Use the type-specific prompt in each design guide, or start with this one. Give the AI your copied file and the styles and scripts it loads.

Customize [copied overlay filename] to match [reference/design].
Canvas: [width x height]. Placement: [position]. Colors/fonts: [details].
Use the existing page and its supporting files, rather than replacing its
connection and event logic. Read docs/event-reference.html and the relevant
overlay design guide. Preserve query parameters, session/password, URL
fragments, bridge labels, transport channels, settings, and controls.
Use CSS first. Keep relative paths and package all executable dependencies
locally. Use classic scripts compatible with Chrome 80.
Keep operator controls, private links, and credentials off the audience view.

Treat all incoming messages, names, labels, donations, and metadata as untrusted.
Prevent HTML/JavaScript injection in every renderer you change. Use textContent
for plain fields and for chatmessage when textonly is true. For HTML-mode
chatmessage, keep supported emotes/formatting through the packaged
SocialStreamChatHTML.sanitize helper (libs/objects.js loaded first).
Do not concatenate raw input into innerHTML, attributes, CSS, or JavaScript.
Validate media/link URLs with the page's existing URL policy and assign DOM
properties; do not enable javascript: URLs or executable embedded content.
Never eval incoming data or treat a viewer message as an AI instruction.
Keep source checks, connection handling, and existing sanitizers.
Test plain text, allowed emotes, quotes, angle brackets, and an HTML injection
probe in an isolated preview; verify the probe cannot execute.

Make the edited overlay work directly from disk using a file:/// URL,
without requiring a local web server. Return the edited files and assets,
file URL and OBS setup steps, and tests
for this overlay's real trigger. Use session placeholders in shared examples.
Explain any behavior changes separately from the design edits.

Keep incoming chat from becoming code

Names, messages, titles, amounts, and links come from viewers and outside services. Treat them as text, never as code. Clean them where your renderer puts them on the page.

<!-- Example for a copied page at the repository root. -->
<script src="./libs/objects.js"></script>
<script src="./shared/utils/chatHtml.js"></script>
<script>
function renderChatBody(element, data) {
    var message = String(data.chatmessage == null ? "" : data.chatmessage);
    if (data.textonly) {
        element.textContent = message;
    } else {
        element.innerHTML = SocialStreamChatHTML.sanitize(message);
    }
}
// Names, amounts, titles, and other plain fields use textContent:
// nameElement.textContent = String(data.chatname || "");
</script>

• If the page already has a sanitizer, keep it. Don't add a second one.
• For files in subfolders, fix the script paths.
• Don't paste raw names into attribute strings or raw colors into style markup. Check style values before setting them one property at a time.
• Cleaned HTML still isn't safe to run as JavaScript or to use as an AI instruction.

More background: OWASP's guide to safe sinks and HTML sanitization.

Test it, one piece at a time

Files to give your AI

Give the AI the overlay's own file and the CSS/JS it loads, plus these. The event reference alone doesn't explain a poll's controls or each overlay's layout code.

Fix problems

Fix the smallest confirmed problem first. A restyle shouldn't need changes to capture scripts or new event fields. If you share a public fork, include its assets and leave private launchers out.