Core Concepts

OpenBroadcaster is built around five core systems that always interact:

1. Library – permanent audio database
2. Queue – live broadcast timeline
3. Playback Engines (Decks) – audio output
4. Automation Controllers – AutoDJ & Scheduler
5. Distribution Systems – Encoder, Twitch, Overlay, WordPress

These systems interact to provide full control of a broadcast session.

The Golden Rule

The Queue is the truth.

From the code:

• Decks never pick songs on their own
• AutoDJ only inserts tracks into the Queue
• Twitch song requests only add entries into the Queue

The Queue feeds:

• Deck A / Deck B
• Encoder streams
• OBS overlays
• Twitch now playing
• WordPress plugin metadata

Persistent vs Live Data

• Persistent: Library entries, categories, settings, encoders, scheduler definitions
• Live (Session-based): Queue contents, active deck state, cartwall playback, Twitch chat state

Closing the app resets live data but preserves persistent data.

UI → ViewModel → Core

Every screen follows this pattern:

User clicks UI
↓
ViewModel validates action
↓
Core service executes logic
↓
State updates
↓
UI refreshes automatically

Key points:

• Buttons do not directly perform work
• ViewModels determine if an action is allowed
• Core services handle the actual logic

Audio Device Mapping

Each audio bus is explicitly assigned:

• Program Bus – main output to speakers / broadcast mix
• Encoder Bus – output to Shoutcast/Icecast / Twitch / Relay
• Cue Bus – isolated preview for DJs

If a device is misconfigured, audio may appear to work but will not be streamed or previewed correctly.

Music Library

The Music Library is the heart of OpenBroadcaster. All automation, scheduling, and user requests pull from this database.

Supported Formats

• MP3, WAV, FLAC, OGG, AAC, WMA
• Metadata extraction for artist, album, title, genre, and duration
• Album art automatically displayed where available

Features

• Category tagging – required for AutoDJ and Scheduler
• Smart search and filtering – by artist, title, category, or custom tags
• Drag-and-drop playlist creation
• Multi-file import – bulk addition supported
• Automatic duplicate detection
• Manual editing of metadata directly in the app

Best Practices

• Use consistent categories for AutoDJ rotation accuracy
• Keep metadata clean to avoid duplicate or missing tracks in Scheduler
• Regularly rescan folders after adding new music to keep the library current

Decks & Playback

OpenBroadcaster uses **two independent decks** for live playback.

Deck Features

• Deck A and Deck B – switchable for live or automated playback
• Transport controls – play, pause, stop, skip, cue
• Real-time display – elapsed time, remaining time, and track metadata
• Crossfade control – smooth transitions between decks
• Deck preview – allows DJ to listen without sending to program bus

Loading Tracks

• Manual drag from Library or Queue
• AutoDJ auto-populates empty decks
• Scheduler can override deck content at specific times

Hotkeys

• Customizable per deck for play, pause, stop, crossfade, and cart triggers
• Supports modifier keys (Shift, Ctrl) for alternate actions

Queue System

The Queue represents the broadcast timeline. All tracks from AutoDJ, Scheduler, Requests, and manual DJ actions flow through the queue before playback.

Queue Features

• Manual drag-and-drop ordering
• Queue items labeled by source: AutoDJ, Request, Scheduler, Manual
• Next track previews – hover to see upcoming metadata
• AutoDJ fills gaps when queue is empty
• Scheduler insertions are prioritized over AutoDJ
• Queue locking – prevents accidental reordering of scheduled tracks

Best Practices

• Always monitor the queue during live shows – it’s the single source of truth
• Use labels and colors (if enabled in Themes) to differentiate source type
• Ensure Scheduler and AutoDJ rules are configured before going live to avoid conflicts

AutoDJ System

The AutoDJ engine ensures continuous, automated playback when live DJs are not on air.

How AutoDJ Works

• Fills empty queue slots automatically
• Uses category rotation rules defined in the library
• Applies artist separation to prevent repeats in short succession
• Weighted randomization – higher priority categories play more frequently
• Tracks are inserted into the Queue, not directly into decks

Configuration

• Define categories in the Music Library (e.g., Rock, Metal, Indie)
• Assign category weights – determines probability of playback
• Exclude artists or tracks for specific time periods if needed
• Enable/disable AutoDJ per deck in the Settings panel

Best Practices

• Always test AutoDJ on a mock schedule before going live
• Ensure categories are populated with enough tracks to prevent repeats
• Combine with Scheduler for optimal broadcast structure

Scheduler / Clockwheel

The Scheduler allows time-based automation for your station using a “clockwheel” approach.

How It Works

• Time slots are divided into hourly blocks
• Tracks, jingles, or show segments are assigned to specific times
• Scheduler inserts content into the Queue with priority over AutoDJ
• Supports repeating blocks, special shows, and holiday overrides

Configuration Steps

1. Open the Scheduler panel from Settings → Scheduler
2. Define hourly blocks and assign categories or playlists
3. Set start/end times for each block
4. Enable automatic insertion into the Queue
5. Preview schedule to ensure proper ordering

Best Practices

• Combine Scheduler with AutoDJ to fill unexpected gaps
• Use descriptive labels for blocks (e.g., “Morning Rock Hour”)
• Verify time zone settings to match your local broadcast time
• Test schedule transitions using the “Preview Next” feature

Audio Routing

OpenBroadcaster separates audio into multiple buses for flexible DJ and streaming control.

Audio Buses

• Program Bus – main output to speakers and broadcast mix
• Encoder Bus – feeds all streaming outputs (Shoutcast, Icecast, Twitch)
• Cue Bus – isolated preview for DJ headphones or monitoring

Routing Rules

• Deck output is always sent to the Program Bus
• Encoder Bus receives only tracks that are flagged to stream
• Cue Bus can be previewed without affecting Program or Encoder audio
• Microphone or external inputs are mapped to Program Bus and optionally to Encoder Bus

Best Practices

• Verify audio devices before going live to avoid no-audio situations
• Keep Cue Bus volume independent for safe pre-listening
• Use separate physical outputs if possible to avoid feedback loops
• Monitor the encoder meters to ensure stream is live

Cartwall

The Cartwall allows instant playback of jingles, sound effects, or preloaded clips.

Features

• Configurable pad layout
• Multiple simultaneous carts can play at once
• Hotkey assignment for each pad
• Loop mode for repeating clips
• Visual indicators when carts are active

Using the Cartwall

• Drag audio files from Library or Queue into Cartwall pads
• Assign hotkeys via Settings → Hotkeys panel
• Trigger playback with mouse or keyboard
• Supports crossfade with Program Bus if deck audio is playing
• Can be used live with AutoDJ or Scheduler without disrupting queue

Best Practices

• Organize pads by type (Jingles, IDs, FX) for fast recall
• Keep important station IDs on the top row for immediate access
• Test hotkeys for conflicts with deck or AutoDJ controls
• Combine with Scheduler for automated jingles at scheduled times

Encoders & Streaming

OpenBroadcaster supports multiple encoders simultaneously for internet radio and Twitch streaming.

Supported Encoder Types

• Shoutcast v1 & v2
• Icecast v2
• Twitch live streams (via OBS relay or direct connection)
• Multiple simultaneous encoders supported

Configuration

1. Open the Encoder panel from Settings → Encoders
2. Create a new encoder profile and select the type
3. Enter server address, port, mount point (for Icecast), and authentication
4. Choose audio format (MP3, AAC, OGG)
5. Map output bus (Program Bus usually)
6. Enable auto-reconnect and fallback options

Encoder Monitoring

• Real-time level meters for each encoder
• Status indicators: Connected, Streaming, Error
• Automatic logging of errors to logs/encoder.log

Best Practices

• Test each encoder individually before going live
• Use SSL/TSL if available for secure streaming
• Keep metadata clean and consistent for now playing updates
• Monitor CPU usage – multiple encoders can be resource intensive

Metadata Management

Metadata is critical for proper song information on streams and overlays.

How It Works

• Tracks automatically send artist/title/album info to all encoders
• OBS overlays and WordPress plugin pull metadata from local HTTP server
• Twitch now playing messages use the same metadata source

Manual Overrides

• Click a track in Library or Queue → Edit Metadata
• Overrides apply immediately to encoder and overlay updates
• Useful for correcting incorrect ID3 tags or special announcements

Best Practices

• Ensure all tracks have proper ID3 tags before importing
• Use consistent capitalization and spelling for artist names
• Check now playing updates on Twitch or your stream website to confirm accuracy

Twitch Integration

OpenBroadcaster connects directly to your Twitch channel to provide live chat, now playing, and loyalty tracking.

Features

• Live chat integration for DJ interaction
• Now playing display with auto-update
• Moderation features: auto-moderate requests, blacklist, and cooldown enforcement
• Supports multiple Twitch accounts for co-hosting or multi-channel streaming
• Loyalty points or viewer tracking integrated with requests

Setup

1. Open Settings → Twitch Integration
2. Authenticate with your Twitch account
3. Select the channel to connect
4. Enable chat monitoring and request tracking
5. Configure cooldowns and maximum simultaneous requests

Best Practices

• Test chat connectivity before going live
• Set reasonable request cooldowns to prevent spam
• Use moderation tools for new channels
• Verify OAuth tokens periodically to prevent disconnects

Song Requests & Cooldowns

Song requests from Twitch viewers integrate directly into the Queue.

How Requests Work

• Users submit requests through Twitch chat commands
• OpenBroadcaster validates against library categories and track availability
• Accepted requests are inserted into the Queue
• Cooldown timers prevent repeated requests by the same user
• Admins can manually approve or reject requests in real-time

Configuration

• Enable requests in Twitch Integration panel
• Define cooldown duration per user (seconds/minutes)
• Set maximum requests per user per day
• Choose how requests are prioritized in the Queue (manual, AutoDJ override, or scheduler override)

Best Practices

• Monitor request spam in chat with cooldown settings
• Test request insertion during a mock live session
• Combine with Scheduler for time-specific priority tracks

Chat Commands & Interaction

OpenBroadcaster provides pre-defined commands for Twitch viewers to interact with your station.

Common Commands

• !request [song] – submit a song request
• !nowplaying – displays the current track
• !next – displays the upcoming track
• !playlist – shows the current queue or playlist
• Custom commands can be added in the Settings → Twitch Commands panel

Moderation & Safety

• Blacklist offensive words or users
• Automatic cooldown enforcement
• Commands limited to subscriber/moderator roles if needed
• Logs all commands for later review in logs/twitch.log

Best Practices

• Customize commands to match your station branding
• Keep command list simple for viewers
• Test commands in a private channel before live usage

OBS Overlays

OpenBroadcaster provides ready-to-use HTML overlays for OBS or other streaming software.

Features

• Now Playing – current track metadata (artist, title, album art)
• Next Tracks – preview upcoming queue items
• History – last X tracks played
• Song Requests – live requests display
• Customizable CSS / theme files
• Works locally or remotely via Web API

Setup Steps

1. Open the Overlay panel in OpenBroadcaster
2. Select the overlay type (Now Playing, Next, History, Requests)
3. Copy the local URL (e.g., http://localhost:8080/overlay/nowplaying.html)
4. In OBS, add a Browser Source → paste the URL
5. Adjust width, height, and CSS as desired
6. Optional: enable remote access for co-hosts or web display

Best Practices

• Use a fixed width/height to prevent scaling issues in OBS
• Customize CSS for your station branding (colors, fonts, logos)
• Test overlays with live playback to ensure metadata updates in real-time
• Combine multiple overlay types in stacked layers for full studio dashboards

Web API

The internal Web API exposes live broadcast data for overlays, WordPress, or other web services.

Endpoints & Usage

• /nowplaying – returns current track info (JSON)
• /next – returns upcoming queue items
• /history – returns last X tracks
• /requests – returns live requests
• Can be accessed via HTTP or WebSocket for dynamic overlays

Best Practices

• Secure your local or remote API with authentication tokens if exposing publicly
• Use browser-based overlays to avoid installing extra software
• Test updates in real-time to ensure overlays stay in sync with Queue
• Combine with Twitch integration for a live interactive broadcast experience

WordPress Plugin Integration

OpenBroadcaster provides a dedicated plugin to display live broadcasts and interact with your audience directly on your WordPress website.

Features

• Now Playing display on posts or pages
• Live song requests submission from site users
• Queue and playlist overview for visitors
• Supports both Direct and Relay connection to OpenBroadcaster
• Easy embedding via shortcodes or Gutenberg blocks

Installation

1. Download the wordpress-plugin-v2 folder from the repo
2. Upload to your WordPress site → Plugins → Add New → Upload
3. Activate the plugin
4. Configure connection settings (Direct or Relay)
5. Place shortcodes on pages or in widgets where you want live data displayed

Shortcodes

Shortcodes allow you to embed OpenBroadcaster data anywhere on your WordPress site.

Available Shortcodes

• [ob_nowplaying] – shows current track
• [ob_next] – displays next tracks in queue
• [ob_history] – shows last X played tracks
• [ob_requests] – allows users to submit live requests
• [ob_queue] – full queue display (admin/moderator only optional)

Usage Tips

• Wrap shortcodes in divs with custom CSS for styling
• Use shortcodes in posts, pages, or Elementor HTML widgets
• Combine multiple shortcodes on a page to create a full live broadcast dashboard

Direct vs Relay Mode

The plugin supports two connection modes:

Direct Mode

• WordPress communicates directly with the OpenBroadcaster app
• Requires local network access or public IP with open ports
• Lower latency, real-time updates
• Recommended if the WordPress site is on the same LAN or has secure direct access

Relay Mode

• Uses the OpenBroadcaster.RelayService to tunnel data
• Allows connections across firewalls or NAT without opening ports
• Ideal for public sites where direct connection is not possible
• May add minimal delay (a few seconds)

Best Practices

• Use Direct mode when possible for fastest updates
• Relay mode is safest for public-facing websites
• Test shortcodes after connecting to ensure live data is displayed correctly
• Enable caching carefully; overlays and requests must remain real-time

General Settings

• Language: select UI language
• Theme: dark or light, custom CSS support
• Default audio devices: assign Program, Encoder, Cue buses
• Logging level: Info, Debug, Warning, Error
• Auto-start behavior: start minimized, auto-connect encoders, auto-enable AutoDJ

Decks

• Enable/disable Deck A or Deck B
• Crossfade duration: seconds
• Hotkey assignments: play, pause, stop, cue, skip
• Deck preview: assign Cue Bus output
• Default load behavior: Auto-load last track on start

AutoDJ

• Enable AutoDJ per deck
• Category weights: priority for rotation
• Artist separation: prevent repeat within X tracks
• Exclude tracks/artists: blacklist for AutoDJ
• Queue insertion rules: insert at end, top, or after currently playing

Scheduler

• Enable/disable Scheduler
• Time zone configuration
• Hourly block definitions: categories, playlists, special shows
• Repeat blocks: daily, weekly, custom
• Queue priority: Scheduler inserts override AutoDJ
• Preview schedule: display next scheduled tracks

Twitch

• OAuth authentication: connect your Twitch account
• Channel selection: primary streaming channel
• Enable chat monitoring
• Request settings: max requests, cooldown per user
• Loyalty points integration: optional
• Command settings: custom commands and moderation

Encoders

• Add/remove encoder profiles: Shoutcast/Icecast/Twitch
• Audio format selection: MP3, AAC, OGG
• Server configuration: IP, port, mount, authentication
• Output bus selection: Program Bus, Encoder Bus, or both
• Reconnect options: auto reconnect on failure
• Logging: per encoder connection logs

Cartwall

• Pad layout: rows × columns
• Assign tracks to pads via drag-and-drop
• Hotkey mapping per pad
• Loop mode: enable/disable for selected pads
• Volume adjustment per pad
• Preview output: Cue Bus vs Program Bus

Audio Routing Issues

Common problems and solutions:

• No audio on stream: Check Encoder Bus mapping; ensure Program → Encoder routing enabled.
• Deck preview not audible: Verify Cue Bus device assignment and volume levels.
• Feedback loop: Ensure Program Bus is not routed back to Cue or external mic input.
• Device not detected: Refresh audio devices in Settings → General, restart app if needed.

Encoder / Streaming Errors

• Cannot connect to server: Verify IP/port/mount/credentials; check firewall.
• Metadata not updating: Ensure tracks in Queue have proper ID3 tags; check encoder mapping.
• High CPU / dropped frames: Reduce number of simultaneous encoders or lower bitrate.
• Reconnect fails: Enable auto-reconnect and test network stability.

Twitch Integration Issues

• Chat not loading: Verify OAuth token and correct channel selection.
• Requests not appearing: Ensure Request system enabled; check cooldown and max request limits.
• Commands ignored: Verify command is enabled and user role matches allowed roles.
• Viewer tracking missing: Confirm Twitch account has required permissions and Loyalty system active.

AutoDJ & Queue Conflicts

• Scheduler overrides AutoDJ: This is intended; ensure AutoDJ is configured to fill gaps only.
• Queue items disappear: Check if Scheduler or manual deck actions are removing tracks.
• Repeats in AutoDJ: Increase artist separation or populate library with more tracks.
• Requests not inserted: Verify request category exists in Library and queue rules allow insertion.

General Best Practices

• Regularly back up config.ini and library database
• Use consistent metadata to avoid broken now playing updates
• Test all features in a private session before going live
• Monitor logs (logs/encoder.log, logs/twitch.log, logs/app.log) for errors
• Keep the app updated to latest version for bug fixes and new features
• Verify network and firewall settings if using remote streaming or WordPress integration