rubycam-gtk 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0d4db566e44eb16348e92c1dadace1af5af4b180fc4de621d6e98becf58f1fee
+  data.tar.gz: 9e4971aaed8f96f29f0c012fcd42ded2385a7b0e6e72281b33d3feb8a73da113
+SHA512:
+  metadata.gz: e5f71af7207517401c84216fbad6b1c144bd75ec384dc534a7a37df83bb98bc20a255a852f60d1b0b40255f75913f18670f4a9e94c71f644ec7de6815293f1e3
+  data.tar.gz: 0fe2370563fa78126edae0f5bda0845f3c9e1437c9647be5c23eb2cf71292bcd856d2c57decdb33c1f344c55ec163cccc60479621b60cd6098cb00c4a3001d14

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nathan Kidd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,148 @@
+# rubycam
+
+Pure-Ruby V4L2 webcam library plus a GTK4 viewer, built against an OBSBOT
+Tiny 2. No C extension and no GStreamer: controls go through `ioctl` and
+frames come from memory-mapped kernel buffers via Fiddle.
+
+The OBSBOT is a standard UVC device, so the kernel's `uvcvideo` driver
+already handles it — this library talks V4L2 and works with any UVC webcam.
+
+## Install
+
+Two gems ship from this repo:
+
+| Gem           | Provides                                   | Depends on          |
+| ------------- | ------------------------------------------ | ------------------- |
+| `rubycam`     | the V4L2/OBSBOT library and the `rubycam` CLI | `dry-cli`        |
+| `rubycam-gtk` | the GTK4 viewer and the `rubycam-gtk` app  | `rubycam`, `gtk4`   |
+
+```sh
+gem install rubycam       # library + CLI (pure Ruby, light install)
+gem install rubycam-gtk   # adds the GTK4 viewer (pulls in the GTK stack)
+```
+
+The `rubycam` gem has no dependencies beyond `dry-cli`; the GTK stack only
+comes in with `rubycam-gtk`.
+
+## Library
+
+```ruby
+require 'rubycam'
+
+Rubycam::Device.open('/dev/video0') do |cam|
+  cam.controls.each_value { |c| puts c }   # discover controls
+  cam[:zoom_absolute] = 50                 # get/set by symbol
+  cam[:pan_absolute] = 20 * 3600           # gimbal units: 1/3600 degree
+
+  cam.set_format(width: 1920, height: 1080, pixel_format: 'MJPG')
+  cam.set_fps(30)
+  File.binwrite('frame.jpg', cam.capture_frame)  # blocking
+  cam.poll_frame                                 # non-blocking, nil if not ready
+end
+```
+
+OBSBOT vendor commands go through the camera's UVC extension unit — the
+same channel the official OBSBOT software uses (protocol from the
+[Tiny4Linux](https://github.com/OpenFoxes/Tiny4Linux) project; see
+`TINY4LINUX_FEATURES.md` for the full feature map):
+
+```ruby
+cam = Rubycam::Device.find('OBSBOT Tiny 2')  # path, /dev name or card/bus hint
+bot = Rubycam::Obsbot.new(cam)
+bot.status   # => { asleep: false, hdr: true, ai_mode: :no_tracking,
+             #      tracking_speed: :standard }
+bot.sleep!   # privacy sleep (gimbal folds down)
+bot.wake!    # wakes even after the camera was folded down by hand
+
+bot.ai_mode = :normal_tracking  # :no_tracking :upper_body :close_up :headless
+                                # :lower_body :desk_mode :whiteboard :hand :group
+bot.tracking_speed = :sport     # or :standard
+bot.goto_preset(0)              # stored gimbal positions 0..2
+bot.hdr = true
+bot.exposure_mode = :face       # :manual, :global or :face
+
+bot.debug = true                # log raw traffic to stderr
+bot.send_hex('16 02 00 00')     # raw command to the extension unit
+bot.dump                        # current status block as hex
+```
+
+Notes:
+
+- The camera delivers 4K@30 / 1080p@60 in MJPG; frames are JPEG strings.
+- Folding the camera down by hand is privacy sleep; V4L2 keeps working but
+  video stops. `Obsbot#wake!` is the only software way back.
+- Writing `tilt_absolute` to its minimum does NOT trigger privacy sleep —
+  that gesture is hardware-only.
+- The first frame after STREAMON takes a few seconds (ISP startup).
+- On newer Tiny 2 firmware the status block lags mode changes by seconds
+  and reports tracking speed at byte 0x24 instead of 0x21 (both handled).
+
+## Viewer app
+
+With `rubycam-gtk` installed the viewer is on your PATH:
+
+```sh
+rubycam-gtk                    # first camera at /dev/video0
+rubycam-gtk /dev/video2        # explicit device
+rubycam-gtk 'OBSBOT Tiny 2'    # find by name
+
+rubycam-gtk --obsbot           # full OBSBOT viewer (default)
+rubycam-gtk --v4l2             # generic V4L2 viewer, no OBSBOT features
+```
+
+From a checkout, use the dev shell (it provides the native GTK libs):
+
+```sh
+nix develop            # or let direnv do it (.envrc: use flake)
+bundle install         # or bin/setup
+rubycam-gtk            # exe/ is on PATH via direnv
+```
+
+Live preview, sliders for gimbal/zoom/image controls, and an OBSBOT panel
+with power switch, live status, AI tracking modes, tracking speed, preset
+positions, HDR, exposure modes and a raw-hex debug console. The ⤢ button
+toggles a compact widget mode (panel only); if the camera disappears the
+app keeps polling and reconnects when it returns.
+
+`--v4l2` launches the same live preview and control sliders without any of
+the OBSBOT panel or vendor commands, so it works with any UVC webcam.
+
+## CLI
+
+Everything the OBSBOT panel does, scriptable — shipped by the `rubycam`
+gem (needs only Ruby + the `dry-cli` gem, no GTK):
+
+```sh
+rubycam                      # list commands
+rubycam status               # sleep state, AI mode, speed, HDR
+rubycam wake                 # wake from privacy sleep
+rubycam track upper_body     # AI tracking mode
+rubycam speed sport
+rubycam preset 2             # gimbal preset 1-3
+rubycam hdr off
+rubycam exposure face
+
+rubycam devices              # every /dev/video* node
+rubycam controls             # V4L2 controls with ranges
+rubycam set zoom_absolute 50
+rubycam reset                # all controls back to defaults
+rubycam snapshot shot.jpg --width=3840 --height=2160
+
+rubycam xu dump              # debug: status block as hex
+rubycam xu send '16 02 02 00' --selector=0x06
+```
+
+Generic V4L2 commands default to `/dev/video0`; OBSBOT commands find the
+camera by name. Both take `-d` to target a path, `/dev` name or card/bus
+substring.
+
+## Examples
+
+```sh
+ruby examples/snapshot.rb            # capture snapshot.jpg
+ruby examples/controls.rb            # list all controls
+ruby examples/controls.rb zoom_absolute 50
+```
+
+The library itself has no dependencies beyond the Ruby stdlib; only the
+GTK viewer needs the dev shell and `bundle install`.

data/exe/rubycam-gtk

@@ -0,0 +1,41 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+#
+# Launch the Rubycam GTK viewer.
+#
+#   rubycam-gtk                  # OBSBOT viewer, first camera at /dev/video0
+#   rubycam-gtk /dev/video2      # explicit device node
+#   rubycam-gtk 'OBSBOT Tiny 2'  # find by card/bus name
+#
+#   rubycam-gtk --obsbot         # full OBSBOT panel (default)
+#   rubycam-gtk --v4l2           # generic V4L2 viewer, no OBSBOT features
+USAGE = <<~TEXT
+  Usage: rubycam-gtk [options] [device]
+
+    device                Device path, /dev name, or card/bus-name substring
+                          (default: /dev/video0)
+
+  Options:
+    --obsbot              Full OBSBOT panel (default)
+    --v4l2                Generic V4L2 viewer, no OBSBOT features
+    -h, --help            Show this message
+
+  Examples:
+    rubycam-gtk                  # OBSBOT viewer, first camera at /dev/video0
+    rubycam-gtk /dev/video2      # explicit device node
+    rubycam-gtk 'OBSBOT Tiny 2'  # find by card/bus name
+TEXT
+
+if ARGV.include?("--help") || ARGV.include?("-h")
+  puts USAGE
+  exit
+end
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+require "rubycam/gtk"
+
+args = ARGV.dup
+mode = args.delete("--v4l2") ? Rubycam::GTK::Video4Linux : nil
+mode = Rubycam::GTK::CameraApp if args.delete("--obsbot") || mode.nil?
+
+mode.new(args.fetch(0, "/dev/video0")).build.run

data/lib/rubycam/gtk/camera_app.rb

@@ -0,0 +1,291 @@
+# Live OBSBOT viewer: video preview, gimbal/zoom/image sliders, plus the
+# full Tiny4Linux control set (tracking, presets, speed, HDR, exposure,
+# debug console) in the OBSBOT panel. Launched by exe/rubycam-gtk.
+require 'gtk4'
+require 'rubycam'
+require_relative 'obsbot_panel'
+
+module Rubycam
+  module GTK; end
+end
+
+class Rubycam::GTK::CameraApp
+  FRAME_INTERVAL_MS = 16
+  SLIDER_KEYS = %i[pan_absolute tilt_absolute zoom_absolute
+                   brightness contrast saturation sharpness].freeze
+  FULL_SIZE = [1380, 640].freeze
+  COMPACT_SIZE = [340, 640].freeze
+
+  def initialize(device_path)
+    @device_path = device_path
+    @awake = true
+  end
+
+  def build
+    app.tap do
+      app.signal_connect('activate') do
+        app.add_window(window)
+
+        window.tap do |win|
+          win.title = begin
+            device.card
+          rescue SystemCallError
+            'Rubycam (no camera)'
+          end
+          win.set_default_size(*FULL_SIZE)
+          win.child = layout
+
+          win.signal_connect('close-request') do
+            GLib::Source.remove(@pump) if @pump
+            close_device
+            false
+          end
+        end
+
+        layout.tap do |l|
+          l.append(picture)
+          l.append(sidebar)
+          l.append(panel.build)
+
+          sidebar.tap do |side|
+            sliders.each_value { |s| side.append(s) }
+            side.append(reset_button)
+            @sliders_in_sidebar = !sliders.empty?
+
+            reset_button.tap do |btn|
+              btn.signal_connect('clicked') { reset_controls }
+            end
+          end
+        end
+
+        start_frame_pump
+        start_status_sync
+        window.present
+      end
+    end
+  end
+
+  # Accepts a device path, a /dev name, or a card/bus substring
+  # (e.g. 'OBSBOT Tiny 2').
+  def device
+    @device ||= (Rubycam::Device.find(@device_path) or
+                 raise Errno::ENOENT, @device_path).tap do |cam|
+      cam.set_format(width: 1280, height: 720, pixel_format: 'MJPG')
+      cam.set_fps(30)
+    end
+  end
+
+  def app = @app ||= Gtk::Application.new('org.rubycam.viewer', :default_flags)
+  def window = @window ||= Gtk::ApplicationWindow.new(app)
+  def layout = @layout ||= Gtk::Box.new(:horizontal, 12)
+
+  def panel
+    @panel ||= Rubycam::GTK::ObsbotPanel.new(bot: -> { obsbot },
+                               on_wake: -> { wake_camera },
+                               on_sleep: -> { sleep_camera },
+                               on_compact_toggle: -> { toggle_compact })
+  end
+
+  def picture
+    @picture ||= Gtk::Picture.new.tap do |pic|
+      pic.hexpand = true
+      pic.vexpand = true
+      pic.margin_start = 12
+      pic.margin_top = 12
+      pic.margin_bottom = 12
+    end
+  end
+
+  def sidebar
+    @sidebar ||= Gtk::Box.new(:vertical, 6).tap do |box|
+      box.margin_top = 12
+      box.margin_bottom = 12
+      box.width_request = 260
+    end
+  end
+
+  def sliders
+    @sliders ||= SLIDER_KEYS.filter_map do |key|
+      device.controls[key]&.then { |ctrl| [key, slider_for(ctrl)] }
+    end.to_h
+  rescue SystemCallError
+    {}
+  end
+
+  def reset_button
+    @reset_button ||= Gtk::Button.new(label: 'Reset to defaults').tap do |btn|
+      btn.margin_top = 12
+    end
+  end
+
+  def slider_for(ctrl)
+    Gtk::Box.new(:vertical, 2).tap do |box|
+      box.append(Gtk::Label.new(ctrl.key.to_s).tap { |l| l.halign = :start })
+      box.append(
+        Gtk::Scale.new(:horizontal,
+                       Gtk::Adjustment.new(ctrl.value, ctrl.min, ctrl.max,
+                                           ctrl.step, ctrl.step * 10, 0)).tap do |scale|
+          scale.draw_value = false
+          scale.signal_connect('value-changed') do
+            set_control_safely(ctrl.key, scale.value.round)
+          end
+        end
+      )
+    end
+  end
+
+  def obsbot = @obsbot ||= Rubycam::Obsbot.new(device)
+
+  # Dashboard ⇄ compact widget mode: compact hides the preview and the V4L2
+  # sliders, leaving just the OBSBOT panel (like Tiny4Linux's widget mode).
+  def toggle_compact
+    @compact = !@compact
+    picture.visible = !@compact
+    sidebar.visible = !@compact
+    window.set_default_size(*(@compact ? COMPACT_SIZE : FULL_SIZE))
+  end
+
+  # Sleep/wake go through OBSBOT's vendor extension unit — the same command
+  # its official software sends. This also wakes the camera after it was put
+  # to sleep by physically folding it down.
+  def sleep_camera
+    @awake = false
+    obsbot.sleep!
+  rescue SystemCallError
+    nil
+  end
+
+  def wake_camera
+    @awake = true
+    obsbot.wake!
+    # Grace period for the stream to resume on its own before the
+    # watchdog rebuilds it.
+    @last_frame_at = monotonic_now
+  rescue SystemCallError
+    nil
+  end
+
+  # After this many consecutive failed polls the camera is treated as gone
+  # (a transient EIO during privacy-sleep transitions must not trigger a
+  # disruptive reconnect).
+  STATUS_FAILURES_BEFORE_RECONNECT = 3
+
+  def start_status_sync
+    GLib::Timeout.add_seconds(2) do
+      sync_status
+      GLib::Source::CONTINUE
+    end
+  end
+
+  # Poll the camera and mirror its state into the panel, so the UI follows
+  # changes made outside the app (folding the camera down, other software).
+  def sync_status
+    obsbot.status.then do |status|
+      @awake = !status[:asleep]
+      @failures = 0
+      panel.update(status)
+    end
+  rescue SystemCallError
+    @failures = (@failures || 0) + 1
+    reconnect_camera if @failures >= STATUS_FAILURES_BEFORE_RECONNECT
+  end
+
+  # The camera is gone (unplugged or re-enumerated): drop the dead handle
+  # and try to find it again on every poll until it returns.
+  def reconnect_camera
+    panel.update(nil)
+    close_device
+    device.then do
+      @failures = 0
+      @last_frame_at = monotonic_now
+      restore_sliders
+    end
+  rescue SystemCallError
+    nil
+  end
+
+  def close_device
+    @device&.close
+  rescue SystemCallError
+    nil
+  ensure
+    @device = nil
+    @obsbot = nil
+  end
+
+  # When the app started without a camera the sidebar has no sliders yet;
+  # build and attach them on first successful (re)connect.
+  def restore_sliders
+    unless @sliders_in_sidebar || sliders.empty?
+      sliders.each_value { |s| sidebar.append(s) }
+      sidebar.reorder_child_after(reset_button, sidebar.last_child)
+      @sliders_in_sidebar = true
+    end
+  end
+
+  def reset_controls
+    sliders.each_key do |key|
+      device.controls[key].then do |ctrl|
+        set_control_safely(key, ctrl.default)
+        slider_scale(key).value = ctrl.default
+      end
+    end
+  end
+
+  def slider_scale(key) = sliders[key].last_child
+
+  def control_value(key)
+    device.controls[key].value
+  rescue SystemCallError
+    nil
+  end
+
+  # Control writes can fail transiently (EIO/EBUSY) while the camera enters
+  # or leaves privacy sleep; an exception here must never kill the main loop.
+  def set_control_safely(key, value)
+    device.controls[key].value = value
+  rescue SystemCallError
+    nil
+  end
+
+  def start_frame_pump
+    @last_frame_at = monotonic_now
+    @pump = GLib::Timeout.add(FRAME_INTERVAL_MS) do
+      pump_one_frame if @device
+      GLib::Source::CONTINUE
+    end
+  end
+
+  # Longer than the camera's first-frame latency, so warmup after a stream
+  # (re)start is never mistaken for a dead stream.
+  WATCHDOG_SECONDS = 5
+
+  def pump_one_frame
+    device.poll_frame.then do |frame|
+      if frame
+        @last_frame_at = monotonic_now
+        show_frame(frame)
+      elsif @awake && monotonic_now - (@last_frame_at || 0) > WATCHDOG_SECONDS
+        # Video should be flowing but is not (e.g. the camera slept and woke
+        # outside our control): rebuild the stream until frames return.
+        @last_frame_at = monotonic_now
+        warn 'video stalled: rebuilding stream'
+        device.restart_streaming
+      end
+    end
+  rescue SystemCallError, RuntimeError
+    nil # stream hiccup (e.g. privacy sleep transition): keep the pump alive
+  end
+
+  def monotonic_now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+  def show_frame(jpeg)
+    GdkPixbuf::PixbufLoader.new.tap do |loader|
+      loader.write(jpeg)
+      loader.close
+      picture.pixbuf = loader.pixbuf
+    end
+  rescue GLib::Error
+    nil # drop corrupt frames rather than crashing the pump
+  end
+end

data/lib/rubycam/gtk/obsbot_panel.rb

@@ -0,0 +1,426 @@
+# OBSBOT control panel: the Tiny4Linux GUI feature set as one widget —
+# sleep/wake, live status, presets, tracking modes, tracking speed, HDR,
+# exposure modes and a raw-hex debug console. Talks to the camera through
+# the injected bot getter so a reconnect (new Obsbot) is picked up
+# transparently.
+module Rubycam
+  module GTK; end
+end
+
+class Rubycam::GTK::ObsbotPanel
+  AI_MODE_LABELS = { no_tracking: 'Static', normal_tracking: 'Normal',
+                     close_up: 'Close-up', upper_body: 'Upper Body',
+                     headless: 'Headless', lower_body: 'Lower Body',
+                     desk_mode: 'Desk', whiteboard: 'Whiteboard',
+                     hand: 'Hand', group: 'Group' }.freeze
+  SPEED_LABELS = { standard: 'Standard', sport: 'Sport' }.freeze
+  EXPOSURE_LABELS = { manual: 'Manual', global: 'Global', face: 'Face' }.freeze
+  STATS = { sleep: 'State', tracking: 'Tracking', speed: 'Speed',
+            hdr: 'HDR', version: 'Version' }.freeze
+
+  def initialize(bot:, on_wake:, on_sleep:, on_compact_toggle:)
+    @bot = bot
+    @on_wake = on_wake
+    @on_sleep = on_sleep
+    @on_compact_toggle = on_compact_toggle
+  end
+
+  def build
+    @build ||= scroller.tap do |sc|
+      sc.child = root
+
+      root.tap do |r|
+        r.append(header_row)
+        r.append(connection_label)
+        r.append(power_row)
+        r.append(stats_grid)
+        r.append(presets_row)
+        r.append(tracking_heading)
+        r.append(tracking_grid)
+        r.append(speed_row)
+        r.append(hdr_row)
+        r.append(exposure_row)
+        r.append(debug_toggle)
+        r.append(debug_revealer)
+
+        header_row.tap do |row|
+          row.append(title_label)
+          row.append(compact_button)
+
+          compact_button.signal_connect('clicked') { @on_compact_toggle.call }
+        end
+
+        power_row.tap do |row|
+          row.append(power_label)
+          row.append(power_switch)
+
+          power_switch.signal_connect('state-set') do |_, on|
+            (on ? @on_wake : @on_sleep).call unless @syncing
+            false
+          end
+        end
+
+        stats_grid.tap do |g|
+          STATS.each_key.with_index do |key, i|
+            g.attach(stat_name_labels[key], 0, i, 1, 1)
+            g.attach(stat_labels[key], 1, i, 1, 1)
+          end
+          stat_labels[:version].label = Rubycam::VERSION
+        end
+
+        presets_row.tap do |row|
+          row.append(presets_label)
+          preset_buttons.each_with_index do |btn, i|
+            row.append(btn)
+            btn.signal_connect('clicked') { goto_preset(i) }
+          end
+        end
+
+        tracking_grid.tap do |g|
+          tracking_buttons.each_with_index do |(mode, btn), i|
+            g.attach(btn, i % 2, i / 2, 1, 1)
+            btn.signal_connect('clicked') { set_tracking(mode) }
+          end
+        end
+
+        speed_row.tap do |row|
+          row.append(speed_label)
+          speed_buttons.each do |speed, btn|
+            row.append(btn)
+            btn.signal_connect('clicked') { set_speed(speed) }
+          end
+        end
+
+        hdr_row.tap do |row|
+          row.append(hdr_label)
+          row.append(hdr_toggle)
+
+          hdr_toggle.signal_connect('toggled') do
+            command { |bot| bot.hdr = hdr_toggle.active? } unless @syncing
+          end
+        end
+
+        exposure_row.tap do |row|
+          row.append(exposure_label)
+          exposure_buttons.each do |mode, btn|
+            row.append(btn)
+            btn.signal_connect('clicked') { command { |bot| bot.exposure_mode = mode } }
+          end
+        end
+
+        debug_toggle.signal_connect('toggled') { toggle_debug }
+
+        debug_revealer.tap do |rev|
+          rev.child = debug_box
+
+          debug_box.tap do |dbg|
+            dbg.append(hex06_row)
+            dbg.append(hex02_row)
+            dbg.append(dump_row)
+            dbg.append(debug_output)
+
+            hex06_row.tap do |row|
+              row.append(hex06_entry)
+              row.append(hex06_send)
+              hex06_entry.signal_connect('activate') { send_hex(hex06_entry, Rubycam::Obsbot::SELECTOR_STATUS) }
+              hex06_send.signal_connect('clicked') { send_hex(hex06_entry, Rubycam::Obsbot::SELECTOR_STATUS) }
+            end
+
+            hex02_row.tap do |row|
+              row.append(hex02_entry)
+              row.append(hex02_send)
+              hex02_entry.signal_connect('activate') { send_hex(hex02_entry, Rubycam::Obsbot::SELECTOR_COMMAND) }
+              hex02_send.signal_connect('clicked') { send_hex(hex02_entry, Rubycam::Obsbot::SELECTOR_COMMAND) }
+            end
+
+            dump_row.tap do |row|
+              row.append(dump06_button)
+              row.append(dump02_button)
+              dump06_button.signal_connect('clicked') { show_dump(Rubycam::Obsbot::SELECTOR_STATUS) }
+              dump02_button.signal_connect('clicked') { show_dump(Rubycam::Obsbot::SELECTOR_COMMAND) }
+            end
+          end
+        end
+      end
+    end
+  end
+
+  # Mirror camera state into the panel. A nil status means no camera.
+  def update(status)
+    @syncing = true
+    connection_label.label = status ? 'Connected' : 'No camera detected — searching…'
+    stat_labels[:sleep].label = status ? (status[:asleep] ? 'Sleeping' : 'Awake') : '—'
+    stat_labels[:tracking].label = status ? AI_MODE_LABELS.fetch(status[:ai_mode], 'Unknown') : '—'
+    stat_labels[:speed].label = status ? SPEED_LABELS.fetch(status[:tracking_speed]) : '—'
+    stat_labels[:hdr].label = status ? (status[:hdr] ? 'On' : 'Off') : '—'
+    status&.then do |s|
+      power_switch.active = !s[:asleep]
+      hdr_toggle.active = s[:hdr]
+      highlight(tracking_buttons, s[:ai_mode])
+      highlight(speed_buttons, s[:tracking_speed])
+    end
+    @syncing = false
+  end
+
+  private
+
+  # Commands can fail transiently (camera asleep or unplugged) or on bad
+  # hex input; report failure instead of crashing the main loop.
+  def command
+    yield @bot.call
+    true
+  rescue SystemCallError, ArgumentError
+    false
+  end
+
+  def highlight(buttons, active_key)
+    buttons.each do |key, btn|
+      key == active_key ? btn.add_css_class('suggested-action') : btn.remove_css_class('suggested-action')
+    end
+  end
+
+  def set_tracking(mode)
+    command { |bot| bot.ai_mode = mode }
+    highlight(tracking_buttons, mode)
+  end
+
+  def set_speed(speed)
+    command { |bot| bot.tracking_speed = speed }
+    highlight(speed_buttons, speed)
+  end
+
+  # The camera ignores preset moves while tracking, so tracking is switched
+  # off first — same order as the official software.
+  def goto_preset(number)
+    command do |bot|
+      bot.ai_mode = :no_tracking
+      bot.goto_preset(number)
+    end
+    highlight(tracking_buttons, :no_tracking)
+  end
+
+  def toggle_debug
+    debug_revealer.reveal_child = debug_toggle.active?
+    command { |bot| bot.debug = debug_toggle.active? }
+  end
+
+  def send_hex(entry, selector)
+    debug_output.label =
+      command { |bot| bot.send_hex(entry.text, selector: selector) } ? 'Sent.' : 'Failed (bad hex or camera error).'
+  end
+
+  def show_dump(selector)
+    command { |bot| debug_output.label = bot.dump(selector).scan(/.{1,8}/).join(' ') }
+      .then { |ok| debug_output.label = 'Failed (camera error).' unless ok }
+  end
+
+  def scroller
+    @scroller ||= Gtk::ScrolledWindow.new.tap do |sc|
+      sc.set_policy(:never, :automatic)
+      sc.width_request = 330
+    end
+  end
+
+  def root
+    @root ||= Gtk::Box.new(:vertical, 10).tap do |b|
+      b.margin_top = 12
+      b.margin_bottom = 12
+      b.margin_start = 6
+      b.margin_end = 12
+    end
+  end
+
+  def header_row = @header_row ||= Gtk::Box.new(:horizontal, 8)
+
+  def title_label
+    @title_label ||= Gtk::Label.new('OBSBOT').tap do |l|
+      l.halign = :start
+      l.hexpand = true
+      l.add_css_class('heading')
+    end
+  end
+
+  def compact_button
+    @compact_button ||= Gtk::Button.new.tap do |b|
+      b.icon_name = 'view-restore-symbolic'
+      b.tooltip_text = 'Toggle compact widget mode'
+      b.halign = :end
+    end
+  end
+
+  def connection_label
+    @connection_label ||= Gtk::Label.new('Connecting…').tap do |l|
+      l.xalign = 0
+      l.add_css_class('dim-label')
+    end
+  end
+
+  def power_row = @power_row ||= Gtk::Box.new(:horizontal, 8)
+
+  def power_label
+    @power_label ||= Gtk::Label.new('Camera').tap do |l|
+      l.halign = :start
+      l.hexpand = true
+    end
+  end
+
+  def power_switch
+    @power_switch ||= Gtk::Switch.new.tap do |sw|
+      sw.active = true
+      sw.halign = :end
+    end
+  end
+
+  def stats_grid
+    @stats_grid ||= Gtk::Grid.new.tap do |g|
+      g.row_spacing = 4
+      g.column_spacing = 12
+    end
+  end
+
+  def stat_name_labels
+    @stat_name_labels ||= STATS.to_h do |key, name|
+      [key, Gtk::Label.new("#{name}:").tap do |l|
+        l.xalign = 0
+        l.hexpand = true
+        l.add_css_class('dim-label')
+      end]
+    end
+  end
+
+  def stat_labels
+    @stat_labels ||= STATS.keys.to_h do |key|
+      [key, Gtk::Label.new('—').tap { |l| l.xalign = 1 }]
+    end
+  end
+
+  def presets_row = @presets_row ||= Gtk::Box.new(:horizontal, 6)
+
+  def presets_label
+    @presets_label ||= Gtk::Label.new('Presets:').tap do |l|
+      l.xalign = 0
+      l.hexpand = true
+    end
+  end
+
+  def preset_buttons
+    @preset_buttons ||= (1..3).map do |n|
+      Gtk::Button.new(label: n.to_s).tap { |b| b.tooltip_text = "Go to preset position #{n}" }
+    end
+  end
+
+  def tracking_heading
+    @tracking_heading ||= Gtk::Label.new('Tracking mode').tap do |l|
+      l.xalign = 0
+      l.add_css_class('dim-label')
+    end
+  end
+
+  def tracking_grid
+    @tracking_grid ||= Gtk::Grid.new.tap do |g|
+      g.row_spacing = 6
+      g.column_spacing = 6
+      g.column_homogeneous = true
+    end
+  end
+
+  def tracking_buttons
+    @tracking_buttons ||= AI_MODE_LABELS.transform_values do |label|
+      Gtk::Button.new(label: label).tap { |b| b.tooltip_text = "Set tracking mode: #{label}" }
+    end
+  end
+
+  def speed_row = @speed_row ||= Gtk::Box.new(:horizontal, 6)
+
+  def speed_label
+    @speed_label ||= Gtk::Label.new('Speed:').tap do |l|
+      l.xalign = 0
+      l.hexpand = true
+    end
+  end
+
+  def speed_buttons
+    @speed_buttons ||= SPEED_LABELS.transform_values do |label|
+      Gtk::Button.new(label: label).tap { |b| b.tooltip_text = "Set tracking speed: #{label}" }
+    end
+  end
+
+  def hdr_row = @hdr_row ||= Gtk::Box.new(:horizontal, 6)
+
+  def hdr_label
+    @hdr_label ||= Gtk::Label.new('HDR:').tap do |l|
+      l.xalign = 0
+      l.hexpand = true
+    end
+  end
+
+  def hdr_toggle
+    @hdr_toggle ||= Gtk::ToggleButton.new.tap do |b|
+      b.label = 'HDR'
+      b.tooltip_text = 'Toggle HDR'
+    end
+  end
+
+  def exposure_row = @exposure_row ||= Gtk::Box.new(:horizontal, 6)
+
+  def exposure_label
+    @exposure_label ||= Gtk::Label.new('Exposure:').tap do |l|
+      l.xalign = 0
+      l.hexpand = true
+    end
+  end
+
+  def exposure_buttons
+    @exposure_buttons ||= EXPOSURE_LABELS.transform_values do |label|
+      Gtk::Button.new(label: label).tap { |b| b.tooltip_text = "Set exposure mode: #{label}" }
+    end
+  end
+
+  def debug_toggle
+    @debug_toggle ||= Gtk::ToggleButton.new.tap do |b|
+      b.label = 'Debug console'
+      b.tooltip_text = 'Log commands to stderr and send raw hex'
+    end
+  end
+
+  def debug_revealer
+    @debug_revealer ||= Gtk::Revealer.new.tap do |r|
+      r.transition_type = :slide_down
+      r.reveal_child = false
+    end
+  end
+
+  def debug_box = @debug_box ||= Gtk::Box.new(:vertical, 6)
+  def hex06_row = @hex06_row ||= Gtk::Box.new(:horizontal, 6)
+  def hex02_row = @hex02_row ||= Gtk::Box.new(:horizontal, 6)
+  def dump_row = @dump_row ||= Gtk::Box.new(:horizontal, 6)
+
+  def hex06_entry
+    @hex06_entry ||= Gtk::Entry.new.tap do |e|
+      e.placeholder_text = '0x06 hex bytes'
+      e.hexpand = true
+    end
+  end
+
+  def hex02_entry
+    @hex02_entry ||= Gtk::Entry.new.tap do |e|
+      e.placeholder_text = '0x02 hex bytes'
+      e.hexpand = true
+    end
+  end
+
+  def hex06_send = @hex06_send ||= Gtk::Button.new(label: 'Send')
+  def hex02_send = @hex02_send ||= Gtk::Button.new(label: 'Send')
+  def dump06_button = @dump06_button ||= Gtk::Button.new(label: 'Dump 0x06')
+  def dump02_button = @dump02_button ||= Gtk::Button.new(label: 'Dump 0x02')
+
+  def debug_output
+    @debug_output ||= Gtk::Label.new('').tap do |l|
+      l.xalign = 0
+      l.wrap = true
+      l.wrap_mode = :char
+      l.selectable = true
+      l.add_css_class('monospace')
+    end
+  end
+end

data/lib/rubycam/gtk/video4linux.rb

@@ -0,0 +1,236 @@
+# Standalone generic V4L2 viewer: live preview plus sliders for whatever
+# controls the camera exposes. A trimmed copy of CameraApp with no OBSBOT
+# panel or vendor commands, so it works with any UVC webcam. Launched by
+# exe/rubycam-v4l2.
+require 'gtk4'
+require 'rubycam'
+
+module Rubycam
+  module GTK; end
+end
+
+class Rubycam::GTK::Video4Linux
+  FRAME_INTERVAL_MS = 16
+  SLIDER_KEYS = %i[pan_absolute tilt_absolute zoom_absolute
+                   brightness contrast saturation sharpness].freeze
+  WINDOW_SIZE = [1120, 640].freeze
+
+  def initialize(device_path)
+    @device_path = device_path
+  end
+
+  def build
+    app.tap do
+      app.signal_connect('activate') do
+        app.add_window(window)
+
+        window.tap do |win|
+          win.title = window_title
+          win.set_default_size(*WINDOW_SIZE)
+          win.child = layout
+
+          win.signal_connect('close-request') do
+            GLib::Source.remove(@pump) if @pump
+            close_device
+            false
+          end
+        end
+
+        layout.tap do |l|
+          l.append(picture)
+          l.append(sidebar)
+
+          sidebar.tap do |side|
+            sliders.each_value { |s| side.append(s) }
+            side.append(reset_button)
+            @sliders_in_sidebar = !sliders.empty?
+
+            reset_button.tap do |btn|
+              btn.signal_connect('clicked') { reset_controls }
+            end
+          end
+        end
+
+        start_frame_pump
+        start_reconnect_watch
+        window.present
+      end
+    end
+  end
+
+  # Accepts a device path, a /dev name, or a card/bus substring
+  # (e.g. 'Integrated Camera').
+  def device
+    @device ||= (Rubycam::Device.find(@device_path) or
+                 raise Errno::ENOENT, @device_path).tap do |cam|
+      cam.set_format(width: 1280, height: 720, pixel_format: 'MJPG')
+      cam.set_fps(30)
+    end
+  end
+
+  def window_title
+    device.card
+  rescue SystemCallError
+    'Rubycam V4L2 (no camera)'
+  end
+
+  def app = @app ||= Gtk::Application.new('org.rubycam.v4l2', :default_flags)
+  def window = @window ||= Gtk::ApplicationWindow.new(app)
+  def layout = @layout ||= Gtk::Box.new(:horizontal, 12)
+
+  def picture
+    @picture ||= Gtk::Picture.new.tap do |pic|
+      pic.hexpand = true
+      pic.vexpand = true
+      pic.margin_start = 12
+      pic.margin_top = 12
+      pic.margin_bottom = 12
+    end
+  end
+
+  def sidebar
+    @sidebar ||= Gtk::Box.new(:vertical, 6).tap do |box|
+      box.margin_top = 12
+      box.margin_bottom = 12
+      box.margin_end = 12
+      box.width_request = 260
+    end
+  end
+
+  def sliders
+    @sliders ||= SLIDER_KEYS.filter_map do |key|
+      device.controls[key]&.then { |ctrl| [key, slider_for(ctrl)] }
+    end.to_h
+  rescue SystemCallError
+    {}
+  end
+
+  def reset_button
+    @reset_button ||= Gtk::Button.new(label: 'Reset to defaults').tap do |btn|
+      btn.margin_top = 12
+    end
+  end
+
+  def slider_for(ctrl)
+    Gtk::Box.new(:vertical, 2).tap do |box|
+      box.append(Gtk::Label.new(ctrl.key.to_s).tap { |l| l.halign = :start })
+      box.append(
+        Gtk::Scale.new(:horizontal,
+                       Gtk::Adjustment.new(ctrl.value, ctrl.min, ctrl.max,
+                                           ctrl.step, ctrl.step * 10, 0)).tap do |scale|
+          scale.draw_value = false
+          scale.signal_connect('value-changed') do
+            set_control_safely(ctrl.key, scale.value.round)
+          end
+        end
+      )
+    end
+  end
+
+  # After this many consecutive frame-pump errors the camera is treated as
+  # gone (a single hiccup while a stream rebuilds must not drop the handle).
+  STREAM_ERRORS_BEFORE_DROP = 60
+
+  # Drop the dead handle and try to find the camera again on every tick until
+  # it returns (unplugged or re-enumerated).
+  def start_reconnect_watch
+    GLib::Timeout.add_seconds(2) do
+      reconnect_camera unless @device
+      GLib::Source::CONTINUE
+    end
+  end
+
+  def reconnect_camera
+    device.then do
+      @stream_errors = 0
+      @last_frame_at = monotonic_now
+      restore_sliders
+      window.title = window_title
+    end
+  rescue SystemCallError
+    nil
+  end
+
+  def close_device
+    @device&.close
+  rescue SystemCallError
+    nil
+  ensure
+    @device = nil
+  end
+
+  # When the app started without a camera the sidebar has no sliders yet;
+  # build and attach them on first successful (re)connect.
+  def restore_sliders
+    unless @sliders_in_sidebar || sliders.empty?
+      sliders.each_value { |s| sidebar.append(s) }
+      sidebar.reorder_child_after(reset_button, sidebar.last_child)
+      @sliders_in_sidebar = true
+    end
+  end
+
+  def reset_controls
+    sliders.each_key do |key|
+      device.controls[key].then do |ctrl|
+        set_control_safely(key, ctrl.default)
+        slider_scale(key).value = ctrl.default
+      end
+    end
+  end
+
+  def slider_scale(key) = sliders[key].last_child
+
+  # Control writes can fail transiently (EIO/EBUSY); an exception here must
+  # never kill the main loop.
+  def set_control_safely(key, value)
+    device.controls[key].value = value
+  rescue SystemCallError
+    nil
+  end
+
+  def start_frame_pump
+    @last_frame_at = monotonic_now
+    @stream_errors = 0
+    @pump = GLib::Timeout.add(FRAME_INTERVAL_MS) do
+      pump_one_frame if @device
+      GLib::Source::CONTINUE
+    end
+  end
+
+  # Longer than the camera's first-frame latency, so warmup after a stream
+  # (re)start is never mistaken for a dead stream.
+  WATCHDOG_SECONDS = 5
+
+  def pump_one_frame
+    device.poll_frame.then do |frame|
+      if frame
+        @last_frame_at = monotonic_now
+        @stream_errors = 0
+        show_frame(frame)
+      elsif monotonic_now - (@last_frame_at || 0) > WATCHDOG_SECONDS
+        # Video should be flowing but is not: rebuild the stream until frames
+        # return.
+        @last_frame_at = monotonic_now
+        warn 'video stalled: rebuilding stream'
+        device.restart_streaming
+      end
+    end
+  rescue SystemCallError, RuntimeError
+    # Sustained errors mean the camera is gone: drop the handle so the
+    # reconnect watch re-finds it. A one-off hiccup is ignored.
+    @stream_errors = (@stream_errors || 0) + 1
+    close_device if @stream_errors >= STREAM_ERRORS_BEFORE_DROP
+  end
+
+  def monotonic_now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+  def show_frame(jpeg)
+    GdkPixbuf::PixbufLoader.new.tap do |loader|
+      loader.write(jpeg)
+      loader.close
+      picture.pixbuf = loader.pixbuf
+    end
+  rescue GLib::Error
+    nil # drop corrupt frames rather than crashing the pump
+  end
+end

data/lib/rubycam/gtk.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+# Rubycam GTK4 viewer: live preview plus the full OBSBOT control panel.
+# Depends on the rubycam gem for the underlying V4L2 / OBSBOT driver.
+#
+#   require "rubycam/gtk"
+#   Rubycam::GTK::CameraApp.new("/dev/video0").build.run
+require "gtk4"
+require "rubycam"
+
+require_relative "gtk/obsbot_panel"
+require_relative "gtk/camera_app"
+require_relative "gtk/video4linux"

data/rubycam-gtk.gemspec

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require_relative "lib/rubycam/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "rubycam-gtk"
+  spec.version = Rubycam::VERSION
+  spec.authors = ["Nathan Kidd"]
+  spec.email = ["nathankidd@hey.com"]
+
+  spec.summary = "GTK4 viewer for Rubycam webcams (OBSBOT Tiny live preview and controls)"
+
+  spec.description = <<~DESC
+    A GTK4 desktop viewer built on the rubycam library: live video preview,
+    sliders for gimbal/zoom/image controls, and a full OBSBOT Tiny control
+    panel — privacy sleep/wake, AI tracking modes, gimbal presets, tracking
+    speed, HDR, exposure modes and a raw-hex debug console.
+  DESC
+
+  spec.homepage = "https://github.com/ruby-gtk-project/rubycam"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.1.0"
+
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["changelog_uri"] = "#{spec.homepage}/releases"
+  spec.metadata["rubygems_mfa_required"] = "true"
+
+  # The rubycam-gtk gem ships only the viewer; the library itself comes from
+  # the rubycam runtime dependency below.
+  spec.files = `git ls-files -z`.split("\x0").select do |f|
+    f.start_with?("lib/rubycam/gtk") ||
+      f == "exe/rubycam-gtk" ||
+      f == "rubycam-gtk.gemspec" ||
+      %w[README.md LICENSE].include?(f)
+  end
+  spec.bindir = "exe"
+  spec.executables = ["rubycam-gtk"]
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "rubycam", Rubycam::VERSION
+  spec.add_dependency "gtk4", "~> 4.2"
+  spec.add_dependency "gdk_pixbuf2", "~> 4.2"
+
+  spec.add_development_dependency "minitest", "~> 5.0"
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "rubocop", "~> 1.21"
+  spec.add_development_dependency "lefthook", "~> 2.1"
+end

metadata

@@ -0,0 +1,154 @@
+--- !ruby/object:Gem::Specification
+name: rubycam-gtk
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- Nathan Kidd
+bindir: exe
+cert_chain: []
+date: 1980-01-01 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rubycam
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.1.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.1.1
+- !ruby/object:Gem::Dependency
+  name: gtk4
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.2'
+- !ruby/object:Gem::Dependency
+  name: gdk_pixbuf2
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.2'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.21'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.21'
+- !ruby/object:Gem::Dependency
+  name: lefthook
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+description: |
+  A GTK4 desktop viewer built on the rubycam library: live video preview,
+  sliders for gimbal/zoom/image controls, and a full OBSBOT Tiny control
+  panel — privacy sleep/wake, AI tracking modes, gimbal presets, tracking
+  speed, HDR, exposure modes and a raw-hex debug console.
+email:
+- nathankidd@hey.com
+executables:
+- rubycam-gtk
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- exe/rubycam-gtk
+- lib/rubycam/gtk.rb
+- lib/rubycam/gtk/camera_app.rb
+- lib/rubycam/gtk/obsbot_panel.rb
+- lib/rubycam/gtk/video4linux.rb
+- rubycam-gtk.gemspec
+homepage: https://github.com/ruby-gtk-project/rubycam
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/ruby-gtk-project/rubycam
+  changelog_uri: https://github.com/ruby-gtk-project/rubycam/releases
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.7.2
+specification_version: 4
+summary: GTK4 viewer for Rubycam webcams (OBSBOT Tiny live preview and controls)
+test_files: []