VisionHub — Omarchy Plugin

Live view and health monitoring of RTSP IP cameras directly in your Omarchy shell bar and desktop. Displays an at-a-glance camera status counter on the top bar and expands into a floating multi-camera grid with single-camera focused view.

Showcase

Multi-Camera Grid View

Configurable live overview of all surveillance feeds with instant reachability status pills and custom camera naming.

Focused Cinema Live View

High-framerate focused stream with interactive FPS switcher, live RTSP audio playback toggle, HUD telemetry, and bottom carousel strip navigation.

Features

• Top Bar Health Widget: Compact status pill displaying active online camera count (e.g. 󰹗 4/4), offline warnings, and hover tooltips with detailed status for each configured camera.
• Floating Live View Window: Themed desktop window featuring a configurable multi-camera grid and high-framerate focused single-camera view.
• Resource Efficient & Isolated: RTSP streams decode in crash-isolated background ffmpeg worker processes managed by an asynchronous Ruby daemon. Only visible cameras consume streaming resources.
• tmpfs Fast Frame Buffer: Video frames stream directly into RAM ($XDG_RUNTIME_DIR/vision-hub), protecting SSD longevity and ensuring zero latency UI rendering.
• Hardware Acceleration Support: Automatic hardware-accelerated video decoding (VAAPI / CUDA / Vulkan / QSV).
• Secure Credential Storage: Camera passwords reside safely in your system keyring (gnome-keyring / secret-tool) and are never written to disk or exposed in configuration files.
• Non-Blocking TCP Health Probes: Proactive reachability checks detect offline cameras without stalling the UI.

Requirements

• Ruby 3.4+ (standard on Arch/Omarchy; verify with ruby --version)
• ffmpeg (with RTSP protocol support)
• secret-tool (libsecret / GNOME Keyring)
• Omarchy Shell (Quickshell / Hyprland)

Installation & Removal

Install

Install and enable the plugin directly from git:

omarchy plugin add https://github.com/tobiasz-p/vision-hub.git --enable

Or clone manually into ~/.config/omarchy/plugins/tobiasz-p.vision-hub and enable:

omarchy plugin enable tobiasz-p.vision-hub

Or place it in a specific bar position:

omarchy bar put tobiasz-p.vision-hub --section right

Disable & Remove

Disable the plugin:

omarchy plugin disable tobiasz-p.vision-hub

Remove the plugin:

omarchy plugin remove tobiasz-p.vision-hub

Configuration

1. Camera Definitions

Create ~/.config/vision-hub/cameras.json:

{
  "cameras": [
    {
      "id": "front",
      "name": "Front Door",
      "host": "192.168.1.101",
      "port": 554,
      "username": "admin",
      "mainPath": "/Streaming/channels/101",
      "subPath": "/Streaming/channels/102"
    },
    {
      "id": "backyard",
      "name": "Backyard",
      "host": "192.168.1.102",
      "port": 554,
      "username": "admin",
      "mainPath": "/live/ch0",
      "subPath": "/live/ch1"
    }
  ]
}

2. Store Credentials in Keyring

Camera passwords are stored securely in GNOME Keyring using secret-tool.

Option A: Single shared password for all cameras

If all cameras share the same password, store a single default entry:

secret-tool store --label='VisionHub default camera' application tobiasz-p.vision-hub camera default

Option B: Per-camera passwords

Store specific passwords for individual cameras by matching the id defined in cameras.json (takes precedence over the default):

secret-tool store --label='VisionHub camera front' application tobiasz-p.vision-hub camera front

secret-tool store --label='VisionHub camera backyard' application tobiasz-p.vision-hub camera backyard

3. Widget Settings

Settings can be customized via omarchy bar set:

Example:

omarchy bar set tobiasz-p.vision-hub gridColumns 2
omarchy bar set tobiasz-p.vision-hub targetFps 10

Gestures & Controls

Contributing

Contributions are welcome! To help keep the codebase clean and git history maintainable, please follow these guidelines when opening a Pull Request.

Workflow & Creating a PR

1. Fork the repository on GitHub to your personal account.
2. Clone your fork and add the upstream repository as a remote:

   git clone https://github.com/<your-username>/vision-hub.git
   cd vision-hub
   git remote add upstream https://github.com/tobiasz-p/vision-hub.git
   

3. Create a feature branch:

   git checkout -b feat/your-feature-name
   # or
   git checkout -b fix/issue-description
   

4. Make your changes: Verify test suites and linters pass locally:

   bundle exec rake
   omarchy plugin validate ~/.config/omarchy/plugins/tobiasz-p.vision-hub
   

5. Push to your fork:

   git push -u origin feat/your-feature-name
   

6. Open a Pull Request: Submit a PR from your branch against upstream/main with a clear description of the changes.

Commit Guidelines

We follow Conventional Commits. Write concise, descriptive commit messages in the imperative mood:

<type>(<optional scope>): <description>

Common Types:

• feat: A new feature or capability
• fix: A bug fix
• docs: Documentation updates
• refactor: Code changes that neither fix a bug nor add a feature
• style: Formatting or UI styling adjustments without logic changes
• test: Adding or updating tests
• chore: Maintenance tasks, dependency updates, or toolchain configuration

Examples:

• feat: add support for custom stream transport protocols
• fix: handle ffmpeg restart edge case during rapid window toggle
• docs: update camera configuration examples for ONVIF profiles

Meaningful Commits & Linear History

• Meaningful Commits Only: Each commit should represent a complete, logical unit of work. Avoid leaving intermediate "WIP", "fix typo", or "checkpoint" commits in the history.
• Squash Fixups: Squash or rebase intermediate commits locally (git rebase -i) before submitting or finalizing your PR.
• Linear History: We maintain a strictly linear git history. PRs will be rebased onto main (no merge commits). Make sure your branch is up-to-date with upstream:

  git pull --rebase upstream main
  

License

MIT License. Copyright (c) 2026 tobiasz-p.