For anyone who wants to create a custom theme/style/template for their chat stream, you can share them via adding them to this repository (in this folder) as a Pull Request.
To use a pre-made theme, you have two hosting options:
Use themes hosted on the official domain:
https://socialstream.ninja/themes/pretty.html?session=YOUR_SESSION_ID
Run themes from your local file system:
file:///C:/path/to/your/theme.html?session=YOUR_SESSION_ID
Important:
- Always append the session parameter correctly, regardless of hosting method.
- If Local Hosting, you may need to use &server mode if using this with OBS +v31
These themes include readme files, sample photos, and guides:
Add ?session=XXXXXXX to these URLs, replacing XXXXXXX with your session ID:
You can use a CSS designed for YouTube with our YouTube-structured overlay page:
Make your own custom theme. It's super easy when using an LLM AI service like Claude.ai 🤖
- Start with sampleoverlay.html
- Benefits:
- Compact, focused codebase
- Compatible with AI language models for assistance
- Contains instructional comments
- Single-purpose functionality
- Easier to maintain and debug
- Clear documentation of available options
-
IFRAME Overlay Method
- Uses IFRAMES and URL parameters to inject styles into the existing dock.html page
- Example: The
pretty.htmlstyle adds overlay images on top - Good for maintaining separation from core code
-
Built-in Style Options
- Use the app's menu settings or OBS stylesheet section
- Outside the scope of this document
-
Sample Overlay Modification
- Modify the simple boiler-plate overlay
- Best for custom themes with AI assistance
- For message structure details, see: Message Structure Documentation
-
YouTube-structured CSS-only mods
- You can use a CSS designed for YouTube with our YouTube-structured overlay page
- The YouTube-CSS friendly Overlay is here, which contains more information.
Warning: Direct modification of
dock.htmlis not recommended due to its complexity and size.
- Use the "Trigger a test message" button in the app menu
- Visit the sample API sandbox page
- Enable API support via app menu
- Create custom test messages near the bottom of the page
Starting with OBS v31, there are important considerations for custom themes:
- Cross-origin iframes will not load as browser sources in OBS v31 on PC and Linux (this was already the case for Mac)
- Custom themes using webRTC via VDO.Ninja iframes (hosted on vdo.socialstream.ninja) may be affected
-
Official Theme Hosting
- Submit your custom themes via PR to be hosted on socialstream.ninja
- Themes hosted on the official domain will work properly with OBS v31
- Approved PRs to main branch are automatically deployed and available via the website
-
WebSocket API Alternative
- For cases where iframes aren't suitable, use the WebSocket API
- Enable with the
&serverparameter or such, as the code requires to trigger. You may need to enable it in the extension/menu as well. - When using the Standalone app with local server option, use
&localserver&serverto utilize the local WebSocket server - May require additional setup if the websocket listening code is not already configured in sample code to be used; see dock.html for reference in that case.
When submitting themes:
- Include clear documentation
- Provide setup instructions
- Add sample screenshots if possible
- Test thoroughly
- Maintain core functionality
- Follow existing message structure
Benefits of contributing to the official repository:
- Automatic hosting on socialstream.ninja domain
- Included in official theme collection
- SSL/HTTPS support
- Consistent availability
- Included in any granted access permissions
- The P2P IFRAMES mode will work in OBS v31
Alternatively, you can self-host using local files, just ensure proper session parameter usage.
For support or questions, check the official documentation.
Contributions for more themes and styles are welcome!