obscura
GitHub

for OBS Studio · Quickshell · Hyprland

Recording is
one quiet button.

A small circle in your bar that opens into a pill while you record, a panel for the details, and a shortcut that works from anywhere. OBS keeps doing the recording; obscura only holds the remote.

git clone https://github.com/lunanoir21/obscura
Install steps →
00:00
00:00
✓Saved
Meet2
1h 07m
0%CPU while idle. No polling loop; the client sleeps on the socket.
1.2 MBrelease binary. Written in Rust, one process, no runtime.
3 MBresident memory for the process that watches OBS.
0config files needed. Port and password come from OBS itself.

How it works

A remote, not another recorder.

01

OBS does the work

obscura drives the OBS you already have through its built-in WebSocket server. Your scenes, sources and encoder settings stay in OBS; nothing is re-implemented.

02

One thin layer

A small Rust binary watches OBS and prints state as JSON lines. The Quickshell module reads them and draws the pill. If one dies, the other is unaffected.

03

Never guesses

The red dot lights only when OBS says the recording started. If OBS is closed, the server is off or the password is wrong, the pill says so instead of pretending.

The panel

Everything you reach for, nothing else.

  • Start, pause and stop; switch scenes; mute sources with live level bars.
  • Pick the recording folder by browsing, set the file name pattern, and see the next file's name. A warning appears if that name is already taken.
  • Frame rate options follow your screen: a 144 Hz display offers 120 and 144, a 60 Hz one does not offer 120.
  • Resolution, container and replay-buffer length change in OBS on the spot. While recording, the ones OBS refuses to change are locked.
  • Timer font and size, button shape, notifications and the OBS port are yours to set.
OBS · bağlı
Hazır
00:001080p · 60 fps
Kaydı başlat
Sahne
SahneOyunKamera
Ses kaynakları
Masaüstü Ses
Mic/Aux
Son 30 sn'yi kaydet
Ekran
Klasör
Kayıt klasörü
/home/luna/Videos/obscura
Seç
Dosya adı
%CCYY-%MM-%DD %hh-%mm-%ss
Sonraki dosya: 2026-10-09 22-20-14.mkv
Bu adla bir dosya zaten var; OBS yenisinin sonuna (1) ekleyerek kaydeder.
Kare hızı
243060120144
Çözünürlük
720p1080p1440pYerel
Biçim
MKVMP4MOV
Süre yazısı
04:1204:12
Yazı boyutu
−
18 px
+
Kayıt bitince
Bildirim göster
Dosya yolunu panoya kopyala
Düğme biçimi
DaireHapYalnız simge

The panel speaks English and Turkish and follows your system language (Look → Language).

Details

Small things, done carefully.

Shortcut anywhere

obscura toggle works with the bar closed. If OBS is closed too, it opens it in the background and starts recording.

Open on click

Click the pill while OBS is closed and it starts minimised to the tray. A second copy is never launched.

After the recording

A notification, optionally the path on the clipboard, and any executable you drop in ~/.config/obscura/hooks/saved.d/.

Level meters

OBS sends about 50 level events a second. obscura thins them to a dozen and only while the panel is open.

Kind to the bar

Blink instead of a constant fade, a window that never resizes mid-animation, and a panel that exists only while it is open.

Your own font

The timer can be Space Mono or the dot-matrix Doto, at any size from 10 to 32 px.

Screenshots

The real widget, in both themes.

The pill while recording
Recording
The pill after saving
Saved
OBS server off
When OBS’s server is off
Panel: control
Control
Panel: recording
Recording settings, with the name-taken warning
Panel: folder chooser
Folder chooser
Panel: look
Look and hooks
Picker: screens
Screen-share picker: screens
Picker: windows
Screen-share picker: windows

Drawn by the widget’s own code in a made-up world, so nothing here comes from a real desktop.

Screen-share picker

The dialog OBS asks for, in your style.

On Wayland, OBS asks the desktop portal which screen or window to capture, and the stock dialog does not look like anything else on your desktop. obscura can answer that question itself, with a card drawn by your Quickshell setup.

It is optional and safe: if the widget is not running, the stock dialog appears. One caveat: the portal does not say who is asking, so every app's share request, browser and Discord included, uses this card.

obscura picker-setup install
systemctl --user restart xdg-desktop-portal-hyprland
# back to the stock dialog:
obscura picker-setup uninstall

Install

From source, five minutes.

The whole install, start to finish: OBS, build, bar, shortcut (82 s, no sound).
Animated terminal: git clone, cargo build, obscura doctor, obscura toggle

  1. Turn on OBS's WebSocket server

    In OBS: Tools → WebSocket Server Settings → Enable. Needs OBS 28 or newer.

  2. Build

    git clone https://github.com/lunanoir21/obscura
cd obscura && cargo build --release
ln -s "$PWD/target/release/obscura" ~/.local/bin/obscura
obscura doctor

  3. Add it to your bar

    Place the module in your Quickshell config and drop the pill where you want it. pal is your colour object, u your scale unit.

    import "vendor/obscura/ui" as Obscura

Obscura.ObscuraPill { pal: mocha; u: barWindow.s(1) }
// once, anywhere in the shell:
Obscura.ObscuraPickerHost {}

  4. Bind a key

    bind = SUPER ALT, R, exec, obscura toggle
bind = SUPER ALT SHIFT, R, exec, obscura pause

Built and tested on Hyprland with OBS Studio 32 and Quickshell 0.3. Other setups are untested.