AI Co-host Guide

How the dock controls, private chat bot, and AI stage overlay work together.

What It Does

The AI co-host is split into a control side and a playout side. The streamer controls it from dock.html, while OBS captures cohost-overlay.html as the on-stream avatar and speech bubble.

Dock Controls

When the stage overlay is connected, right-click a chat message in the dock and choose Co-host. The dock can read the message, ask the AI for an answer, or create a light roast draft.

AI Stage Overlay

The overlay shows the avatar, speech bubble, and optional browser text-to-speech audio. This is the browser source you put in OBS.

Private Chat Bot

Answer and Light Roast use the configured LLM provider through the Private Chat Bot bridge. Read does not require AI.

Multimodal Co-host

cohost.html connects to the SSN live chat feed when opened with the same session. It defaults to monitor-only; use its Live Chat panel to let it answer questions.

Basic Setup

  1. Open the Streaming Chat dock with your session: dock.html?session=YOUR_SESSION_ID.
  2. For the default multimodal co-host, open cohost.html?session=YOUR_SESSION_ID and check the Live Chat status panel. It will monitor chat by default.
  3. Add the AI stage overlay to OBS: cohost-overlay.html?session=YOUR_SESSION_ID&tts.
  4. For AI answers, configure an LLM provider in the popup. For quick testing, choose SSN Hosted Trial LLM, which uses llm.socialstream.ninja.
  5. Enable Chat Bots and AI services > Chat Bot - Private Interface > Enable private chat bot option.
  6. Right-click a dock message and select Co-host. The menu is hidden until the stage overlay is detected.
cohost.html control page showing media devices, AI provider settings, system instructions, and live chat status
The cohost.html control page: pick your camera and microphone, choose an AI provider, set system instructions, and watch the Live Chat status panel.

Tip: Use the same session value for the dock and co-host overlay. If audio is wanted from OBS, include &tts on the overlay URL. The "Send primary chat bot replies to this overlay" option is not required for right-click co-host actions.

Simple AI Option

llm.socialstream.ninja is available through SSN Hosted Trial LLM as a free simple option for testing while the trial is available.

  • Open Chat Bots and AI services > Configure LLM Service Provider.
  • Select SSN Hosted Trial LLM (experimental).
  • Leave the endpoint, token, and model blank for the default trial setup.
  • For longer-term use, use your own token or local provider if the trial service is disabled or rate-limited.

Voice Conversation Support

  • SSN Desktop: Uses local Whisper with the microphone selected on cohost.html. The first use downloads about 42 MB; later transcription runs offline.
  • Chrome / Chrome extension link: The extension opens the hosted co-host page in a Chrome tab. Voice input uses Chrome Speech Recognition and the system-default microphone, may require internet, and does not use Desktop Whisper.
  • Other browsers: Voice recognition is not guaranteed. Typed co-host chat, live-chat input, camera/screen input, and configured LLM responses can still work without speech recognition.

The microphone meter only confirms that the page captured an audio stream. In Chrome, speech recognition separately uses Chrome's system-default microphone. In SSN Desktop, Diagnostics should show Listening (Desktop Whisper) and then the recognized text under Heard.

How The Pages Talk

The dock and overlay use the existing Social Stream session bridge. Messages are sent as overlayNinja payloads and targeted by label.

Read on Co-host: dock sends the selected chat message directly to cohost-overlay.html.

Answer / Light Roast: dock sends a private chatbot request to the SSN background service, shows the AI draft in the dock, then sends it to the overlay only after the streamer clicks Speak.

{
  "action": "cohostOverlay",
  "target": "cohost-overlay",
  "meta": {
    "command": "say",
    "text": "The line the avatar should say",
    "speak": true,
    "emotion": "happy"
  }
}

Available Actions

Action Requires Result
Read on Co-host Connected cohost-overlay.html Reads the selected chat message on the overlay.
Answer Private Chat Bot + configured LLM or Hosted Trial LLM Creates a short answer draft for streamer approval.
Light Roast Private Chat Bot + configured LLM or Hosted Trial LLM Creates a short, playful, PG draft for streamer approval.
Speak Approval panel draft Sends the approved text to the AI stage overlay.
Copy Approval panel draft Copies the draft without sending it to the overlay.

Status And Troubleshooting

  • If the Co-host menu is missing, the co-host overlay is not detected in the same session.
  • If Answer or Light Roast is disabled, the SSN bridge or Private Chat Bot is not available.
  • The primary chat bot overlay toggle is optional and does not enable dock right-click co-host actions.
  • If cohost.html is not seeing chat, confirm the URL has the same session as the popup and that the Live Chat mode is Monitor, Questions, or All.
  • If Desktop shows Listening (Desktop Whisper) but never fills Heard, confirm the selected microphone is not muted and allow the first model download to finish.
  • If Chrome never fills Heard, allow microphone permission, check the operating system's default microphone, confirm internet access, and verify that Chrome Speech Recognition is available.
  • If text appears but no audio plays, add &tts or &speak=1 to the overlay URL.
  • If AI requests time out, check that Social Stream is on, the session matches, Private Chat Bot is enabled, and the selected LLM provider is reachable.
  • If Local Gemma cannot download its model files from the default asset host, set the asset host to your own mirrored Gemma folder.
  • If the hosted trial AI stops responding, it may be disabled or rate-limited; switch to your own token, Ollama, or Custom API.
  • If multiple overlays are open, make sure the overlay label matches the dock target. The default label is cohost-overlay.

Useful URL Parameters

  • session=YOUR_SESSION_ID - required for the dock and overlay to share a room.
  • tts or speak=1 - lets the overlay speak with browser TTS.
  • label=cohost-overlay - sets the overlay target label.
  • name=NinjaBot - sets the display name on the overlay.
  • avatar=https://... - uses a custom avatar image.
  • position=bottom-right - controls stage placement.
  • scale=1.2 - scales the overlay.
  • status - shows connection/status text on the overlay.

Design Notes

  • The overlay is the playout source, so OBS captures the visual and audio output.
  • The dock is the control surface, so streamer approval stays off-stream.
  • Generated responses are not auto-spoken; the streamer must approve them first.
  • Non-standard command details live inside meta, keeping payloads predictable for overlays and automations.