How obsproject/obs-studio works
1. Repository purpose and top-level shape
- This is the OBS Studio monorepo: a desktop application plus its media engine, plugin ecosystem, platform-specific capture/rendering backends, and packaging/build automation.
- The code is split into a few major roots: libobs for the core engine, frontend for the Qt-based application UI, plugins for feature modules, shared for reusable support libraries, plus libobs-* rendering backends and test/CI infrastructure.
2. Core media engine: libobs
- libobs is the architectural center. It implements the scene model, sources, filters, transitions, outputs, encoders, graphics abstraction, audio/video media I/O, hotkeys, properties, config, threading, and platform utilities.
- The main data path here is: inputs/sources produce frames and audio -> scenes/compositor mix and render them -> encoders compress -> outputs package and deliver to a destination such as a file or streaming service.
3. Frontend application layer: frontend
- frontend is the OBS Studio desktop app built on Qt. It owns the main window, dialogs, docks, settings pages, wizards, update UI, plugin manager UI, OAuth/login flows, and the user-facing control surfaces.
- It talks to libobs through the frontend API in frontend/api and through higher-level app classes like OBSApp, OBSStudioAPI, and the main widgets under frontend/widgets.
4. Rendering backends: libobs-opengl, libobs-d3d11, libobs-metal, libobs-winrt
- Rendering and capture are split by platform/graphics API.
- libobs-opengl provides OpenGL/EGL/X11/Wayland/Cocoa glue; libobs-d3d11 provides the Windows Direct3D 11 subsystem; libobs-metal provides the macOS Metal implementation in Swift; libobs-winrt handles Windows Runtime capture pieces.
- These backends are the boundary between OBS’s portable scene/compositing logic and OS/driver-specific graphics APIs.
5. Plugin model: feature modules under plugins/
- Most runtime features are delivered as modules loaded by libobs, not hardcoded into the core.
- Plugins include capture sources (win-capture, mac-capture, linux-capture, linux-pipewire, linux-v4l2, win-dshow, mac-avcapture), audio inputs (win-wasapi, linux-pulseaudio, linux-alsa, oss-audio, sndio, linux-jack), encoders (obs-x264, obs-nvenc, obs-qsv11, obs-libfdk, coreaudio-encoder, mac-videotoolbox), outputs (obs-outputs, obs-ffmpeg, obs-webrtc), and UI add-ons (obs-browser, obs-text, text-freetype2, obs-transitions, obs-filters, plugin-manager, etc.).
6. Windows capture and injection path
- plugins/win-capture is a major subsystem because Windows game/window/display capture requires hook-based interception.
- It contains a graphics hook, injected helper, graphics API-specific capture code for D3D8/9/10/11/12, DXGI, OpenGL, and Vulkan, plus helpers for graphics offsets and compatibility data.
- The data path here is: OBS injects capture helpers into target processes -> hooks the graphics API -> copies frames back to OBS for composition.
7. macOS capture and virtual camera
- macOS support is split across plugins/mac-capture, plugins/mac-avcapture, plugins/mac-syphon, plugins/mac-videotoolbox, and plugins/mac-virtualcam.
- These modules cover screen/window/audio capture, Apple capture frameworks, Syphon interoperability, hardware encoding, and the macOS virtual camera implementation.
- Several pieces are written in Objective-C/Swift, reflecting tight integration with Apple frameworks and the Camera/Driver architectures.
8. Linux capture and portals
- Linux capture is distributed across linux-capture, linux-pipewire, linux-v4l2, linux-alsa, linux-pulseaudio, linux-jack, and linux-alsa.
- Modern desktop capture on Wayland flows through PipeWire and portals, while legacy X11 capture uses Xcomposite/XShm paths.
- Audio capture is similarly backend-specific, with separate modules for ALSA, PulseAudio, JACK, and sndio.
9. Encoder/output/service stack
- plugins/obs-ffmpeg, plugins/obs-outputs, plugins/obs-nvenc, plugins/obs-qsv11, plugins/obs-libfdk, and related encoder plugins are responsible for turning rendered media into streamable or recordable bitstreams.
- obs-outputs provides RTMP, FLV, MP4, and null outputs; obs-ffmpeg adds FFmpeg-based muxing/encoding paths; obs-webrtc adds WHIP/WebRTC streaming; rtmp-services supplies service metadata and presets.
- The output boundary is where scene-rendered media leaves OBS and becomes a file, a network stream, or a device feed.
10. Sources, filters, transitions, and UI-facing components
- obs-filters, obs-transitions, image-source, text-freetype2, vlc-video, obs-vst, and similar modules implement source types and visual/audio processing.
- These modules plug into the same core source/filter interfaces, so they participate in the shared scene graph and rendering pipeline rather than owning a separate UI stack.
- Many ship shader/effect assets in data/ alongside locale files, indicating a mixed runtime of C/C++ code plus declarative GPU effects and translated strings.
11. Shared support libraries
- shared/ contains reusable infrastructure used across core, frontend, plugins, and tests.
- Important pieces include IPC and shared-memory queues, file updating, media playback, Qt helper widgets, scripting support for Lua/Python, and small utility libraries like BPM, options parsing, and “happy eyeballs” networking.
- This layer reduces duplication for functionality that is not part of the core media engine but is needed across many modules.
12. Build system, dependency management, and platform packaging
- The project is CMake-driven (CMakeLists.txt, CMakePresets.json) with extensive per-platform CMake logic under cmake/.
- .github/scripts, .github/actions, and workflows handle formatting, analysis, package creation, code signing, docs generation, and platform-specific build steps.
- Packaging is a first-class concern: there are manifests, appcasts, Steam packaging scripts, Windows signing configs, macOS resources, Flatpak-related validation, and Linux desktop/metainfo files.
13. Documentation, localization, and assets
- docs/sphinx contains the developer-facing and API documentation.
- Translation files are distributed throughout frontend/data/locale and each plugin’s data/locale, so localization is part of the runtime asset model, not a separate service.
- Assets such as effects, icons, manifests, themes, and schemas are colocated with the modules that consume them.
14. Testing and validation
- test/ contains unit/integration-style tests for utility layers and media/input behavior, plus platform-specific test targets.
- The repository also includes dedicated validation tooling in CI for manifests, services definitions, Qt XML/forms, formatting, and compatibility rules.
- This makes the architecture strongly contract-driven: shared APIs, plugin schemas, and packaging metadata are continuously validated across the tree.
Main entry points: libobs libobs · frontend OBS Studio · win-capture Windows capture · mac-capture macOS capture
Components 24
Core engine
Portable media engine and scene/compositing runtime.
- libobs · Core scene graph, sources, filters, transitions, encoders, outputs, graphics, audio/video I/O, hotkeys, and platform utilities.
libobs - Graphics · Graphics abstraction, effects, math, textures, shaders, and device-independent compositing.
libobs/graphics - Media I/O · Audio/video buffers, resampling, format conversion, frame handling, and remux helpers.
libobs/media-io - Utilities · Threading, config, platform, serializers, process/task helpers, and common low-level support.
libobs/util
Desktop UI
Qt-based application layer and user-facing controls.
- OBS Studio · Desktop application shell, main window, dialogs, docks, settings, wizards, and update/login flows.
frontend - Frontend API · Public and internal interface between the frontend app and the core OBS runtime.
frontend/api - Main UI · Main window widgets, preview, status bar, audio mixer, scene controls, and app chrome.
frontend/widgets - UI Support · Crash handling, output helpers, networking helpers, theme/update logic, and platform integration.
frontend/utility
Render backends
Platform graphics and capture backends.
- OpenGL · OpenGL/EGL/X11/Wayland/Cocoa rendering backend glue.
libobs-opengl - D3D11 · Direct3D 11 rendering and resource management backend for Windows.
libobs-d3d11 - Metal · Swift-based Metal rendering backend and swapchain/device layer.
libobs-metal - WinRT capture · Windows Runtime capture and dispatch support used by Windows capture paths.
libobs-winrt
Plugins
Loadable runtime modules for capture, encoding, output, and effects.
- Plugins · Feature modules loaded by libobs, spanning capture, encoding, outputs, and source/filter add-ons.
plugins - Windows capture · Injected hook-based game/window/display capture across multiple graphics APIs.
plugins/win-capture - macOS capture · Screen, window, and audio capture paths for macOS.
plugins/mac-capture - Linux capture · X11 capture helpers and legacy Linux screen/window capture implementation.
plugins/linux-capture - PipeWire · Wayland desktop and camera capture through portals and PipeWire.
plugins/linux-pipewire - Outputs · Streaming, recording, muxing, null output, and RTMP/FLV/MP4 delivery paths.
plugins/obs-outputs - FFmpeg · FFmpeg-based muxing, codec integration, and source/output support.
plugins/obs-ffmpeg - Services · Streaming service presets, schemas, and platform-specific ingest metadata.
plugins/rtmp-services - Sources & filters · Built-in sources, filters, transitions, text, browser, audio effects, and UI add-ons.
Shared libs
Reusable support libraries used across the repo.
- Shared libs · Reusable IPC, scripting, playback, Qt widget, and utility libraries shared across modules.
shared
Build & CI
Build, packaging, docs, and validation infrastructure.
- Build & CI · CMake, scripts, workflows, packaging, signing, docs generation, and validation.
.github - Docs & tests · Sphinx documentation plus unit/integration tests for core utilities and media behavior.
docs/sphinx
Connections 28
- OBS Studio → Frontend API: uses · UI talks to core through the frontend API.
- Main UI → OBS Studio: builds UI · Main widgets compose the user-facing OBS window.
- UI Support → OBS Studio: supports · App services provide crash handling, updates, and platform glue.
- OBS Studio → libobs: controls · The desktop app configures and drives the media engine.
- libobs → Graphics: renders via · Core compositing and effects depend on the graphics layer.
- libobs → Media I/O: moves media · Media I/O feeds audio/video into the engine and outputs encoded streams.
- libobs → Utilities: relies on · Core runtime uses shared low-level utilities.
- libobs → Shared libs: reuses · Engine and plugins share IPC, scripting, playback, and Qt helpers.
- libobs → OpenGL: loads backend · Portable graphics layer binds to the OpenGL implementation where applicable.
- libobs → D3D11: loads backend · Windows graphics and capture paths use the D3D11 backend.
- libobs → Metal: loads backend · macOS graphics paths use the Metal backend.
- libobs → WinRT capture: uses · Windows Runtime capture support is part of the Windows boundary layer.
- Plugins → libobs: loads into · Runtime modules register sources, filters, encoders, and outputs with the core.
- Windows capture → libobs: feeds frames · Injected helpers capture frames back into the core compositor.
- Windows capture → D3D11: hooks · Windows capture intercepts D3D/OpenGL/Vulkan presentation paths.
- macOS capture → libobs: feeds capture · macOS capture modules deliver screen/window/audio sources to the engine.
- macOS capture → Metal: integrates · macOS capture and rendering closely follow Apple graphics APIs.
- Linux capture → libobs: feeds capture · X11-based Linux capture sources enter the scene pipeline.
- PipeWire → libobs: feeds capture · Wayland/PipeWire desktop capture feeds the core engine.
- Outputs → libobs: exports · Outputs consume rendered/encoded media from the core.
- FFmpeg → libobs: encodes/muxes · FFmpeg paths provide codec and mux integration for the runtime.
- Services → Outputs: configures · Service presets and schemas drive streaming output setup.
- Sources & filters → libobs: extends · Sources, filters, and transitions register with the core scene system.
- Sources & filters → OBS Studio: shown in UI · Feature plugins surface through the application UI and dialogs.
- Build & CI → OBS Studio: packages · CMake, scripts, and workflows build and package the desktop app and modules.
- Build & CI → Plugins: validates · CI checks plugin schemas, manifests, formatting, and platform-specific steps.
- Docs & tests → libobs: documents/tests · Docs and tests describe and verify the core engine contracts.
- Docs & tests → Frontend API: documents/tests · Frontend API docs and validation anchor the app-core interface.