Omaframe

Beautiful screenshots and clean screen recordings for Omarchy.

Omaframe is small on purpose. Press a key, pick how it looks, paste. When you need an arrow, a label or a blur, it is one key away. There is no big editor to learn, no account and no upload. Everything stays on your computer.

Install

On Omarchy or Arch with Hyprland, one command installs the latest release and everything it needs:

curl -fsSL https://pkgs.btso.dev/install.sh | bash -s -- omaframe

It adds my signed package repository, so Omaframe then updates with the rest of your system (omarchy update or sudo pacman -Syu). If you installed an earlier release by hand, run the same command to start getting updates.

If pacman says it cannot satisfy a dependency, your package lists are older than GPU Screen Recorder 6.1.0. Run omarchy-update (or sudo pacman -Syu on plain Arch) and then the command again.

Open Omaframe from the launcher and enable its capture shortcuts. It only sets up Print, Alt+Print and Alt+Shift+Print when they are free or still use Omarchy's stock capture actions. It backs up your bindings first and leaves custom keys alone.

Version 0.11.0 pins screenshots to your screen and opens a screenshot again when you click its notification. See the release notes. Version 0.11.1 starts again on Omarchy stable and rc (release notes). Version 0.11.2 shows a video's first frame as soon as it opens and loads the filmstrip faster (release notes).

Take a screenshot

Press Print Screen. Click a window, drag an area, or press F for the whole display. If the capture bar is in the way, hold Super and drag it, or drag the grip at its left edge. Press H to hide or restore the bar; each new capture shows it again. On the finish chooser:

• Click a finish to select it. A single click never copies, saves or closes, so a stray click right after a capture is harmless.
• Double-click a finish, press its number, or press Enter to copy the selected one. When Save screenshots automatically is on, the file is also saved; when it is off, only the clipboard gets the capture.
• Press E to mark up the selected finish first.
• Press Ctrl+C or Clipboard to copy the selected finish once without saving. Press Esc or × to cancel.
• Press Copy and save to save the file even when automatic saving is off.

Save screenshots automatically is on by default. Turn it off in Settings to stop keeping screenshot files. This does not disable editable drafts that are autosaved while you edit. A final clipboard-only copy does not update the draft with your latest edits.

Most screenshots don't need a new finish? Turn on Skip the finish chooser in Settings, next to Save screenshots automatically. Press Print Screen, click a window, drag an area or press F, and the screenshot is copied right away in Raw, without a frame, and saved too when automatic saving is on. The finish you picked in the chooser stays remembered for the chooser. The Screenshot copied notification confirms it; click it to change the finish, pin it or mark it up in the editor. The chooser's Hide possible secrets prompt is skipped as well, so look before you paste. Scrolling captures still end in the chooser, and if saving or copying fails the chooser opens with its retry. Settings can set up the optional Ctrl+Print shortcut, which always ends in the chooser. The setting is off by default and never changes your key bindings.

Paste it anywhere. Crops, marks and redactions you made in the editor are kept either way. Click the Screenshot copied notification to open it in the editor again, with its marks and finish still editable. If copying fails, the panel stays open. In the chooser, Ctrl+C retries a clipboard-only copy; in the editor, use Ctrl+Enter or Copy. A saved screenshot offers a retry for its unfinished step. The close button still cancels, and Esc while choosing an area still cancels the capture. Clicking outside the panel does nothing.

While you pick, Omaframe reads the text in the screenshot. If it spots something that looks like a secret, such as an API key, a token, an email address or a card number, a Hide possible secrets button appears. Press H and each one gets a redaction you can still move or undo in the editor. It can miss things, so look before you share. Press T to copy the text in the screenshot instead. Text copying reads the current crop and edits, so hidden or cropped-out text is excluded.

Need a menu or tooltip? Press Print Screen, choose Delay, then open it. When the screen freezes, choose what to capture. Pick 3, 5 or 10 seconds, or press T in the screenshot selector to use your last choice. Settings can also set up the optional Shift+Print shortcut. During the countdown, click Cancel or press either screenshot shortcut again. Ordinary Print stays immediate. The badge may appear in an ongoing recording.

Pin a screenshot

Want to keep a screenshot in view while you work? Press P on the finish chooser, or Pin (Ctrl+P) in the editor. The pin lifts off the place you captured and settles in the corner farthest from it, at its own size or smaller when it is large. It stays above your windows on every workspace until you close it. A pin is the screenshot itself with your marks and crop, without the finish. To show it framed, on a call say, press Shift+P instead. Pinning doesn't copy or save anything.

• Drag a pin to move it, onto another display too, or drag its corners to resize it.
• Scroll over it to zoom, or Ctrl+scroll to fade it.
• Double-click, middle-click or Esc closes it.
• Right-click for Copy, Save, Actual size, Click through, opacity and Close.

Click through lets clicks reach the window under the pin. Only a small pin badge in its corner still takes clicks: click the badge to hold the pin again. To pin a saved screenshot, open History, then press Pin or P. Omaframe keeps running while pins are open, and exits when the last one closes.

Capture a scrolling page

Press S in the screenshot selector, or run omaframe --scroll. Click the window you want, such as a browser. Omaframe scrolls and stitches the page until it reaches the end. Move the pointer to take over and scroll by hand if needed. To keep only part of the page, crop it in the editor afterwards.

Choose Done, Enter or Esc to keep what has been captured. Cancel discards it. For keyboard controls, point at the progress panel to focus it. The panel sits outside the capture when there is room; otherwise its rows come from the first frame, before the panel appeared. Fixed headers and small footers are usually kept once. Footers taller than about one eighth of the viewport, or 128 pixels, may repeat.

The result uses the same finishes and editor as an ordinary screenshot. Long pages fit to width; use Shift+wheel or the scrollbar to reach the bottom while editing. Capture stops at 32000 pixels along the scrolling direction, 200 MiB of image pixels, or 400 MiB of retained frame bands. Tiny scroll steps can reach the frame-band limit first. If it loses track of the page, Omaframe switches to manual scrolling. A scrollbar is removed when its gutter is verified; window controls are preserved. Completely repeating content uses wheel cadence and ranked matches to resolve ambiguous seams, so check the result before sharing. Pages with large animations, overlays or replaced content may need manual scrolling.

Mark it up

Press E before you pick a finish. Press T and click to type a label right on the image, then add arrows, boxes, highlights, blur or redaction, or crop. Use the mouse wheel to zoom in around the pointer for precise cropping and marks. With Select active, drag empty space to pan the zoomed image. Dragging a mark still moves it. You can also pan with the middle mouse button or scrollbars. Click Fit to reset the view. Zoom changes only the editor view, not the saved image. Click an active tool again to return to Select. With Crop, drag over the area to keep; the crop applies and returns to Select. Choose Crop again to trim the cropped image further. Ctrl+Z restores each previous crop in turn. Hold Shift while drawing or dragging an endpoint for 45-degree lines and arrows. The readout shows the angle counterclockwise from the right, so up-right is 45°. Hold Shift while drawing shapes for squares and circles. Hold Shift while dragging a shape corner to keep its original proportions. Drag marks to move them, or hold Shift to move straight. Side handles resize width or height; text wraps without changing its font size. Drag text corners to scale the font. Arrow keys move a selected mark one pixel, or ten with Shift. Pen strokes have resize handles too. Use the contextual Style button to change a tool's appearance. Labels offer text and background colors, opacity, size and alignment. Arrows offer open or filled heads, color, thickness and a contrast outline; lines and pen strokes offer the same color, thickness and outline controls. Boxes and ovals can have a colored fill with opacity. Highlights offer color and opacity, steps offer circle and number colors and size, and blur offers strength. Choices are remembered for new marks of each type. Video annotations use the same controls. Click outside a style panel to close it. Esc finishes text, cancels a drag, clears the selected mark, resets the tool to Select, then leaves Edit, one step at a time.

Record your screen

Press Alt+Print Screen, then click a window, drag an area, or press F. The Stop button sits outside what you are recording. If there is no room for it, use Alt+Print Screen or the Omarchy bar to stop. When you stop, trim the ends or cut out a slow part, then Copy and close. The video is on your clipboard.

If something private showed up while you recorded, press G to blur it or R to cover it, and drag over it. It stays hidden for the whole clip. To point something out, pause where it happens and press A for an arrow, B for a box, T for a label or N for a numbered step. Those show from there to the end. Select any mark and press I and O to set where it starts and stops.

Version 0.5.0 adds video crop, recovery drafts, camera overlay and GIF export:

• Press C and drag a rectangle to crop the whole clip. Press V to preview it, or Reset crop to restore the full frame.
• Edits are kept automatically in History, including trim, cuts, sound, marks, crop and camera placement. Reopen a draft to continue. Keep the original video in place; drafts store edits without copying large videos.
• Turn on Camera overlay in recording Options and choose your camera. It starts off. After recording, pause playback and drag the camera to move it. The Camera menu changes its size, position or visibility.
• Use Export GIF for a short looping demo or bug report. It includes your edits and has no sound, with Copy GIF and Show file after saving. GIFs use up to 720 pixels at 15 fps and clips up to 30 seconds. They can be larger than MP4, especially with lots of movement. MP4 export stays available.

Export saves a new MP4 with your edits. Copy video copies an opened original or your current export for pasting into a chat or folder. If a draft cannot be saved, Omaframe asks before leaving the editor. A failed export keeps your edits open.

Watch the full 50-second demo

History

Find saved captures and editable drafts in History from the toolbar, with Ctrl+H, or with omaframe --history. Filter by type, search filenames, and refresh to see folder changes. Previously used save folders are scanned too; forget them in Settings. Only matching files directly in those folders appear.

Copy again uses the saved PNG bytes or a video file link. Pin a screenshot to keep it on screen. Open captures in the editor, resume linked drafts, reveal files, or move one file to Trash after confirmation. Incomplete recordings carry an Incomplete badge.

Clipboard-only copies add no history item. Editable drafts may remain. Screenshot draft previews apply the saved edits and finish. Video previews use a bounded private JPEG cache; history keeps no extra full captures.

Keys

Where	Key	Does
Anywhere	Shift+Print	Start a delayed screenshot, when enabled in Settings
Anywhere	Ctrl+Print	Take a screenshot that ends in the finish chooser, when enabled in Settings
Choosing a screenshot area	T	Start the remembered screenshot delay
Anywhere	Print Screen	Take a screenshot
Anywhere	Alt+Print Screen	Start a recording, or stop it
Anywhere	Alt+Shift+Print Screen	Pause or resume recording, after enabling capture shortcuts in Settings
Choosing an area	F / Tab / Esc	Whole display / switch to video / cancel
Choosing an area	H	Hide or restore the capture bar
Choosing an area to record	D / M	Computer sound / microphone
Picking a finish	Click / double-click	Select a finish / copy it, saving a file when automatic saving is on
Picking a finish	1 to 9, Enter	Copy that finish / the selected one, saving a file when automatic saving is on
Picking a finish	Ctrl+C	Copy the selected finish without saving
Picking a finish	Esc	Cancel
Picking a finish	E / R	Mark up the selected finish / retake
Picking a finish	P / Shift+P	Pin the screenshot to the screen / pin it with the selected finish
Picking a finish	H / T	Hide possible secrets / copy the text
Marking up	V C A L B O H R G P N T	Select, crop, arrow, line, box, oval, highlight, redact, blur, pen, steps, text
Marking up or video	Shift+drag	Constrain angles, draw squares or circles, keep corner proportions, or move straight
Marking up or video	Arrow keys / Shift+arrow keys	Move a selected mark one / ten source pixels
Marking up	Shift+H	Hide possible secrets
Marking up	Ctrl+Z / Ctrl+Shift+Z	Undo / redo
Marking up	Delete, Ctrl+D, F2	Delete, duplicate, rewrite the selected label
Marking up	Ctrl+C / Ctrl+X / Ctrl+V	Copy / cut / paste the selected mark. Never copies or closes the screenshot
Marking up	Ctrl+P	Pin the screenshot to the screen
Marking up	Ctrl+Enter	Finish: after a capture, copy and save a file only when automatic saving is on; in the studio, copy and save
Reviewing a video	Space, I / O, Delete	Play, set start / end, remove the selected part
Reviewing a video	C V G R A B T N	Crop, select, blur, redact, arrow, box, label, step. With a mark selected, I / O set when it shows
Reviewing a video	Ctrl+Z / Ctrl+Shift+Z or Ctrl+Y	Undo / redo trim, cuts and marks
Reviewing a video	Ctrl+C / Ctrl+X / Ctrl+V, Ctrl+D	Copy / cut / paste the selected mark at the playhead, duplicate it
In the window	Ctrl+H	Open capture history
History	P	Pin the selected screenshot
A clicked pin	Esc / Ctrl+C / Ctrl+S	Close / copy / save it
A clicked pin	Ctrl+0, Ctrl+= / Ctrl+-	Actual size, zoom in / out
A clicked pin	T, arrow keys	Click through, nudge it (Shift: ten pixels)
In the window	Ctrl+S	Copy and save, even when automatic saving is off

Good to know

Screenshots go to an Omaframe folder in your Pictures folder and recordings to one in your Videos folder (~/Pictures/Omaframe and ~/Videos/Omaframe unless your desktop says otherwise). Change either in Settings. Saved images contain only the rendered pixels, and redaction replaces pixels with a solid fill. Your originals are never changed.

Open and the folder buttons use your desktop's file chooser through xdg-desktop-portal, starting in your screenshot folder (or in the folder you last opened from). Without a portal, Omaframe shows its own dialog instead.

The text Omaframe reads for H and T stays in memory. It is never saved, not even in drafts. Reading needs tesseract and tesseract-data-eng; without them the button and T are simply not there. Set OMARCHY_OCR_LANGS (for example eng+deu) to read other languages, as Omarchy's own text capture does.

Screenshot drafts keep a private copy of the capture. Video drafts keep only edits and refer to the original video. Both appear under History. Deleting a video draft leaves the original video and exports in place. If a screenshot draft cannot be saved, the studio keeps the image and edits open and offers retry or discard before you leave.

Camera recordings keep a separate camera video and a small .camera.json file beside the screen recording. Keep these files together to edit the camera later. Pause/resume leaves paused time out of both tracks. If the camera fails, screen recording continues. Share the exported MP4 to include your chosen layout.

Audio meters check the selected microphone and computer sound without changing volume. Turn Mic on in the recording bar or open Options and speak to check it. Computer sound reads Quiet until something plays. Clip risk shows limited input headroom, not the volume of the encoded mix. Microphone preview is active only while the record-mode bar, Options, or the recording control needs it. Meters close during countdown, startup, pause, saving, and when those surfaces hide. Whole-display recordings without a visible control have no live meter.

Recording a whole display on a single monitor leaves no room for a Stop button outside the video, so Omaframe shows a short countdown that tells you how to stop, and it is gone before the first frame. Stop with Alt+Print Screen or with the recording icon in the Omarchy bar. With a second monitor, the Stop button waits there, at the edge next to the one you are recording.

A whole-display recording includes the Omarchy bar, because it is part of the screen. Stopping from the bar's icon works normally; Omarchy may also show its own "Screen recording saved" notice.

You can take and edit screenshots while you record. If you stop a recording in the middle of a screenshot, its review opens once the screenshot is done.

When a capture stops right at a plain background, the finishes carry that background out a little so the content is not pressed against the edge. Raw keeps the capture exactly as it was.

Omaframe follows your Omarchy theme and updates when you switch themes.

Pause and Resume sit beside Stop. Pausing keeps the same recording open and leaves the paused interval out of the saved video and audio. The timer counts recorded time. You can still take screenshots while paused, and Stop saves the clip normally.

If the recorder is still finishing 15 seconds after Stop, the button turns into Force. Force-stopping keeps whatever file was written, but it may be incomplete. If the camera is unplugged before recording starts, the recording continues screen-only and Omaframe tells you. A selected camera that is not connected stays selected until you pick another one, so Omaframe never switches to a different camera on its own.

Enable capture shortcuts in Settings to use Alt+Shift+Print Screen for pause/resume, including whole-display recordings without a visible control. Setup keeps custom bindings and adds the new key only when it is free.

For a menu or tooltip capture, run omaframe --delay 5 or omaframe --capture --delay 5. The delay is integer seconds from 0 to 30; 0 captures immediately. Other modes cannot use --delay.

omaframe --capture --direct finishes one screenshot without the finish chooser, and omaframe --capture --chooser always shows it, whatever Skip the finish chooser is set to. Both also work with no option, with --screen, --repeat and --delay, but not together or with other modes.

For scripts or custom keys, use omaframe --pause-recording, omaframe --resume-recording, or omaframe --toggle-recording-pause. These commands control only the current Omaframe recording and fail if it is not ready. Print and Alt+Print keep their existing behavior.

There is no animated zoom yet. Marks on a video stay in place: they do not follow something that moves or scrolls.

Uninstall

sudo pacman -R omaframe

Then delete the block between -- omaframe:shortcuts:start and -- omaframe:shortcuts:end in ~/.config/hypr/bindings.lua to give Print Screen and Alt+Print Screen back to Omarchy and remove the pause shortcut. Reload Hyprland to apply the change. If cached Lua keeps the running bindings, restart your Hyprland session. Your screenshots, recordings and settings stay where they are.

Build from source

Build dependencies: base-devel cmake ninja pkgconf qt6-base qt6-declarative qt6-multimedia qt6-wayland qt6-imageformats bash layer-shell-qt wayland wayland-protocols wl-clipboard ffmpeg gpu-screen-recorder libpulse procps-ng xdg-utils. libnotify is optional and adds a notification after a quick screenshot. tesseract and tesseract-data-eng are optional and add secret hiding and copying text.

cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=RelWithDebInfo
cmake --build build -j 3
./build/omaframe --studio

omaframe with no options takes a screenshot, --record starts or stops a recording, --repeat captures the last area again, --studio opens the window, and a file path opens that image or video. You can also build the package yourself: download PKGBUILD from the latest release and run makepkg -si. See RELEASING.md for how releases are made.

The capture, clipboard and recording tests talk to a Wayland compositor and the session bus, so run them in a throwaway nested desktop rather than your own session. With omabox, for example:

omabox run --net isolated -- ctest --test-dir build --output-on-failure

Test notes and hardware results are in docs/, starting with the recording validation.

GitHub CI builds on Arch and runs fifteen headless suites plus OCR pattern tests. Native capture, clipboard and full OCR recognition checks run locally in omabox. See CI coverage and the current roadmap.

The real audio backend test runs against its own PulseAudio server and synthetic sources. It is separate from the headless suite. On a devbox with the omaframe-ci:latest image:

docker build --network=host -f tests/audio-pulse.Dockerfile -t omaframe-ci-meter .
docker run --rm --user "$(id -u):$(id -g)" -e HOME=/tmp -v "$PWD:/src" -w /src omaframe-ci-meter ctest --test-dir build-ci -L audio-server -V

Build build-ci with testing enabled first. This checks synthetic audio only; physical microphones and Bluetooth devices need a separate hardware check.

License

MIT. The native Wayland capture code is adapted from Omasnap at acfb3b5772ccb041b57ccc76e16f1b72719f37e9, copyright Tobi Lütke, and its license is kept in docs/OMASNAP-LICENSE. MatteShot and Omaroll informed the workflow and style; Omaframe has its own interface and renderer.