Skip to content
/ primebible-obs Public

Professional Bible verse overlay for OBS Studio - Live streaming tool for churches, worship

primebible.com

License

MIT license
1 star 0 forks Branches Tags Activity
Star
Notifications You must be signed in to change notification settings

primebible/primebible-obs

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

10 Commits
data
data
 
 
public
public
 
 
.gitignore
.gitignore
 
 
LICENSE
LICENSE
 
 
QUICKSTART.md
QUICKSTART.md
 
 
README.md
README.md
 
 
config.json
config.json
 
 
package.json
package.json
 
 
server.js
server.js
 
 

Repository files navigation

🌟 PrimeBible Pro for OBS

GitHub stars GitHub forks GitHub issues License

Professional Bible Overlay System for Live Streaming

Version License: MIT Node OBS Studio PrimeBible

State-of-the-art Bible verse overlays for worship services, Bible studies, and live streaming

Features • Quick Start • Architecture • API Documentation • Contributing

📖 Table of Contents

Overview

PrimeBible Pro for OBS is a professional-grade Bible verse overlay system designed for churches, ministries, and content creators using OBS Studio. It combines stunning visual design, powerful features, and seamless integration to deliver Scripture beautifully during live streams, worship services, and Bible studies.

🎯 Key Benefits

  • 🎨 Professional Design: 6 customizable themes with glassmorphic effects and smooth animations
  • ⚡ Lightning Fast: Real-time verse display with < 100ms latency
  • 🎮 Intuitive Control: Web-based dashboard + mobile remote control
  • 🔗 Deep OBS Integration: Automated setup, source management, and visibility control
  • 📱 Multi-Device Support: Control from desktop, tablet, or phone
  • 🖌️ Live Annotation: Draw, highlight, and annotate verses in real-time
  • 📚 Multiple Bible Translations: Powered by PrimeBible API (default: KJV, AKJV, WEB, ASV - configurable)
  • 🛠️ Zero Config: Works out-of-the-box with sensible defaults
  • 🔒 100% Free: Open source, no subscriptions, no paywalls

✨ Features

🎨 Stunning Visual Themes

Theme Description Best For
Glass Lower Third Modern glassmorphic design with blur effects Contemporary worship services
Minimal Center Clean, distraction-free centered display Teaching & Bible studies
Full Screen Maximum readability for large venues Large auditoriums
Split Side Professional side panel layout Conference streams
Corner Card Compact, unobtrusive display Gaming/casual streams
Scrolling Ticker News-style animated text Announcements & extended passages

⚡ Professional Power Features

  • ✅ Multi-slide presentations with automatic text chunking
  • ✅ Keyboard shortcuts for lightning-fast operation
  • ✅ Service planning - Pre-load your entire service order
  • ✅ History tracking - Never lose a verse you've displayed
  • ✅ Favorites system - Quick access to commonly used verses
  • ✅ Real-time preview - See exactly what will appear on stream
  • ✅ OBS WebSocket integration - Full automation and control
  • ✅ Live annotation tools - Draw, erase, highlight on-the-fly
  • ✅ Responsive design - Works on any screen size or device

🎬 Smooth Animations

  • Fade - Classic smooth transition
  • Slide - Dynamic entrance/exit
  • Zoom - Attention-grabbing scale effect
  • Typewriter - Character-by-character reveal

🔧 Customization Options

  • Colors: Custom background, text, and accent colors
  • Fonts: Google Fonts integration with 1000+ typefaces
  • Sizes: Adjustable font scaling for any venue
  • Positioning: Fine-tune placement and alignment
  • Opacity: Transparent overlays or solid backgrounds
  • High Contrast Mode: Enhanced readability for accessibility

🚀 Quick Start

Option 1: One-Command Install (Recommended)

# Clone and start in one command
git clone https://github.com/primebible/primebible-obs.git && cd primebible-obs && npm install && npm start

Option 2: Step-by-Step

# 1. Clone the repository
git clone https://github.com/primebible/primebible-obs.git
cd primebible-obs

# 2. Install dependencies
npm install

# 3. Start the server
npm start

🎯 Access Your Interfaces

Once started, open your browser:

📡 First-Time OBS Setup

  1. Open the Control Panel (http://localhost:3000/control)
  2. In the OBS Connection section, enter your OBS WebSocket details:
    • Default password: (usually blank for local OBS)
    • Port: 4455 (default)
  3. Click Connect to OBS
  4. Click Add Overlay to OBS - this automatically creates a browser source
  5. You're ready to go!

💻 System Requirements

Minimum Requirements

  • OS: Windows 10/11, macOS 10.15+, Ubuntu 20.04+
  • Node.js: v18.0.0 or higher
  • RAM: 2GB available
  • OBS Studio: v28.0+ (v29+ recommended)
  • Browser: Chrome 90+, Firefox 88+, Safari 14+, Edge 90+

Recommended Specs

  • OS: Windows 11, macOS 13+, Ubuntu 22.04+
  • Node.js: v20.0.0+
  • RAM: 4GB+ available
  • OBS Studio: v29.0+
  • Network: Gigabit Ethernet (for multi-device control)

📦 Installation

Prerequisites

  1. Install Node.js: Download from nodejs.org (LTS version recommended)
  2. Install OBS Studio: Download from obsproject.com
  3. Enable OBS WebSocket:
    • Open OBS → Tools → WebSocket Server Settings
    • Enable WebSocket server
    • Note the port (default: 4455) and password (if set)

Installation Methods

Method 1: NPM (Recommended for Developers)

npm install -g primebible-obs
primebible-obs start

Method 2: Git Clone (Recommended for Contributors)

git clone https://github.com/primebible/primebible-obs.git
cd primebible-obs
npm install
npm start

Method 3: Download ZIP

  1. Download the latest release
  2. Extract the ZIP file
  3. Open terminal in the extracted folder
  4. Run npm install && npm start

⚙️ Configuration

config.json

The config.json file controls server behavior and default settings:

{
  "port": 3000,
  "obsWebSocketPort": 4455,
  "obsWebSocketPassword": "",
  "primeBibleApiKey": "",
  "fallbackBibleApi": true,
  "logLevel": "info",
  "enableCors": true,
  "maxHistoryItems": 100,
  "defaultTheme": "glass",
  "defaultAnimation": "fade"
}

Configuration Options

Option Type Default Description
port number 3000 HTTP server port
obsWebSocketPort number 4455 OBS WebSocket port
obsWebSocketPassword string "" OBS WebSocket password
primeBibleApiKey string "" Optional PrimeBible API key for enhanced features
fallbackBibleApi boolean true Use fallback API if PrimeBible unavailable
logLevel string "info" Logging level: debug, info, warn, error
enableCors boolean true Enable CORS for remote access
maxHistoryItems number 100 Maximum history entries to keep
defaultTheme string "glass" Default overlay theme
defaultAnimation string "fade" Default animation style

Environment Variables

For production deployments, use environment variables:

PORT=3000
OBS_WEBSOCKET_PORT=4455
OBS_WEBSOCKET_PASSWORD=your_password
PRIMEBIBLE_API_KEY=your_api_key
NODE_ENV=production

🎮 Usage

Control Panel Interface

1. Search & Display Verses

  1. Type a verse reference in the search box (e.g., "John 3:16")
  2. Select translation (KJV, NIV, ESV, etc.)
  3. Choose theme and animation
  4. Click Preview to see it locally
  5. Click Display on Stream to show it live

2. Multi-Slide Presentations

Long passages are automatically chunked into slides:

  • Use Next/Previous buttons or arrow keys to navigate
  • Progress indicator shows current slide
  • Automatic text balancing for readability

3. Service Planning

  • Add to Plan: Build your entire service order ahead of time
  • Drag to Reorder: Rearrange verses in your plan
  • Save/Load Plans: Reuse service plans week after week
  • One-Click Display: Click any plan item to display instantly

4. Live Annotation

To enable annotation tools:

  1. In OBS Studio, add the control as a Browser source with URL: http://localhost:4456/control
    1. Right-click the Browser source → Order → Move to Top (to set as overlay)
      1. Right-click the Browser source → Interact...
        1. IMPORTANT: Click the Enable button on the annotation tools in the control panel

          1. You can now annotate directly over your overlay!

          2. Available annotation tools:

  • Drawing Tool: Freehand draw on the overlay
  • Highlighter: Emphasize specific words or phrases
  • Eraser: Remove annotations
  • Clear All: Reset the canvas
  • Color Picker: Choose annotation colors

Keyboard Shortcuts

Shortcut Action
Space Show/Hide overlay
Enter Display current verse
→ Next slide
← Previous slide
Esc Hide overlay
Ctrl/Cmd + K Focus search
Ctrl/Cmd + P Open service plan
Ctrl/Cmd + H View history
Ctrl/Cmd + F View favorites

Mobile Remote Control

Scan the QR code in the control panel or navigate to http://[your-ip]:3000/remote on your mobile device.

Features:

  • Full control panel access
  • Touch-optimized interface
  • Real-time sync with desktop
  • Service plan navigation
  • Quick verse lookup

🏛️ Architecture

System Overview

┌──────────────────────────────────────────┐
│          PrimeBible OBS Architecture          │
└──────────────────────────────────────────┘

┌───────────────┐     ┌───────────────┐     ┌───────────────┐
│  Control Panel  │     │  Mobile Remote │     │  Stage Display │
│ (Web Browser) │     │  (Web Browser) │     │ (Web Browser) │
└────────┬───────┘     └───────┬───────┘     └───────┬───────┘
         │                   │                   │
         └─────────┬─────────┴─────────┬─────────┘
                   │                   │
         ┌─────────┴────────────────────────┐
         │       WebSocket Server        │
         │      (Real-time Sync)         │
         └─────────┬────────────────────────┘
                   │
         ┌─────────┴────────────────────────┐
         │    Node.js Express Server    │
         │   (API + Static Content)    │
         └────┬───────┬──────┬───────┬────┘
              │       │      │       │
      ┌───────┴─┐  ┌─┴──┐  ┌┴──┐  ┌─┴────┐
      │ PrimeBible│  │OBS│  │DB│  │ Overlay │
      │    API    │  │ WS│  │  │  │(OBS Source)│
      └─────────┘  └───┘  └───┘  └─────────┘

Component Breakdown

1. Server Layer (server.js)

Responsibilities:

  • HTTP/HTTPS server (Express)
  • WebSocket orchestration (ws library)
  • REST API endpoints
  • Static file serving
  • OBS WebSocket client integration
  • State management and persistence

Key APIs:

Endpoint Method Description
/api/verse GET Fetch Bible verses from PrimeBible API
/api/history GET/POST Manage verse display history
/api/favorites GET/POST/DELETE Manage favorite verses
/api/service-plan GET/POST Load/save service plans
/api/obs/connect POST Connect to OBS WebSocket
/api/obs/ensure-overlay POST Create/update overlay source in OBS
/api/obs/overlay-visible GET/POST Control overlay visibility
/api/qr GET Generate QR code for mobile access

2. Overlay Client (public/overlay.html, public/overlay.js)

Responsibilities:

  • Render Bible verses with themes and animations
  • Listen for WebSocket commands from server
  • Handle multi-slide presentations
  • Apply live annotations and drawing
  • Responsive design for all aspect ratios

WebSocket Events (Received):

  • displayVerse - Show verse with theme/animation
  • hideOverlay - Hide current overlay
  • nextSlide / prevSlide - Navigate multi-slide content
  • updateStyle - Change colors, fonts, sizes
  • drawing - Live annotation data

3. Control Panel (public/control.html, public/control.js)

Responsibilities:

  • Search and fetch verses
  • Preview before displaying
  • Service plan management
  • History and favorites management
  • OBS connection and control
  • Live customization interface

4. Data Persistence (data/ folder)

  • history.json - Recently displayed verses
  • favorites.json - User-favorited verses
  • service-plan.json - Saved service orders

Data Flow Example

1. User searches "John 3:16" in Control Panel
2. Control JS calls /api/verse?reference=John+3:16&translation=KJV
3. Server fetches from PrimeBible API (with cache)
4. Server returns JSON to Control Panel
5. User clicks "Display"
6. Control sends WebSocket message to Server
7. Server broadcasts to all Overlay clients
8. Overlay animates verse on screen
9. OBS captures overlay as browser source
10. Verse added to history.json

📡 API Documentation

REST Endpoints

GET /api/verse

Fetch a Bible verse or passage.

Query Parameters:

  • reference (string, required) - Bible reference (e.g., "John 3:16", "Psalm 23:1-6")
  • translation (string, optional) - Bible translation code (default: "KJV")

Response:

{
  "success": true,
  "data": {
    "reference": "John 3:16",
    "translation": "KJV",
    "text": "For God so loved the world...",
    "verses": [
      {
        "verse": 16,
        "text": "For God so loved the world..."
      }
    ]
  }
}

POST /api/history

Add verse to history.

Body:

{
  "reference": "John 3:16",
  "translation": "KJV",
  "text": "For God so loved the world..."
}

WebSocket Events

Client → Server

displayVerse

{
  "type": "displayVerse",
  "payload": {
    "reference": "John 3:16",
    "text": "For God so loved the world...",
    "translation": "KJV",
    "theme": "glass",
    "animation": "fade"
  }
}

🛠️ Development

Project Structure

primebible-obs/
├── server.js              # Main Node.js server
├── config.json            # Configuration file
├── package.json           # Dependencies
├── public/                # Static web assets
│   ├── control.html       # Control panel UI
│   ├── control.js         # Control panel logic
│   ├── overlay.html       # Overlay UI
│   ├── overlay.js         # Overlay logic
│   ├── remote.html        # Mobile remote UI
│   ├── remote.js          # Mobile remote logic
│   └── stage.html         # Stage display (confidence monitor)
└── data/                  # Persistent storage
    ├── history.json       # Verse history
    ├── favorites.json     # Favorite verses
    └── service-plan.json  # Service plan data

Running in Development Mode

# Enable debug logging
export NODE_ENV=development
export LOG_LEVEL=debug

# Start with auto-reload (using nodemon)
npm install -g nodemon
nodemon server.js

Testing

# Run smoke tests
npm test

# Manual testing checklist
# See SMOKE_TEST.md for comprehensive test cases

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Quick Contribution Guide:

  1. Fork the repository
  2. Create a feature branch: git checkout -b feature/amazing-feature
  3. Commit your changes: git commit -m 'Add amazing feature'
  4. Push to the branch: git push origin feature/amazing-feature
  5. Open a Pull Request

Code Style

  • JavaScript: ES6+ syntax, async/await preferred
  • Indentation: 2 spaces
  • Naming: camelCase for variables/functions, PascalCase for classes
  • Comments: JSDoc style for functions

🚀 Deployment

Digital Ocean Deployment

See DIGITAL_OCEAN_DEPLOYMENT.md for complete Digital Ocean deployment guide.

Docker Deployment

# Build Docker image
docker build -t primebible-obs .

# Run container
docker run -d -p 3000:3000 --name primebible-obs primebible-obs

Production Checklist

  • Set NODE_ENV=production
  • Configure OBS WebSocket password
  • Set up reverse proxy (nginx/Apache)
  • Enable HTTPS/SSL
  • Configure firewall rules
  • Set up automatic backups for /data folder
  • Configure log rotation
  • Set up monitoring (optional)

🔧 Troubleshooting

Common Issues

"Cannot connect to OBS WebSocket"

Solution:

  1. Verify OBS is running
  2. Check OBS WebSocket is enabled: Tools → WebSocket Server Settings
  3. Verify port (default: 4455) and password match your config
  4. Ensure firewall allows WebSocket connections

"Overlay not appearing in OBS"

Solution:

  1. Verify overlay URL is correct: http://localhost:3000/overlay
  2. Check browser source dimensions match your canvas
  3. Ensure overlay source is not hidden in OBS
  4. Try clicking "Refresh cache" in OBS browser source properties

"Verses not loading"

Solution:

  1. Check internet connection (required for Bible API)
  2. Verify PrimeBible API is accessible
  3. Check server console for API errors
  4. Try alternative Bible API if enabled in config

"Mobile remote not working"

Solution:

  1. Ensure devices are on same network
  2. Use your computer's local IP (not localhost)
  3. Check firewall allows port 3000 connections
  4. Verify CORS is enabled in config.json

Debug Mode

export LOG_LEVEL=debug
npm start

This enables verbose logging for troubleshooting.

🤝 Contributing

We love contributions! Here's how you can help:

  • 🐛 Report bugs: Open an issue
  • 💡 Suggest features: Start a discussion
  • 📝 Improve docs: Submit a PR for README updates
  • 🎨 Add themes: Create new overlay themes
  • 🌐 Translations: Help translate the interface

Contributors

Thanks to all our contributors! 🙏

📜 License

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

Third-Party Licenses

  • PrimeBible API: Free for non-commercial use
  • OBS Studio: GPL-2.0
  • Node.js dependencies: See individual package licenses

📞 Support

Getting Help

Sponsorship

PrimeBible OBS is 100% free and open source. If this project has blessed your ministry, consider supporting:

  • ⭐ Star this repository
  • 💬 Share with your church/community
  • 💙 Sponsor PrimeBible (optional)

🚀 Roadmap

Version 2.1 (Planned)

  • Additional overlay themes (Neon, Classic, Minimal Modern)
  • Enhanced mobile remote with gesture controls
  • Multi-language interface (Spanish, Portuguese, Korean)
  • Hotkey support for physical stream deck integration
  • Enhanced stage display with speaker notes

Version 2.2 (Future)

  • Cloud sync for service plans
  • Collaborative remote control (multiple devices)
  • Custom theme builder with visual editor
  • Automated sermon note generation
  • Integration with other Bible APIs (Crossway, YouVersion)

📊 Project Stats

  • Lines of Code: ~5,000
  • Languages: JavaScript (58.3%), HTML (30.1%), CSS (11.6%)
  • License: MIT
  • Status: Active Development
  • First Release: November 2025

🙏 Acknowledgments

  • PrimeBible: For providing the exceptional Bible API
  • OBS Studio: For the amazing streaming platform
  • obs-websocket-js: For WebSocket integration library
  • Our Contributors: Thank you for making this project better!

Made with ❤️ by PrimeBible

Bringing Scripture to Life in Your Streams

Website • GitHub • Documentation • Issues

© 2025 PrimeBible. Released under the MIT License.

About

Professional Bible verse overlay for OBS Studio - Live streaming tool for churches, worship

primebible.com

Topics

nodejs open-source streaming websocket church overlay live-streaming bible obs obs-studio worship ministry bible-verses

Resources

Readme

License

MIT license
Activity

Stars

1 star

Watchers

1 watching

Forks

0 forks
Report repository

Releases 1

Initial Release - v1.0.0 Latest
Nov 17, 2025

Packages

No packages published

Contributors 2

  •  
  •  

Languages