How to Deploy & Use jp9000/obs-studio

# OBS Studio Deployment & Usage Guide

## 1. Prerequisites

### Required Tools
- **CMake** 3.16 or higher (3.24+ recommended)
- **Git** 2.28+
- **C/C++ Compiler**:
 - **Windows**: Visual Studio 2019 or 2022 (Community edition works)
 - **macOS**: Xcode 14+ with Command Line Tools
 - **Linux**: GCC 11+ or Clang 14+
- **Qt**: Version 6.4+ (Qt5 5.15+ supported for legacy builds)
- **Python** 3.8+ (for scripting support and build scripts)

### Platform-Specific Dependencies

**Windows:**
- Windows 10 SDK (10.0.20348.0 or later)
- 64-bit build tools (x64 Native Tools Command Prompt)

**macOS:**
- macOS 11.0+ SDK
- Metal development libraries

**Linux (Ubuntu/Debian):**
```bash
sudo apt install build-essential git cmake ninja-build qt6-base-dev qt6-svg-dev \
   libffmpeg-dev libavdevice-dev libavcodec-dev libavformat-dev libavutil-dev \
   libswresample-dev libx264-dev libxcb-randr0-dev libxcb-shm0-dev \
   libxcb-xinerama0-dev libxcb-composite0-dev libxcb-xfixes0-dev \
   libx11-xcb-dev libgl1-mesa-dev libgles2-mesa-dev libcurl4-openssl-dev \
   libmbedtls-dev libjack-jackd2-dev libpulse-dev

2. Installation

Clone the Repository

git clone --recursive https://github.com/obsproject/obs-studio.git
cd obs-studio

If you already cloned without submodules:

git submodule update --init --recursive

Fetch Pre-built Dependencies (Windows/macOS)

Windows:

# Run in PowerShell from the repo root
.\CI\build-windows.ps1 -Help  # View build options first
# Or manually download deps:
cmake -P CI\check-depends.cmake

macOS:

# Dependencies are fetched automatically during CMake configure, or:
cmake -P CI/check-macos-deps.cmake

3. Configuration

CMake Configuration Options

Create a build directory:

mkdir build && cd build

Development Build (with debugging):

cmake .. \
  -DCMAKE_BUILD_TYPE=Debug \
  -DENABLE_PLUGINS=ON \
  -DENABLE_BROWSER=ON \
  -DENABLE Websocket=ON \
  -DCMAKE_INSTALL_PREFIX=$PWD/install

Production Build:

cmake .. \
  -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_INSTALL_PREFIX=/opt/obs-studio \
  -DENABLE_UNIT_TESTS=OFF \
  -DBUILD_FOR_DISTRIBUTION=ON

Key Configuration Variables

Variable	Description	Default
`ENABLE_BROWSER`	Enable browser source plugin	ON
`ENABLE_VLC`	Enable VLC video source	OFF
`ENABLE_PIPEWIRE`	Linux screen capture (Wayland)	ON
`ENABLE_NEW_MPEGTS_OUTPUT`	Advanced MPEG-TS output	OFF
`QT_VERSION`	Force Qt version (5 or 6)	Auto-detect

Environment Variables

# Linux/macOS - Add to ~/.bashrc or ~/.zshrc
export OBS_PLUGINS_PATH=$PWD/build/plugins
export OBS_PLUGINS_DATA_PATH=$PWD/build/data

# Windows (PowerShell)
$env:OBS_PLUGINS_PATH="C:\obs-studio\build\plugins"
$env:QTDIR="C:\Qt\6.4.0\msvc2019_64"

4. Build & Run

Build Commands

Using CMake directly:

cmake --build . --config Release --parallel $(nproc)

Using Ninja (Linux/macOS):

cmake -G Ninja ..
ninja -j$(nproc)

Windows (Visual Studio):

cmake --build . --config Release --parallel 8
# Or open OBS.sln in Visual Studio

Run Locally (Development)

Linux:

./build/rundir/Release/bin/obs
# Or after install:
./install/bin/obs

macOS:

open ./build/rundir/Release/OBS.app
# Or for development without bundling:
./build/rundir/Release/bin/obs

Windows:

.\build\rundir\Release\bin\64bit\obs64.exe

Production Run

After installation:

# Linux (system install)
obs

# macOS
/Applications/OBS.app/Contents/MacOS/OBS

# Windows
C:\Program Files\obs-studio\bin\64bit\obs64.exe

5. Deployment

Packaging for Distribution

Windows (Installer):

# Build the installer using CPack
cmake --build . --target package
# Or manually:
.\CI\build-windows.ps1 -Package

macOS (App Bundle & DMG):

cmake --build . --target package
# Creates OBS.app and optionally a DMG

Linux (Flatpak - Recommended):

# Build Flatpak bundle
flatpak-builder build-flatpak com.obsproject.Studio.json --repo=repo
flatpak build-bundle repo obs-studio.flatpak com.obsproject.Studio

Linux (Debian Package):

cpack -G DEB

Deployment Platforms

Platform	Method	Notes
Windows	NSIS Installer / Portable ZIP	Use `BUILD_FOR_DISTRIBUTION=ON`
macOS	Signed .app bundle	Requires Apple Developer ID
Linux	Flatpak (Flathub)	Most universal method
Linux	PPA (Ubuntu)	For apt distribution
Linux	Arch AUR	Community maintained

CI/CD Integration

The repository includes GitHub Actions workflows in .github/workflows/:

main.yml - Standard builds for all platforms
publish.yml - Release automation

6. Troubleshooting

Build Issues

Submodule errors:

# If you see "fatal: not a git repository" for deps
git submodule foreach --recursive 'git clean -xfd && git reset --hard'
git submodule update --init --recursive --force

CMake Qt not found:

# Explicitly specify Qt location
cmake -DQTDIR=/path/to/qt/6.4.0/gcc_64 ..

Windows: Missing Windows SDK:

Install via Visual Studio Installer → Individual Components → Windows 11 SDK

Linux: Wayland/PipeWire issues:

# Ensure development headers are present
sudo apt install libpipewire-0.3-dev libwayland-dev

Runtime Issues

Black screen/Rendering issues:

Linux: Try OBS_USE_EGL=1 obs for EGL backend
Windows: Update GPU drivers; run with --disable-gpu to test

Plugins not loading: Check plugin paths:

obs --verbose  # Shows plugin loading details

Crash on startup (macOS):

# Reset OBS config
mv ~/Library/Application\ Support/obs-studio ~/Library/Application\ Support/obs-studio.backup

Stream key/Service issues:

Verify ~/.config/obs-studio/service.json (Linux)
%APPDATA%\obs-studio\service.json (Windows)
~/Library/Application Support/obs-studio/service.json (macOS)

Debug Builds

For detailed logging:

cmake -DCMAKE_BUILD_TYPE=Debug -DENABLE_TRACE_LOGGING=ON ..

Generate backtrace on crash (Linux):

gdb ./build/rundir/Debug/bin/obs
(gdb) run
(gdb) bt full  # After crash