Streaming Software Integration | steveseguin/captionninja | DeepWiki (2025)

This page explains how to integrate CAPTION.Ninja with popular streaming software platforms such as OBS Studio, vMix, and others. It covers the technical implementation of embedding caption overlays into your broadcasts, configuring browser sources, and managing display options. For information about customizing the appearance of captions, see CSS Styling. For advanced audio routing configurations, see Advanced Audio Setup.

Sources: README.md35-42

Integration Architecture

CAPTION.Ninja uses a browser-source based integration model with streaming platforms. The fundamental architecture involves a two-component system: a caption source that processes audio and generates text, and a caption display (overlay) that renders the text within your stream.

Sources: README.md16-25 overlay.html608-686

Basic Integration Process

Integrating CAPTION.Ninja with streaming software follows a consistent pattern regardless of which platform you're using:

Sources: README.md38-42

Step-by-Step Integration Instructions

1. Start the Caption Source:

   See Also

   Real weapons analysis
   • Open https://caption.ninja in Chrome or Edge
   • Grant microphone access when prompted
   • Configure any desired options (language, translation, etc.)

2. Obtain the Overlay URL:

   • The main interface will display a URL for the overlay
   • This URL contains a unique room ID parameter that connects your caption source to the overlay

3. Add to Streaming Software:

   • Add a new Browser Source in your streaming software
   • Enter the overlay URL in the source URL field
   • Configure dimensions and other browser source properties

Sources: README.md11-14 README.md38-42

OBS Studio Integration

OBS Studio is the most commonly used streaming platform with CAPTION.Ninja. Integration requires adding a Browser Source with specific configurations.

Adding CAPTION.Ninja to OBS

1. In OBS, click the "+" icon in the Sources panel

2. Select "Browser" from the sources list

3. Name your source (e.g., "Captions")

4. Configure the source properties:

   • URL: Paste the overlay URL from CAPTION.Ninja
   • Width: 1280 (recommended minimum)
   • Height: 720 (recommended minimum)
   • Use custom frame rate: Disabled
   • Control audio via OBS: Disabled
   • Refresh browser when scene becomes active: Optional
   • Shutdown source when not visible: Optional (may cause reconnection delay)

5. Position and resize the caption source in your scene as needed

Custom CSS in OBS

OBS allows applying custom CSS to Browser Sources, enabling styling without modifying the overlay URL:

1. In Browser Source properties, expand the "Custom CSS" field
2. Enter custom CSS to override default styles (examples below)

Sources: README.md128-146 overlay.html14-55

vMix Integration

vMix integration follows a similar pattern to OBS but with some platform-specific differences.

Adding CAPTION.Ninja to vMix

1. In vMix, click "Add Input"
2. Select "Browser" from the input types
3. Enter the overlay URL from CAPTION.Ninja
4. Set Width and Height (1280x720 recommended minimum)
5. Click "OK" to add the browser source
6. Position the source in your production as needed

Browser Input Settings

1. Right-click on the Browser input and select "Browser Settings"
2. Ensure "Transparent Background" is checked
3. You may need to use Custom CSS similar to OBS for optimal appearance

Sources: README.md38-42

Electron Capture for Desktop Applications

For scenarios where you need to display captions overlaid on desktop applications (not in a stream), CAPTION.Ninja can work with Electron Capture.

1. Download Electron Capture from GitHub
2. Launch the application
3. Enter the overlay URL from CAPTION.Ninja
4. Configure the window properties (transparent, click-through, etc.)
5. Position the window over the application requiring captions

Sources: README.md44-49

URL Parameters for Streaming Integration

The overlay system accepts various URL parameters that control its behavior. These parameters can be particularly useful when integrating with streaming software:

Sources: overlay.html609-632 README.md92-99

WebSocket Communication Architecture

The overlay integration relies on WebSocket communication between the caption source and display components. This architecture allows for real-time updates with minimal latency.

The overlay connects to the WebSocket server and implements reconnection logic with exponential backoff to handle connection interruptions.

Sources: overlay.html634-686

Audio Source Configuration for Streaming

CAPTION.Ninja normally uses your system's default microphone for speech recognition. When integrating with streaming software, you may want to caption different audio sources:

For detailed instructions on setting up virtual audio routing, see Advanced Audio Setup.

Sources: README.md52-70

Multi-Language Streaming Setup

For multilingual broadcasts, CAPTION.Ninja allows creating multiple overlay instances from a single caption source:

This configuration:

1. Runs a single caption source instance
2. Creates multiple browser sources with different translation parameters
3. Allows viewers to choose their preferred language stream

Sources: README.md86-108

Troubleshooting Stream Integration

Common issues when integrating CAPTION.Ninja with streaming software:

For persistent issues, check Troubleshooting for additional guidance.

Sources: overlay.html633-686 README.md224-230

Performance Considerations

When integrating CAPTION.Ninja with streaming software, consider these performance factors:

1. Browser Source Impact: Each browser source consumes system resources. For multi-language setups, consider using a secondary computer for translation overlays.

2. Reconnection Handling: The overlay implements automatic reconnection with exponential backoff, which helps recover from network interruptions without manual intervention.

3. Caption Timing: The showtime parameter controls how long captions remain visible. Setting an appropriate value can help with readability without cluttering the screen.

4. Memory Management: For long streaming sessions, consider periodically refreshing the browser source if you notice increased resource usage.

Sources: overlay.html633-686 overlay.html609-632