CasparCG-OBS Control Client

March 16, 2026 ยท View on GitHub

A Python GUI application for seamless integration between CasparCG media servers and OBS Studio. This client automates the complete workflow of transitioning OBS scenes, playing media through CasparCG, and transitioning backโ€”all with precise timing control.

Caution

This project has never been tested in a production environment. Expect bugs and potential issues. The project is no longer maintained.

๐ŸŽฏ Key Features

Connection Management

  • โœ… Dual Connection Monitoring: Real-time status for both CasparCG and OBS
  • โœ… Auto-Reconnect: Attempts reconnection every 5 seconds on connection loss
  • โœ… Visual Indicators: Green/red status dots for instant connection feedback

Media Management

  • ๐Ÿ“ Media Library Browser: View all available media from CasparCG server
  • ๐Ÿ–ผ๏ธ Thumbnail Support: Visual preview of media files (framework ready)
  • ๐Ÿ”„ Auto-Refresh: Media list updates every 60 seconds automatically
  • โš ๏ธ Existence Validation: Visual warnings for missing media files
  • ๐ŸŽฏ Drag & Drop Playlist: Intuitive playlist creation

Playback Control

  • ๐ŸŽฌ Automated Workflow:
    1. Transition OBS to CasparCG scene
    2. Play media in CasparCG
    3. Monitor playback progress
    4. Transition back before video ends
  • โฑ๏ธ Precise Timing: Configure exact moment for back-transition
  • ๐Ÿ“Š Real-Time Progress: Live playback position and time remaining
  • ๐Ÿ”Š Audio Levels: Visual audio level meters (via OSC)
  • โฏ๏ธ Playback Controls: Play, stop, and navigation buttons

Settings & Persistence

  • ๐Ÿ’พ Auto-Save: Settings and playlist saved automatically
  • ๐Ÿ“‹ JSON Configuration: Easy to backup and share
  • ๐Ÿ”ง Comprehensive Settings: Control all aspects of both systems
  • ๐Ÿ’ผ Session Restoration: Automatically loads last configuration

User Interface

  • ๐Ÿ“ Responsive Design: Scales to 1/3 screen width or full screen
  • ๐ŸŽจ Modern Qt Interface: Clean, professional appearance
  • ๐Ÿ“ฑ Collapsible Panels: Hide sections for more workspace
  • ๐Ÿ–ฑ๏ธ Intuitive Controls: Familiar drag-drop and click interactions

๐Ÿš€ Quick Start

Easiest Way - Use Run Script

macOS/Linux:

./run.sh

Windows:

run.bat

The script will automatically set up the virtual environment if needed and launch the application.

Manual Setup

  1. Run Setup Script:

    ./setup.sh          # macOS/Linux
setup.bat           # Windows

  2. Run Application:

    source venv/bin/activate    # Activate venv
python main.py              # Start app

๐Ÿ“‹ Requirements

Software

  • Python 3.8+ (3.10 recommended)
  • CasparCG Server 2.3+ (for media playback)
  • OBS Studio 28+ with WebSocket plugin enabled

Python Dependencies

  • PyQt6 - GUI framework
  • obs-websocket-py - OBS control
  • python-osc - OSC message handling
  • Pillow - Image processing
  • pyamcp - CasparCG AMCP protocol

All dependencies are installed automatically by the setup script.

โš™๏ธ Configuration

First-Time Setup

  1. Launch the application

  2. Click "Settings" button in top bar

  3. Configure OBS:

    • Host: IP address of OBS machine (localhost for same machine)
    • Port: WebSocket port (default: 4455)
    • Password: Your OBS WebSocket password
    • Transition: Name of transition to use (e.g., "Fade", "Cut")
    • CasparCG Scene: OBS scene name where CasparCG output appears

  4. Configure CasparCG:

    • Host: IP address of CasparCG server
    • Port: AMCP port (default: 5250)
    • Channel: Video channel number (typically 1)
    • Layer: Video layer (default: 10)
    • OSC Port: Port for receiving feedback (default: 6250)

  5. Configure Playback:

    • Pre-transition time: Seconds before video ends to start transition back

  6. Click OK to save and connect

OBS WebSocket Setup

  1. Open OBS Studio
  2. Go to Tools โ†’ WebSocket Server Settings
  3. โœ… Enable WebSocket Server
  4. Note the port and set a password
  5. Click Apply

CasparCG OSC Setup

Ensure your CasparCG casparcg.config has OSC enabled:

<osc>
  <default-port>6250</default-port>
  <predefined-clients>
    <predefined-client>
      <address>127.0.0.1</address>
      <port>6250</port>
    </predefined-client>
  </predefined-clients>
</osc>

๐Ÿ“– Usage

Adding Media to Playlist

  1. Click Refresh in Available Media panel
  2. Drag media files from Available Media list
  3. Drop into Playlist panel
  4. Playlist is automatically saved

Playing Media

Three ways to play:

  1. Double-click any item in playlist
  2. Single-click item, then click Play in Selected Media panel
  3. Select item and use big Play button

The Playback Workflow

When you play a media file:

  1. โœ… Client validates media exists on server
  2. ๐ŸŽฌ OBS transitions to configured CasparCG scene
  3. โ–ถ๏ธ CasparCG starts playing the media file
  4. ๐Ÿ“Š Real-time progress tracking via OSC
  5. โฑ๏ธ Before video ends (configured time), OBS transitions back
  6. โœ… Seamless return to previous scene

Monitoring Playback

The Currently Playing panel shows:

  • ๐Ÿ–ผ๏ธ Media thumbnail
  • ๐Ÿ“„ Filename
  • โฑ๏ธ Current time / Total duration
  • ๐Ÿ“Š Progress bar
  • ๐Ÿ”Š Audio level meters (2 channels)
  • โน๏ธ Stop button

๐Ÿ“ Project Structure

caspar-client/
โ”œโ”€โ”€ main.py                     # Main GUI application
โ”œโ”€โ”€ casparcg_connection.py      # CasparCG AMCP/OSC handler
โ”œโ”€โ”€ obs_connection.py           # OBS WebSocket handler
โ”œโ”€โ”€ settings_manager.py         # Configuration management
โ”œโ”€โ”€ media_manager.py            # Media library & playlist
โ”œโ”€โ”€ playback_controller.py      # Workflow orchestration
โ”œโ”€โ”€ requirements.txt            # Python dependencies
โ”œโ”€โ”€ setup.sh / setup.bat        # Setup scripts
โ”œโ”€โ”€ run.sh / run.bat           # Run scripts
โ”œโ”€โ”€ README.md                   # This file
โ”œโ”€โ”€ QUICKSTART.md              # Quick start guide
โ”œโ”€โ”€ ARCHITECTURE.md            # Technical documentation
โ”œโ”€โ”€ DEVELOPMENT.md             # Development guide
โ””โ”€โ”€ .gitignore                 # Git ignore patterns

๐Ÿ“š Documentation

๐Ÿ”ง Troubleshooting

Connection Issues

CasparCG won't connect:

  • โœ… Verify CasparCG Server is running
  • โœ… Check correct IP and port in Settings
  • โœ… Test with: telnet localhost 5250
  • โœ… Check firewall settings

OBS won't connect:

  • โœ… Verify OBS is running
  • โœ… Enable WebSocket in OBS settings
  • โœ… Check password is correct
  • โœ… Verify port matches (default 4455)

Media Issues

No media files showing:

  • โœ… Click Refresh button
  • โœ… Verify CasparCG is connected (green dot)
  • โœ… Check CasparCG media folder has files
  • โœ… Verify correct channel in settings

Red text in playlist:

  • โš ๏ธ Media file missing from CasparCG server
  • โœ… Add file to CasparCG media folder
  • โœ… Click Refresh to update status

Playback Issues

Transition doesn't work:

  • โœ… Verify transition name matches OBS exactly
  • โœ… Check scene name matches OBS scene
  • โœ… Ensure OBS is connected (green dot)

No OSC feedback:

  • โœ… Configure CasparCG OSC in config file
  • โœ… Verify OSC port matches settings
  • โœ… Check firewall allows UDP on OSC port

๐Ÿ› ๏ธ Advanced Usage

Command Line Arguments (Future)

python main.py --config custom_settings.json
python main.py --debug

Keyboard Shortcuts (Framework Ready)

  • Space - Play selected media
  • S - Stop playback
  • R - Refresh media list
  • Ctrl+Q - Quit application

๐Ÿค Contributing

Contributions are welcome! Please see DEVELOPMENT.md for guidelines.

๐Ÿ“„ License

This project is licensed under the MIT License.

๐Ÿ™ Acknowledgments

Built with:

๐Ÿ“ž Support

For issues, questions, or suggestions:

  1. Check documentation files
  2. Review troubleshooting section
  3. Check CasparCG and OBS documentation
  4. Create an issue with detailed description

๐Ÿ—บ๏ธ Roadmap

  1. Recheck if obs scene and transition are correctly configured by correct event

  2. If client was restarted, but caspar still play video, after restart, client should check current scene in obs and if something is playing and execute missing steps of second transition

  3. Before returning transition, recheck if on live is still casparcg scene - zrobiฤ‡ poprzez callback obs

  4. Usuล„ osc unsubscribe, bo niedostepne

  5. Zrobiฤ‡ coลผ z woล‚aniem wฤ…tkรณw przy callbackach niepotrzebnym

  6. Dodaj check przed playoutem, czy scena zdefiniowana w obs istnieje

  7. jeล›li nie wyjdzie odtwarzanie, to wyล›wietl informacje dlaczego. Lub, ลผe doszล‚o do maualnego override itd.

  8. Zamiast zamiany preview z live, wrzuฤ‡ scenฤ™ z preview na live (zostaw jฤ… rรณwnieลผ na preview)

  9. reduce log verbosity

  10. jakoล› obsล‚uลผ bล‚ฤ™dy np. gdy lista odล›wieลผyล‚a siฤ™ niepoprawnie

  11. Przy zamykaniu okno dialogowe, czy chcฤ™ zamknฤ…ฤ‡. Jeล›li odtwarzany jakiล› film, nie moลผna zamknฤ…ฤ‡ aplikacji

  12. execute python instructions md on whole project

  13. Split project into modules (custom errors, eg.)

  14. poprawiฤ‡ te offsety, aby byล‚y z odpowiednimi instrukcjami itd.

GUI: dynamiczne przerzucanie kolumny z available mediami nad playlistฤ™ w zaleznosci od szerokosci