pylibobs

Python bindings for libobs — the core C library of OBS Studio.

Lets Python scripts and apps drive libobs directly: initialize OBS, build scenes, configure encoders, mix audio, and record / stream — all without OBS Studio's UI running.

Status: beta. The public API is feature-complete and covered by tests. Reference counting semantics match OBS 32's obs_*_get_ref() model.

Why?

Existing options:

• obspython runs inside OBS only — you can't pip install it or use it from a normal Python app.
• obsws-python / simpleobsws talk to OBS via WebSocket — requires OBS to be running, and only exposes what the WebSocket API allows.

pylibobs links libobs directly (via cffi), so your Python process is the OBS host.

License

Copyright (C) 2026 Jonata Bolzan Loss and contributors.

pylibobs is licensed under GPL v2 or later, inherited from libobs. See LICENSE for the full text.

The published wheels bundle libobs's compiled binaries (also GPLv2+), so the wheel as distributed is covered by GPLv2+. Anything you build on top of pylibobs must be GPL-compatible if you redistribute it. Personal use carries no obligation.

Installation

pip install pylibobs

That's it on Windows / macOS / Linux. The wheel ships with bundled libobs binaries (libobs plus its plugin DLLs and data files, sourced from the official OBS Studio release on PyPI's build server). You don't need to install OBS Studio.

If you're installing from sdist (rare — only when no wheel is published for your platform), or you want to use a system-installed OBS, the loader falls back through:

1. $LIBOBS_PATH environment variable (explicit override)
2. Bundled libs inside the wheel — pylibobs/_libs/<platform>/<arch>/
3. ctypes.util.find_library("obs")
4. Well-known OBS Studio install paths

Maintainers / contributors can refresh the bundled libs by running:

python scripts/fetch_libs.py                  # current platform
python scripts/fetch_libs.py --all            # every platform
python scripts/fetch_libs.py --version 32.2.2 # pin OBS version

This downloads libobs from the official OBS GitHub release. The _libs/ tree is .gitignored and only populated during wheel builds.

Quick start

import time
from pylibobs import (
    OBSContext, OBSData, Source, Scene, Output,
    VideoEncoder, AudioEncoder,
)

with OBSContext() as obs:
    obs.set_video(width=1920, height=1080, fps_num=60)
    obs.set_audio()
    obs.load_modules()

    scene = Scene.create("main")
    cap = Source.create("monitor_capture", "Desktop", {"monitor": 0})
    scene.add(cap)

    venc = VideoEncoder.create("obs_x264", "video", {"crf": 23, "preset": "veryfast"})
    aenc = AudioEncoder.create("ffmpeg_aac", "audio", {"bitrate": 192})

    out = Output.create("ffmpeg_muxer", "rec", {"path": "out.mkv"})
    out.set_video_encoder(venc)
    out.set_audio_encoder(aenc)
    out.start()

    time.sleep(10)
    out.stop()

See examples/ for full recording and streaming scripts.

pylibobs-studio (tkinter, stdlib only)

examples/pylibobs_studio.py is a complete OBS-style desktop application built on nothing but the Python standard library:

python examples/pylibobs_studio.py

Features:

The whole app is ~600 lines in a single file. Use it as a starting point for your own pylibobs-based applications.

API overview

Testing

pip install -e ".[dev]"

# Unit tests (mocked cffi layer — fast, no libobs needed)
pytest tests/unit

# Integration tests (need a real libobs)
pytest tests/integration -m integration

# On Linux CI with no display:
Xvfb :99 -screen 0 1920x1080x24 &
DISPLAY=:99 pytest tests/integration -m integration

CI runs the full matrix on Windows, Linux, and macOS — see .github/workflows/ci.yml.

Project layout

pylibobs/
├── pylibobs/
│   ├── _lib.py            # Library locator
│   ├── _ffi.py            # cffi instance
│   ├── _declarations.py   # C API declarations for cdef()
│   ├── context.py         # OBSContext
│   ├── data.py            # OBSData
│   ├── source.py          # Source
│   ├── scene.py           # Scene / SceneItem
│   ├── encoder.py         # VideoEncoder / AudioEncoder
│   ├── service.py         # Service
│   ├── output.py          # Output
│   └── _libs/             # Bundled libobs binaries (after fetch_libs.py)
├── tests/unit/            # Mocked tests
├── tests/integration/     # Real libobs tests
├── scripts/fetch_libs.py  # Pull libobs from OBS releases
└── examples/              # record_to_file.py, stream_to_rtmp.py

Coverage / known gaps

pylibobs targets libobs 32.2.2 and declares every function it exports (1384 obs_* / gs_* / signal_* / proc_* / calldata_* / audio_output_* / video_output_* symbols), reachable via pylibobs._ffi.get_lib(). 1157 of them carry their full C signature; the remaining 227 are declared as void f(void) placeholders because scripts/generate_cdef.py cannot parse their headers yet — they resolve, but need a curated signature in _declarations.py before they can be called correctly. Pythonic class-based wrappers cover the common workflows:

• Lifecycle, video/audio init, scenes, sources, scene items, transforms (pos/scale/rot/crop/bounds)
• Outputs (file + RTMP streaming), encoders (incl. ROI hints and EncoderCaps), services
• Live preview (Display attached to a native window via HWND)
• Filters, transitions, hotkeys, fader + VU meter, audio monitoring
• Type lookups: display names, defaults, encoder capabilities, themed source icons (32.2+)
• Raw audio/video callbacks (numpy-friendly), audio resampler, media remux
• Properties API (read + edit, with type-aware widgets in examples/pylibobs_studio.py)
• Save / load whole scene collections to JSON

What's intentionally raw-only (callable via get_lib() but no class wrapper):

• The 290 gs_* graphics primitives — exposing them invites GPU-thread bugs; use obs_render_main_texture() instead.
• Property builders (obs_properties_add_*) — only useful for C plugin authors.
• Multi-canvas API (obs_canvas_*), obs_view_*, codec bitstream parsers (obs_avc_* / obs_av1_*).

Contributing

git clone https://github.com/jonata/pylibobs.git
cd pylibobs
python -m venv .venv && source .venv/bin/activate    # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
python scripts/fetch_libs.py                          # download bundled libobs
pytest                                                # 100+ tests, mock + integration

The integration suite needs process isolation (libobs can't gracefully restart inside a single process); use the included runner:

python scripts/run_tests.py

Release process

pylibobs is versioned after the libobs it bundles: pylibobs X.Y.Z ships libobs X.Y.Z. A release that only changes pylibobs, on the same libobs, adds a fourth number (X.Y.Z.1, X.Y.Z.2, …). Moving to a new libobs resets to its version.

1. Set the same version in pyproject.toml and pylibobs/__init__.py; when moving to a new libobs, also update DEFAULT_OBS_TAG in scripts/fetch_libs.py. python scripts/check_version.py checks they agree.
2. Tag the commit v<version> (e.g. v32.2.2) and push the tag. GitHub Actions:
   • Refuses to build unless the tag, both version strings and DEFAULT_OBS_TAG agree
   • Builds platform-specific wheels with bundled libobs (Windows x64 / Linux x86_64 / macOS Apple Silicon)
   • Builds the sdist
   • Publishes to PyPI via Trusted Publishing (no token needed in repo secrets)
   • Attaches all wheels to a GitHub Release with auto-generated notes

To set up Trusted Publishing on PyPI for this repo, register pylibobs as a project on PyPI, then in Project settings → Publishing, add a "GitHub Actions" trusted publisher pointing at <owner>/pylibobs / workflow release.yml / environment pypi.

Contributions welcome — PRs against main.