CasparCG-OBS Control Client

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

• QUICKSTART.md - Quick start guide and common tasks
• ARCHITECTURE.md - Technical architecture and design
• DEVELOPMENT.md - Development and testing guide

🔧 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:

• CasparCG - Professional graphics and video play-out software
• OBS Studio - Open broadcaster software
• PyQt6 - Python Qt bindings
• obs-websocket-py - OBS WebSocket Python client

📞 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