OBS Image Display Plugin

A powerful OBS Studio plugin that supports displaying images from multiple sources with rich animation effects.

Features

Image Source Support

• URL Images: Load images from network URLs
• API Integration: Retrieve image URLs through REST APIs
• Local Files: Load local image files

Animation Effects

• Fade in/out effects
• Slide in/out animations
• Scale animations
• Rotation animations
• Custom animations based on JSON scripts

Hotkey Support

• Show/hide images
• Toggle image display state
• Play animations
• Switch to next image

Configuration Options

• Image position, scale, and rotation
• Opacity control
• Auto-refresh intervals
• Animation duration and easing effects

Technical Architecture

Core Modules

1. Image Loader (image-loader)

   • HTTP/HTTPS URL download support
   • REST API integration
   • Local file reading
   • Asynchronous loading mechanism

2. Animation Script System (animation-script)

   • JSON format animation scripts
   • Keyframe animations
   • Multiple easing functions
   • Loop and conditional control

3. Image Source (image-source)

   • OBS source interface implementation
   • Render pipeline integration
   • Property configuration interface
   • Hotkey handling

Dependencies

• CURL: HTTP request handling (from OBS deps)
• nlohmann json: JSON parsing (from OBS deps)
• pthread: Multi-threading support
• OBS Studio API: Plugin interface

Installation

System Requirements

• macOS 10.15+
• OBS Studio 28.0+
• Xcode Command Line Tools

Building the Plugin

# Clone the project
git clone <repository-url>
cd obs-plugintemplate

# Configure build
cmake --preset macos

# Build
cmake --build build

Installing the Plugin

# Copy plugin to OBS plugins directory
cp build/obs-plugintemplate.so ~/Library/Application\ Support/obs-studio/plugins/

Usage Guide

Adding Image Source

1. Click "Add Source" in OBS
2. Select "Image Display Source"
3. Configure image source and display properties

Configuration Options

Image Source

• Source Type: Choose URL, API, or Local File
• Image URL: Direct image link
• API Endpoint: REST API address
• JSON Path: Path to image URL in API response
• Local File Path: Local image file path

Display Properties

• Visibility: Control image show/hide
• Opacity: 0.0-1.0 transparency
• Position: X/Y coordinates
• Scale: X/Y axis scaling ratio
• Rotation: Rotation angle

Animation Settings

• Enter Animation: Animation effect when image appears
• Exit Animation: Animation effect when image disappears
• Duration: Animation playback duration
• Easing: Animation speed curve

Hotkey Configuration

In OBS Settings under "Hotkeys" tab, you can configure:

• Show Image
• Hide Image
• Toggle Image
• Next Image
• Play Animation

Animation Script Format

The plugin supports custom animation scripts in JSON format:

{
  "name": "Example Animation",
  "duration": 5.0,
  "loop": true,
  "keyframes": [
    {
      "time": 0.0,
      "position": {"x": 0, "y": 0},
      "scale": {"x": 1.0, "y": 1.0},
      "rotation": 0.0,
      "opacity": 1.0
    },
    {
      "time": 2.5,
      "position": {"x": 100, "y": 50},
      "scale": {"x": 1.5, "y": 1.5},
      "rotation": 180.0,
      "opacity": 0.5
    }
  ]
}

API Interface Examples

Simple Image URL Response

{
  "image_url": "https://example.com/image.jpg"
}

Complex Nested Structure

{
  "data": {
    "images": {
      "featured": {
        "url": "https://example.com/featured.jpg"
      }
    }
  }
}

Corresponding JSON path: data.images.featured.url

Troubleshooting

Common Issues

1. Plugin fails to load

   • Check OBS version compatibility
   • Ensure dependencies are correctly installed
   • Review OBS log files

2. Images not displaying

   • Verify image URL accessibility
   • Check network connection
   • Confirm supported image formats (PNG, JPG, GIF, etc.)

3. API requests failing

   • Check API endpoint correctness
   • Verify JSON path configuration
   • Review network request logs

Log Files

OBS logs location: ~/Library/Application Support/obs-studio/logs/

Development

Project Structure

obs-plugintemplate/
├── src/
│   ├── plugin-main.cpp      # Main plugin entry
│   ├── image-source.cpp     # Image source implementation
│   ├── image-loader.cpp     # Image loading module
│   └── animation-script.cpp # Animation script system
├── data/
│   └── locale/             # Localization files
├── cmake/                  # CMake configuration
└── docs/                   # Documentation

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

This project is licensed under the GPL v2 License - see the LICENSE file for details.

Acknowledgments

• OBS Studio team for the excellent plugin framework
• Contributors to the open-source libraries used in this project