Design your own Social Stream overlays

Choose the overlay you want to redesign

You can change an existing page's colors, fonts, layout, artwork, and motion. The HTML file is the page; the OBS URL points to it and supplies session and display settings. For a small restyle, use OBS Custom CSS on the hosted page. For deeper changes, download the source and run your own copy.

These guides cover overlay families, including their themes. Pick the receiver for the feature you use: a chat page, a selected-message page, and a poll do not all consume the same input.

For a ready-made design start in the Galerie d’incrustations ou Galerie de modèles. For an existing StreamElements/Streamlabs chat skin, follow the import guide. The imported self-contained HTML has its own export/setup instructions.

1. Download the actual files

1. Télécharger le ZIP du code bêta, or open the beta repository et choisissez Code → Download ZIP.
2. Extract the ZIP into a folder you can keep, such as C:\SSN\social_stream-beta\. Do not edit inside the compressed archive. These are page source files; editing a separate copy does not require reinstalling SSN.
3. Find the file shown in the table above. Duplicate it beside the original: for example poll.html devient my-poll.html. Pour themes/featured-styles/featured-modern.html, keep the copy in themes/featured-styles/.
4. Open the copy in a text/code editor. Give your AI tool access to that file and the referenced styles/scripts it needs. Save HTML as .html, not .html.txt.

Keep the extracted folder structure. A single downloaded HTML file may load scripts, stylesheets, fonts, images, audio, or JSON beside it. GitHub's page view and a browser's “Save page” are not a dependable complete bundle. Each type guide identifies useful files, but the full extracted folder is the simplest way to retain dependencies.

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

A reference such as ../../shared/utils/chatHtml.js is relative to the page that loads it. Moving that page to the root breaks the path. Copy local artwork and fonts into the project too, then use relative URLs. Keep downloaded versions together; your edited copy will not automatically receive future SSN fixes.

2. Keep the session and connection settings

Start SSN, connect a source, and confirm the original overlay works. Copy the complete generated link from the relevant SSN tool. The value after session= identifies your SSN session; it is not a YouTube channel, a Twitch username, a filename, or the poll's title.

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

The example uses placeholders. SSN and the page must use the same actual session and any configured password. Changing the filename does not change the session. Keep SSN and capture running: an overlay receives data; it does not capture platform chat by itself.

• ? starts the query; subsequent settings use &. Copy values instead of retyping them. In an HTML source attribute, write &; in the browser/OBS URL field use an ordinary ampersand.
• Preserve transport settings: server, server2, server3, local endpoints, labels, and version values are page-specific. Do not add a server flag just because another overlay supports it.
• Preserve fragments too: everything after # can matter. AI Event Overlay, for example, uses a private #aieventauth=... display token.
• Use placeholders in shared examples. Keep your real session link, password, and private display tokens out of public screenshots, repositories, and AI prompt examples.

When a copy stays blank, check the original generated link first. Some pages prompt for missing settings; others remain hidden or redirect. Supplying the correct session explicitly avoids relying on those page-specific defaults.

3. Open your file in OBS

Open the edited HTML directly from your computer. There is no server to install or start.

1. Drag your copied HTML file into Chrome or Edge. Copy its full address from the address bar; it starts with file:///.
2. Copy everything from ? onward in your working SSN overlay link and add it to the end of that file address. This keeps your session, password, other settings, and any # ending.
3. Open the combined address in your browser to test it.
4. Dans OBS, ajoutez une Source navigateur. Laissez Fichier local unchecked and paste the full address into URL. Set the width and height for your design.

For example, this SSN link:

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

becomes this address for a downloaded poll copy on Windows:

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

Use your actual file address and copied settings. On macOS the address starts with file:///Users/...; on Linux it usually starts with file:///home/.... Copying the browser address handles spaces and slashes for you.

Set this up once. OBS saves the address with the source. Keep the downloaded folder in the same place and keep SSN and your chat source running when using the overlay. After saving a design change, use Actualiser le cache de la page actuelle in the source properties.

Why leave Local file unchecked? The URL field lets you include ?session=.... Selecting the HTML with the file picker alone does not add those settings.

<!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 documents its file/URL modes, dimensions, Custom CSS, and refresh controls in the Browser Source reference.

4. Change the design, or ask AI to do it

For a CSS-only change, keep the hosted link and use OBS's CSS personnalisé field. It applies only to that source, so a normal browser opening the same URL will not show those overrides. For an edited HTML file, append overrides after its existing styles, or link a local stylesheet after them. Supply your logo, font files, brand colors, canvas size, and a visual reference.

Some pages support &css= ou &b64css=; support is per page. poll.html, for example, reads neither. Check the page's parser before using URL options. A web page cannot generally load an arbitrary font or image from another computer's local disk.

When changing markup, preserve IDs/classes referenced by scripts. If JavaScript rebuilds an element on each update, permanent artwork must live outside that element or be recreated by the renderer. Copy a shared stylesheet/script and change your page's reference if you want the edit to affect only your design.

Use the type-specific prompt in the guides above, or start with this general prompt:

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.

The type guides describe the real trigger to preserve. Do not accept a design that only works because it hard-codes sample messages. Keep a copy of the original file and compare the edited display using the same test inputs.

5. Keep incoming chat from becoming code

Messages, names, titles, amounts, metadata, and media links can originate with viewers or external services. Sanitize at the point where the custom renderer inserts them. A string received through SSN is not permission to execute it. Use plain DOM text for plain fields; use the packaged sanitizer for the message body's supported HTML. See OWASP's explanation of safe sinks and HTML sanitization.

In SSN, textonly applies only to chatmessage. When true, render that body as literal text. Otherwise it may contain emotes and allowed formatting. Render other normal fields as text; media fields such as chatimg et contentimg are URLs/data, not HTML snippets.

<!-- 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>

Keep an existing equivalent sanitizer rather than adding a second one. For nested files adjust relative script paths. Build avatars and links with DOM properties after validating the URL under the page's existing media/link policy. Do not interpolate raw names into attribute strings or raw colors into style markup; validate styles before setting individual properties. HTML sanitization does not make a string safe to execute as JavaScript or an AI instruction.

Test the renderer in an isolated preview

• Use a plain name such as Guest <b>One</b>: the brackets should remain text.
• Essayez chatmessage: "<b>Hello</b>" avec textonly: true, then false. Literal markup and allowed formatted content should take their respective paths.
• Check a supported emote and an image-only message so safety changes do not remove those features.
• Have the AI test a harmless probe such as <img src=x onerror="window.__ssnInjectionProbe=1"> in the changed renderer. It must not execute, set the marker, or leave executable event attributes. Test a script-scheme link as well. Run probes locally, not in public chat.

A passing probe only checks the paths exercised. Keep tests focused on the renderers and fields changed by the design.

6. Test layout, connection, and OBS separately

1. Layout: use the page's documented preview/demo mode, where available, or fictional local samples. Test long names/messages, missing avatars, empty data, and the expected number of rows.
2. SSN delivery: keep SSN active and use Créer un message de test (Create Test Message) with the same session. The usual Extension API ingest mode needs contrôle distant de l’extension par API (remote API control of extension) enabled. Use an isolated test setup; submitted tests can trigger configured automations.
3. The actual trigger: feature a Dock message for a featured card, send a poll vote for a poll, select a winner for a giveaway, change ticker text for a ticker, or start a timer for a timer. Plain chat is not a universal test.
4. Real capture: confirm an actual source message/event reaches the original and edited page. A mock event proves rendering, not platform capture.
5. OBS : check the source at its final size, transparency, animations, audio, fonts, and layering. Exercise show/hide, clear/reset, and a refresh. The browser and OBS have separate storage and sessions; browser login or localStorage is not automatically shared.

For pages that collect data in memory, unloading or refreshing can lose state. Check the type guide before enabling automatic refresh or shutdown-when-hidden. Host-managed displays have different recovery behavior. Remove demo/preview flags before expecting live data.

Useful files and references to give your AI

• docs/event-reference.html: canonical fields, named events, metadata, media, and donation values.
• docs/customoverlays.md: custom receivers and connection examples.
• Compatibilité des événements et alertes: which events/fields a design can expect from a source.
• Test-message guide et createtestmessage.html: sample payloads and delivery modes.
• libs/objects.js et shared/utils/chatHtml.js: packaged display sanitization.
• shared/utils/chatBadges.js et shared/utils/contentImage.js: existing badge and image handling.
• js/transport-dedupe.js, js/local-server-url.js, et shared/overlay-control-transport.js: existing transport support when loaded by your page.
• currency.js: preserve hasDonation for display and honor a valid numeric USD donoValue, including zero.
• Event Flow et Commandes et API: reuse existing controls when the design needs a trigger.

Give the actual overlay source and its referenced CSS/JS as well as these docs. An event reference alone does not describe a poll's control state or every overlay's private rendering structure.

When the copy does not work

Stop at the smallest confirmed issue. A restyle should not require changing capture scripts or inventing new event fields. If sharing a public fork, include its supporting assets and keep private launchers out of that upload.