OBS Message Overlay

A production-ready Python overlay editor for OBS Studio. Design real-time text messages, shapes, stickers, and smoke effects — then push them live to your stream via a Browser Source.

---

Features

Category	Capabilities
Text	Custom TTF/OTF fonts, solid/gradient fills, per-character styles, alignment, letter/line spacing
Effects	Drop Shadow, Glow, Stroke (outline), Bevel/Emboss, Texturize
Transitions	Fade, Fly From Left/Right/Top/Bottom, Drop In, Roll On, Zoom In, Bounce In, Spin & Scale, Elastic Bounce, Wipe, Typewriter, Particle Burst
Animations	Audio Bounce (mic/system audio reactive), Pulse, Wave, Float, Shake, Spin, Rainbow
Shapes	Rectangle, Rounded Rect, Circle, Ellipse, Line — solid or gradient fill, stroke
Stickers	PNG/JPG images with transparency, scale, flip, rotate
Smoke	CPU particle system: density, speed, direction, turbulence, color, particle size
Layers	Unlimited layers, z-order reordering, visibility toggle, duplicate
Presets	4 built-in + save/load unlimited custom presets (JSON)
Export	Browser Source (HTML/CSS/JS) served locally; OBS WebSocket script

---

Project Structure

obsmsgplug/
├── overlay_editor.py          # ← Launch this to open the GUI
├── requirements.txt
├── README.md
│
├── obs/
│   └── obs_script.py          # ← Load this in OBS → Tools → Scripts
│
├── src/
│   ├── models/                # Data models (layer types, project)
│   │   ├── layer.py           # TextLayer, ShapeLayer, StickerLayer, SmokeLayer
│   │   └── project.py         # Project, Scene, CanvasSettings
│   │
│   ├── rendering/             # Pillow/NumPy rendering pipeline
│   │   ├── renderer.py        # Main compositor
│   │   ├── text_renderer.py   # Per-character text with effects
│   │   ├── effects.py         # Shadow, glow, stroke, bevel
│   │   ├── particles.py       # Smoke particle system
│   │   └── animations.py      # Easing functions, transition & animation engine
│   │
│   ├── audio/
│   │   └── analyzer.py        # Real-time audio RMS + beat detection
│   │
│   ├── server/
│   │   └── overlay_server.py  # Flask + Socket.IO HTTP/WebSocket server
│   │
│   ├── ui/
│   │   ├── main_window.py     # Main PyQt5 window
│   │   ├── preview_widget.py  # Live 30fps preview (QPainter)
│   │   ├── layers_panel.py    # Layer stack management
│   │   ├── text_tab.py        # Text properties
│   │   ├── style_tab.py       # Shadow/glow/stroke/bevel
│   │   ├── animation_tab.py   # Transitions & animations
│   │   ├── shapes_tab.py      # Shape & sticker properties
│   │   ├── overlays_tab.py    # Smoke overlay properties
│   │   └── color_picker_widget.py  # Color + gradient picker
│   │
│   └── utils/
│       ├── config.py          # App settings (~/.config/)
│       └── presets.py         # Built-in & custom presets
│
├── browser_source/
│   ├── overlay.html           # HTML served to OBS Browser Source
│   ├── overlay.css            # Styles & CSS keyframe animations
│   └── overlay.js             # JS renderer + smoke particle system
│
└── assets/
    ├── fonts/                 # Drop custom fonts here
    ├── stickers/              # Drop PNG stickers here
    └── presets/               # User-saved preset JSON files

---

Installation

1. Prerequisites

• Python 3.10 or newer
• OBS Studio 28+ (for WebSocket v5 / Browser Source)
• pip package manager

2. Install Python dependencies

cd /path/to/obsmsgplug
pip install -r requirements.txt

Key packages:

• PyQt5 — GUI framework
• Pillow — image & text rendering
• numpy, scipy — animation math, audio analysis
• sounddevice — real-time audio capture
• flask, flask-socketio, eventlet — local Browser Source server

3. Launch the editor

python overlay_editor.py

The editor opens with a dark-themed UI, a live preview, and a layer stack.

---

Connecting to OBS

Method A: Browser Source (Recommended — works with any OBS version)

1. Start the overlay server: Server → Start / Restart Server (auto-starts on launch)
2. In OBS, add a Browser Source:
   • Right-click your scene → Add → Browser
   • URL: http://localhost:8765/overlay
   • Width: 1920, Height: 1080
   • ✅ Enable "Shutdown source when not visible"
3. Done! Changes in the editor appear live in OBS.

Method B: OBS Python Script (optional, adds hotkeys & auto-creates source)

1. Open OBS → Tools → Scripts
2. Click + and select obs/obs_script.py
3. In OBS → Tools → Scripts → Python Settings, set your Python 3 executable
4. The script will auto-create the Browser Source and register show/hide hotkeys

Note: The OBS Python scripting API (obspython) is only available when running inside OBS. The standalone editor (overlay_editor.py) runs independently and communicates via the local HTTP server.

---

Quick Start Guide

Creating your first overlay

1. Launch overlay_editor.py
2. Click + Text in the toolbar or Layers panel
3. In the Text tab on the right:
   • Type your message in the text box
   • Choose a font (click Browse… to load a TTF/OTF)
   • Set font size and color
4. In the Style tab, enable Glow or Shadow for visual impact
5. In the Animation tab, set an Entrance Transition (e.g. Fly From Left)
6. Watch the live preview update in real-time
7. Connect OBS via Browser Source (see above) to go live

Loading a preset

• Toolbar dropdown → pick a preset, or
• Menu: Presets → Load Preset

Built-in presets:

Preset	Description
Neon Glow Announcement	Gradient "NOW LIVE" with cyan glow, elastic zoom-in
Subtle Smoke Lower Third	Name/title banner with soft smoke background
Typewriter Alert	Follower alert that types itself out character by character
Audio Bounce Title	Beat-reactive title that bounces to music

---

Per-Character Styling

To style individual characters differently:

1. Select a text layer
2. In the Text tab, the char_styles list is managed programmatically
3. Via JSON project file, add entries to char_styles array:

"char_styles": [
  { "char": "H", "fill": {"fill_type": "solid", "color": [255,0,0,255]}, "font_size": 72 },
  { "char": "i", "fill": {"fill_type": "solid", "color": [0,255,0,255]} }
]

Full per-character UI editor is on the roadmap for v1.1.

---

Audio-Reactive Effects

1. Menu: Audio → Enable Audio Analysis
2. Select a text layer → Animation tab
3. Set Type = "Audio Bounce"
4. Enable ✅ "React to audio input"
5. The text will bounce and scale with your microphone/system audio

The audio analyzer uses sounddevice to capture input, performs FFT-based beat detection, and feeds the amplitude to the animation engine in real-time.

---

Smoke Overlay

1. Click + Smoke in the Layers panel
2. In the Smoke tab:
   • Density: How many particles spawn per second (0.0–1.0)
   • Speed: Particle drift velocity
   • Direction: 270° = upward, 90° = downward, 0° = right
   • Turbulence: Randomness / swirl in particle paths
   • Particle color: RGBA (alpha controls transparency)
   • Emitter Y: Set to 1.0 to emit from the bottom of screen

The smoke renders in both the Python preview (Pillow particles) and the browser source (HTML Canvas particles). The JavaScript version is smoother and recommended for the final output.

---

Save / Load Projects

• Ctrl+S — Save project (.omolay JSON format)
• Ctrl+Shift+S — Save As
• Ctrl+O — Open project
• File → Recent Files — Quick access to recent projects

Projects are standard JSON and can be version-controlled.

---

Extending the Project

Adding a new transition effect

1. Add an entry to TransitionEffect enum in src/models/layer.py
2. Handle it in AnimationEngine.get_transform() in src/rendering/animations.py
3. Add a CSS @keyframes rule in browser_source/overlay.css
4. Add the mapping in TRANSITION_ANIMATIONS in browser_source/overlay.js

Adding a new animation type

1. Add to AnimationType enum
2. Handle in AnimationEngine.get_transform()
3. Add CSS animation + JS handling in browser_source files

Custom shapes

Add to ShapeType enum and handle in OverlayRenderer._render_shape() (Python) and renderShapeLayer() (JS).

---

Performance Notes

Concern	Detail
Preview FPS	Target 30fps; complex text effects (glow+stroke+bevel) may drop to 15fps on slower machines. Disable effects to improve preview speed; they still render in the browser source.
Smoke particles	Browser source renders ≈ 30–80 particles smoothly via Canvas 2D. Python preview is intentionally limited for performance.
Text rendering	Pillow renders text per-frame. For long strings with many effects, consider caching: store the rendered image and only re-render when the layer changes (TODO for v1.1).
Browser Source	The JS renderer in OBS's Chromium engine is significantly faster than the Python preview. Always test your final design in OBS.

For maximum performance in OBS:

• Use Browser Source (Chromium rendering is hardware-accelerated)
• Set a reasonable frame rate in OBS Scene settings
• Disable "Shutdown source when not visible" if experiencing flash-in

---

Troubleshooting

Server won't start / Flask error

pip install flask flask-socketio eventlet

Audio not working

pip install sounddevice
# On Linux, also: sudo apt install libportaudio2

PyQt5 install fails on Linux

sudo apt install python3-pyqt5
# or
pip install PyQt5 --config-settings --confirm-license

Fonts not loading

• Use absolute paths, or place fonts in assets/fonts/
• Supported formats: .ttf, .otf, .ttc
• Test with: python -c "from PIL import ImageFont; ImageFont.truetype('your_font.ttf', 48)"

OBS Browser Source shows blank white page

• Check that the server is running (green indicator in editor)
• Verify the URL is exactly http://localhost:8765/overlay
• In OBS browser source settings, click "Refresh cache of current page"

scipy not available (stroke effect fallback)

pip install scipy

Without scipy, the stroke effect uses a simpler single-pixel outline.

---

License

MIT License. See LICENSE file.

---

Roadmap (v1.1+)

• Full per-character style UI editor
• OpenGL-based smoke renderer (10x more particles)
• OBS WebSocket v5 direct integration (scene switching triggers)
• Twitch/YouTube alert webhook integration
• Video/GIF sticker support
• Text rendering cache for improved preview performance
• Multi-monitor preview
• Export to standalone HTML file (no server required)