rubycam 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 56159c34d1f4c3fc3b773260aab3bca1428ea7e431a7a28481285d6059917293
+  data.tar.gz: eb0006ec99edf167df7220c21a0d88e0d6e97c9c9d09751cb9dd7fbf25861e7b
+SHA512:
+  metadata.gz: 58a93e7f44420ffcef22e953b078a19a97451748b8cadf8ab22fea9d75f09bb27f879c8b8284b56048911fc2ff43df93e9ad796d008c15c6bf7bf2d75e4f9eec
+  data.tar.gz: b206af6d57365dd79f82e3636d41728195ba1ceded40a4f5d7d06cb02e92607f5015fa26d1b5d463b716b284044beaf1264188c6192c0efac598090db1681c19

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/TINY4LINUX_FEATURES.md

@@ -0,0 +1,76 @@
+# Tiny4Linux feature checklist
+
+Feature inventory of [Tiny4Linux](https://github.com/OpenFoxes/Tiny4Linux)
+(Rust controller for the OBSBOT Tiny 2), tracked against Rubycam.
+Boxes are checked as features land in Rubycam.
+
+## Library (`tiny4linux` crate → `lib/rubycam/obsbot.rb`)
+
+- [x] Open camera by hint: exact path, `/dev/<name>`, or scan `/dev/video*`
+      matching card / bus info, skipping metadata-capture nodes
+- [x] Device info (card, bus)
+- [x] Sleep / wake commands (command02 packets, selector 0x02)
+- [x] Get status: sleep state (byte 0x02)
+- [x] Get status: AI/tracking mode (bytes 0x18 + 0x1c, 10 modes + unknown)
+- [x] Get status: HDR on/off (byte 0x06)
+- [x] Get status: tracking speed (byte 0x21: 0=standard, 2=sport)
+- [x] Set AI mode — 10 modes (selector 0x06, `16 02 m n`)
+- [x] Set tracking speed — standard / sport (command02, selector 0x02)
+- [x] Goto preset position 1–3 (command02 with float appendix, selector 0x02;
+      invalid preset raises)
+- [x] Set HDR mode on/off (selector 0x06, `01 01 xx`)
+- [x] Set exposure mode — manual / global / face (two-stage: command02
+      mode-type packet on 0x02, then `03 01 xx` on 0x06 for auto modes)
+- [x] command02 packet builder (frame id `aa 25`, sequence nr, segment size
+      `0c 00`, checksum, function group, command, 16-byte appendix)
+- [x] Send raw command bytes to unit 2, selector 0x02 or 0x06
+- [x] Hex dump of current 0x06 and 0x02 state
+- [x] Debug logging toggle (log sent commands / raw status)
+
+## GUI (`t4l-gui` → `app/camera_app.rb`)
+
+- [x] Sleep/wake control with state shown (icon + label follow camera state)
+- [x] Current-status panel: sleep mode, AI mode, tracking speed, HDR, version
+- [x] Preset position buttons 1–3 (tracking switched off before moving)
+- [x] Tracking mode selector — all 10 AI modes, active mode highlighted
+- [x] Tracking speed selector — standard / sport, active speed highlighted
+- [x] HDR toggle button
+- [x] Exposure mode buttons — manual / global / face
+- [x] Dashboard ⇄ Widget (compact) window modes with toggle button
+- [x] Periodic camera status poll; UI follows out-of-band changes
+- [x] Camera hotplug: "no camera" message and automatic reconnect
+- [x] Debug area: toggle debugging, send raw hex to 0x06 / 0x02,
+      hex-dump 0x06 / 0x02
+- [ ] i18n (7 locales) — skipped: English only, like the rest of Rubycam
+
+## CLI (`t4l` → `bin/rubycam`, dry-cli)
+
+- [x] OBSBOT commands: status, wake/sleep, track, speed, preset, hdr, exposure
+- [x] Raw extension-unit access: `xu dump`, `xu send` (with `--debug` logging)
+- [x] V4L2 commands (any UVC camera): devices, info, controls, get/set/reset
+- [x] Snapshot to JPEG with format negotiation
+
+## Rubycam extras (not in Tiny4Linux)
+
+- Live video preview (pure-Ruby V4L2 MJPG streaming)
+- Generic V4L2 control sliders (pan/tilt/zoom/brightness/…) + reset
+- Stream watchdog (rebuilds stalled stream after privacy sleep)
+
+## Out of scope
+
+- AUR packaging / desktop files / OBSBOT theme assets
+
+## Firmware notes (verified on real hardware, 2026-07)
+
+Tested against an actual OBSBOT Tiny 2 running newer firmware than the
+Tiny4Linux captures:
+
+- All set commands (sleep/wake, AI mode, speed, preset, HDR, exposure)
+  work byte-for-byte as Tiny4Linux sends them — AI tracking physically
+  confirmed.
+- The 0x06 status block is **eventually consistent**: mode changes can take
+  seconds to appear (the GUI highlights optimistically and re-syncs on poll).
+- Tracking speed is reported at byte 0x24, not 0x21 (which reads a constant
+  3 on this firmware); `Obsbot#status` checks both.
+- Concurrent readers (two processes polling the extension unit) scramble
+  status reads — avoid running two control apps at once.

data/exe/rubycam

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+#
+# Command-line control for Rubycam webcams.
+#
+#   rubycam                       # list commands
+#   rubycam status                # OBSBOT sleep/AI/HDR state
+#   rubycam wake                  # wake from privacy sleep
+#   rubycam track upper_body      # AI tracking mode
+#   rubycam set zoom_absolute 50  # any V4L2 control
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+require "rubycam/cli"
+
+Dry::CLI.new(Rubycam::CLI::Commands).call

data/lib/rubycam/cli.rb

@@ -0,0 +1,324 @@
+require 'dry/cli'
+require_relative '../rubycam'
+
+module Rubycam
+  # Command-line companion to the GTK viewer (bin/rubycam). Generic V4L2
+  # commands default to /dev/video0 like the GUI; OBSBOT vendor commands
+  # default to finding the camera by name.
+  module CLI
+    module Commands
+      extend Dry::CLI::Registry
+
+      # Base for commands that target one camera. Subclasses inherit the
+      # --device option (dry-cli copies params down the class hierarchy).
+      class VideoCommand < Dry::CLI::Command
+        option :device, type: :string, aliases: ['-d'], default: '/dev/video0',
+               desc: 'Device path, /dev name, or card/bus-name substring'
+
+        private
+
+        def with_device(options)
+          hint = options.fetch(:device)
+          device = Device.find(hint) or
+            abort "rubycam: no camera matches #{hint.inspect}"
+          begin
+            yield device
+          ensure
+            device.close
+          end
+        end
+
+        def fetch_control(device, name)
+          device.controls.fetch(name.to_sym) do
+            abort "rubycam: unknown control #{name} (see `controls`)"
+          end
+        end
+
+        def pick(value, allowed)
+          allowed.find { |a| a.to_s == value } or
+            abort "rubycam: expected one of: #{allowed.join(', ')}"
+        end
+      end
+
+      class ObsbotCommand < VideoCommand
+        option :device, type: :string, aliases: ['-d'], default: Obsbot::DEVICE_HINT,
+               desc: 'Device path, /dev name, or card/bus-name substring'
+        option :debug, type: :boolean, default: false,
+               desc: 'Log extension-unit traffic to stderr'
+
+        private
+
+        def with_obsbot(options)
+          with_device(options) do |device|
+            bot = Obsbot.new(device)
+            bot.debug = options[:debug]
+            yield bot
+          end
+        end
+      end
+
+      class Version < Dry::CLI::Command
+        desc 'Print version'
+        def call(**) = puts(VERSION)
+      end
+
+      class Devices < Dry::CLI::Command
+        desc 'List video capture devices'
+
+        def call(**)
+          Rubycam.devices.each do |dev|
+            meta = dev.device_caps & Device::CAP_META_CAPTURE != 0
+            puts format('%-14s %-28s %s%s', dev.path, dev.card, dev.bus_info,
+                        meta ? '  (metadata)' : '')
+            dev.close
+          end
+        end
+      end
+
+      class Info < VideoCommand
+        desc 'Show device identity (driver, card, bus)'
+
+        def call(**options)
+          with_device(options) do |dev|
+            { path: dev.path, driver: dev.driver, card: dev.card,
+              bus: dev.bus_info }.each { |k, v| puts format('%-8s %s', "#{k}:", v) }
+          end
+        end
+      end
+
+      class Controls < VideoCommand
+        desc 'List V4L2 controls with ranges and current values'
+
+        def call(**options)
+          with_device(options) do |dev|
+            dev.controls.each_value do |c|
+              notes = [(' [read-only]' if c.read_only?),
+                       (' [inactive]' if c.inactive?)].compact.join
+              puts "#{c}#{notes}"
+            end
+          end
+        end
+      end
+
+      class Get < VideoCommand
+        desc 'Read one V4L2 control'
+        argument :control, required: true, desc: 'Control key (see `controls`)'
+
+        def call(control:, **options)
+          with_device(options) { |dev| puts fetch_control(dev, control).value }
+        end
+      end
+
+      class Set < VideoCommand
+        desc 'Set one V4L2 control'
+        argument :control, required: true, desc: 'Control key (see `controls`)'
+        argument :value, required: true, desc: 'Integer value (clamped to range)'
+
+        def call(control:, value:, **options)
+          with_device(options) do |dev|
+            ctrl = fetch_control(dev, control)
+            ctrl.value = Integer(value)
+            puts "#{ctrl.key} = #{ctrl.value}"
+          end
+        rescue ArgumentError
+          abort "rubycam: value must be an integer, got #{value.inspect}"
+        end
+      end
+
+      class Reset < VideoCommand
+        desc 'Reset all writable controls to their defaults'
+
+        def call(**options)
+          with_device(options) do |dev|
+            dev.controls.each_value do |c|
+              next if c.read_only? || c.type == :button
+
+              begin
+                c.value = c.default
+              rescue SystemCallError
+                # inactive controls (e.g. manual exposure in auto mode) reject writes
+              end
+            end
+          end
+        end
+      end
+
+      class Snapshot < VideoCommand
+        desc 'Capture a single frame to a JPEG file'
+        argument :path, desc: 'Output file (default: snapshot.jpg)'
+        option :width, type: :integer, default: 1920
+        option :height, type: :integer, default: 1080
+
+        def call(path: 'snapshot.jpg', **options)
+          with_device(options) do |dev|
+            dev.set_format(width: options.fetch(:width).to_i,
+                           height: options.fetch(:height).to_i, pixel_format: 'MJPG')
+            File.binwrite(path, dev.capture_frame)
+            puts "#{dev.card}: wrote #{path} (#{dev.width}x#{dev.height} #{dev.pixel_format})"
+          end
+        end
+      end
+
+      # Nod (yes) and shake (no) gimbal gestures. The pan/tilt speed controls
+      # govern how fast absolute moves execute, so the gesture maxes them out
+      # for the duration — a slow drift doesn't read as a nod — and restores
+      # the saved speeds afterwards.
+      class GestureCommand < VideoCommand
+        SWING = 15 * 3600 # amplitude in V4L2 1/3600-degree units
+        BEAT = 0.5        # seconds per half-swing before reversing
+
+        private
+
+        def gesture(options, axis)
+          with_device(options) do |dev|
+            ctrl = fetch_control(dev, axis)
+            speeds = dev.controls.values_at(:pan_speed, :tilt_speed).compact
+            saved = speeds.map { |s| [s, s.value] }
+            begin
+              speeds.each { |s| s.value = s.max }
+              home = ctrl.value
+              2.times do
+                ctrl.value = home + SWING
+                sleep BEAT
+                ctrl.value = home - SWING
+                sleep BEAT
+              end
+              ctrl.value = home
+              sleep BEAT
+            ensure
+              saved.each { |s, v| s.value = v }
+            end
+          end
+        end
+      end
+
+      class Yes < GestureCommand
+        desc 'Nod the camera up and down, like nodding "yes"'
+        def call(**options) = gesture(options, :tilt_absolute)
+      end
+
+      class No < GestureCommand
+        desc 'Pan the camera side to side, like shaking your head "no"'
+        def call(**options) = gesture(options, :pan_absolute)
+      end
+
+      class Status < ObsbotCommand
+        desc 'Show OBSBOT status (sleep, AI mode, tracking speed, HDR)'
+
+        def call(**options)
+          with_obsbot(options) do |bot|
+            bot.status.each { |k, v| puts format('%-16s %s', "#{k}:", v) }
+          end
+        end
+      end
+
+      class Wake < ObsbotCommand
+        desc 'Wake the camera from privacy sleep'
+        def call(**options) = with_obsbot(options, &:wake!)
+      end
+
+      class Sleep < ObsbotCommand
+        desc 'Put the camera into privacy sleep'
+        def call(**options) = with_obsbot(options, &:sleep!)
+      end
+
+      class Track < ObsbotCommand
+        desc "Set AI tracking mode (#{Obsbot::AI_MODES.keys.join(', ')})"
+        argument :mode, required: true, desc: 'Tracking mode'
+
+        def call(mode:, **options)
+          with_obsbot(options) { |bot| bot.ai_mode = pick(mode, Obsbot::AI_MODES.keys) }
+        end
+      end
+
+      class Speed < ObsbotCommand
+        desc 'Set tracking speed (standard, sport)'
+        argument :speed, required: true, desc: 'Tracking speed'
+
+        def call(speed:, **options)
+          with_obsbot(options) do |bot|
+            bot.tracking_speed = pick(speed, Obsbot::TRACKING_SPEEDS)
+          end
+        end
+      end
+
+      class Hdr < ObsbotCommand
+        desc 'Switch HDR on or off'
+        argument :state, required: true, desc: 'on or off'
+
+        def call(state:, **options)
+          with_obsbot(options) { |bot| bot.hdr = pick(state, %i[on off]) == :on }
+        end
+      end
+
+      class Exposure < ObsbotCommand
+        desc 'Set exposure mode (manual, global, face)'
+        argument :mode, required: true, desc: 'Exposure mode'
+
+        def call(mode:, **options)
+          with_obsbot(options) do |bot|
+            bot.exposure_mode = pick(mode, Obsbot::EXPOSURE_MODES.keys)
+          end
+        end
+      end
+
+      class Preset < ObsbotCommand
+        desc 'Move gimbal to a preset position (tracking is switched off first)'
+        argument :number, required: true, desc: 'Preset number (1-3)'
+
+        def call(number:, **options)
+          n = Integer(number, exception: false)
+          abort 'rubycam: preset must be 1-3' unless n && (1..3).cover?(n)
+          with_obsbot(options) do |bot|
+            bot.ai_mode = :no_tracking
+            bot.goto_preset(n - 1)
+          end
+        end
+      end
+
+      class XuDump < ObsbotCommand
+        desc 'Hex-dump the 60-byte state of an extension-unit selector'
+        argument :selector, desc: 'Selector, e.g. 0x06 (default) or 0x02'
+
+        def call(selector: '0x06', **options)
+          with_obsbot(options) { |bot| puts bot.dump(Integer(selector)) }
+        end
+      end
+
+      class XuSend < ObsbotCommand
+        desc 'Send raw hex bytes to an extension-unit selector'
+        argument :hex, required: true, desc: "Hex bytes, e.g. '16 02 02 00'"
+        option :selector, default: '0x06', desc: 'Selector to send to'
+
+        def call(hex:, **options)
+          with_obsbot(options) do |bot|
+            bot.send_hex(hex, selector: Integer(options.fetch(:selector)))
+          end
+        end
+      end
+
+      register 'version', Version, aliases: ['-v', '--version']
+      register 'devices', Devices
+      register 'info', Info
+      register 'controls', Controls
+      register 'get', Get
+      register 'set', Set
+      register 'reset', Reset
+      register 'snapshot', Snapshot
+      register 'yes', Yes
+      register 'no', No
+      register 'status', Status
+      register 'wake', Wake
+      register 'sleep', Sleep
+      register 'track', Track
+      register 'speed', Speed
+      register 'hdr', Hdr
+      register 'exposure', Exposure
+      register 'preset', Preset
+      register 'xu' do |xu|
+        xu.register 'dump', XuDump
+        xu.register 'send', XuSend
+      end
+    end
+  end
+end

data/lib/rubycam/controls.rb

@@ -0,0 +1,45 @@
+module Rubycam
+  # A single camera control (brightness, zoom_absolute, ...) discovered via
+  # VIDIOC_QUERYCTRL. Reading and writing goes through the owning device.
+  class Control
+    TYPES = { 1 => :integer, 2 => :boolean, 3 => :menu, 4 => :button,
+              5 => :integer64, 6 => :ctrl_class, 7 => :string, 8 => :bitmask,
+              9 => :integer_menu }.freeze
+
+    FLAG_DISABLED  = 0x0001
+    FLAG_GRABBED   = 0x0002
+    FLAG_READ_ONLY = 0x0004
+    FLAG_INACTIVE  = 0x0010
+
+    attr_reader :id, :type, :name, :min, :max, :step, :default, :flags
+
+    def initialize(device, id:, type:, name:, min:, max:, step:, default:, flags:)
+      @device = device
+      @id = id
+      @type = TYPES.fetch(type, type)
+      @name = name
+      @min = min
+      @max = max
+      @step = step
+      @default = default
+      @flags = flags
+    end
+
+    # Symbol key derived from the control name, e.g. "Zoom, Absolute" => :zoom_absolute
+    def key = @key ||= name.downcase.gsub(/[^a-z0-9]+/, '_').gsub(/^_|_$/, '').to_sym
+
+    def value = @device.get_control(id)
+
+    def value=(v)
+      clamped = v.clamp(min, max)
+      @device.set_control(id, clamped)
+    end
+
+    def inactive? = flags & FLAG_INACTIVE != 0
+    def read_only? = flags & FLAG_READ_ONLY != 0
+
+    def to_s
+      "#{key} (#{type}) min=#{min} max=#{max} step=#{step} default=#{default} value=#{value}"
+    end
+  end
+end

data/lib/rubycam/device.rb

@@ -0,0 +1,267 @@
+require 'fiddle'
+
+module Rubycam
+  # A V4L2 capture device. Controls are read/written with ioctl; frames are
+  # streamed with memory-mapped kernel buffers (uvcvideo does not support
+  # plain read()).
+  class Device
+    BUF_TYPE_VIDEO_CAPTURE = 1
+    MEMORY_MMAP = 1
+    CTRL_FLAG_NEXT_CTRL = 0x80000000
+
+    PROT_READ = 1
+    MAP_SHARED = 1
+
+    LIBC = Fiddle.dlopen(nil)
+    MMAP = Fiddle::Function.new(
+      LIBC['mmap'],
+      [Fiddle::TYPE_VOIDP, Fiddle::TYPE_SIZE_T, Fiddle::TYPE_INT,
+       Fiddle::TYPE_INT, Fiddle::TYPE_INT, Fiddle::TYPE_LONG],
+      Fiddle::TYPE_VOIDP
+    )
+    MUNMAP = Fiddle::Function.new(
+      LIBC['munmap'], [Fiddle::TYPE_VOIDP, Fiddle::TYPE_SIZE_T], Fiddle::TYPE_INT
+    )
+
+    CAP_META_CAPTURE = 0x00800000
+
+    attr_reader :path, :driver, :card, :bus_info, :device_caps,
+                :width, :height, :pixel_format
+
+    # Find a camera by device path, /dev name, or a substring of its card
+    # name or bus info — e.g. Device.find('OBSBOT Tiny 2'). Metadata-only
+    # nodes (uvcvideo exposes one per camera) are skipped. Returns nil when
+    # nothing matches.
+    def self.find(hint)
+      [hint, "/dev/#{hint}"].each do |path|
+        return open(path) if File.exist?(path)
+      end
+
+      Dir['/dev/video*'].sort.each do |path|
+        device = begin
+          open(path)
+        rescue SystemCallError
+          next
+        end
+        if (device.card.include?(hint) || device.bus_info.include?(hint)) &&
+           device.device_caps & CAP_META_CAPTURE == 0
+          return device
+        end
+        device.close
+      end
+      nil
+    end
+
+    def self.open(path = '/dev/video0')
+      device = new(path)
+      if block_given?
+        begin
+          yield device
+        ensure
+          device.close
+        end
+      else
+        device
+      end
+    end
+
+    def initialize(path)
+      @path = path
+      @io = File.open(path, 'r+')
+      @buffers = []
+      @streaming = false
+      query_capabilities
+    end
+
+    def close
+      stop_streaming
+      @io.close unless @io.closed?
+    end
+
+    # ---- Controls ----------------------------------------------------------
+
+    # All controls the driver exposes, keyed by symbol (e.g. :zoom_absolute).
+    def controls
+      @controls ||= enumerate_controls.to_h { |c| [c.key, c] }
+    end
+
+    def [](key) = controls.fetch(key).value
+
+    def []=(key, value)
+      controls.fetch(key).value = value
+    end
+
+    def get_control(id)
+      buf = [id, 0].pack('Ll')
+      @io.ioctl(Ioctl::VIDIOC_G_CTRL, buf)
+      buf.unpack('Ll')[1]
+    end
+
+    def set_control(id, value)
+      @io.ioctl(Ioctl::VIDIOC_S_CTRL, [id, value].pack('Ll'))
+      value
+    end
+
+    # ---- Format / frame rate -----------------------------------------------
+
+    def fourcc(str) = str.unpack1('V')
+    def fourcc_to_s(num) = [num].pack('V')
+
+    # Negotiate resolution and pixel format ('MJPG' or 'YUYV'). The driver may
+    # adjust the values; the actual result lands in width/height/pixel_format.
+    def set_format(width:, height:, pixel_format: 'MJPG')
+      buf = [BUF_TYPE_VIDEO_CAPTURE].pack('L') + "\0" * (Ioctl::FORMAT_SIZE - 4)
+      @io.ioctl(Ioctl::VIDIOC_G_FMT, buf)
+      buf[8, 12] = [width, height, fourcc(pixel_format)].pack('L3')
+      @io.ioctl(Ioctl::VIDIOC_S_FMT, buf)
+      @width, @height, pix = buf[8, 12].unpack('L3')
+      @pixel_format = fourcc_to_s(pix)
+      @frame_size = buf[28, 4].unpack1('L')
+      [@width, @height, @pixel_format]
+    end
+
+    def set_fps(fps)
+      buf = [BUF_TYPE_VIDEO_CAPTURE].pack('L') + "\0" * (Ioctl::STREAMPARM_SIZE - 4)
+      @io.ioctl(Ioctl::VIDIOC_G_PARM, buf)
+      buf[12, 8] = [1, fps].pack('L2')
+      @io.ioctl(Ioctl::VIDIOC_S_PARM, buf)
+      num, denom = buf[12, 8].unpack('L2')
+      denom / num.to_f
+    end
+
+    # ---- Streaming -----------------------------------------------------------
+
+    def start_streaming(buffer_count: 4)
+      set_format(width: 1920, height: 1080) unless @width
+      request_buffers(buffer_count)
+      map_buffers
+      @buffers.each_index { |i| queue_buffer(i) }
+      @io.ioctl(Ioctl::VIDIOC_STREAMON, [BUF_TYPE_VIDEO_CAPTURE].pack('L'))
+      @streaming = true
+    end
+
+    def stop_streaming
+      return unless @streaming
+
+      @io.ioctl(Ioctl::VIDIOC_STREAMOFF, [BUF_TYPE_VIDEO_CAPTURE].pack('L'))
+      @buffers.each { |b| MUNMAP.call(b[:ptr], b[:length]) }
+      @buffers.clear
+      request_buffers(0)
+      @streaming = false
+    end
+
+    def streaming? = @streaming
+
+    # Tear down and rebuild the buffer queue. Useful when a stream goes
+    # quiet after an external event (e.g. a camera's privacy sleep).
+    def restart_streaming
+      stop_streaming
+      start_streaming
+    end
+
+    # Block until the next frame is ready and return its bytes as a String.
+    # The default timeout is generous because the camera's ISP takes a few
+    # seconds to deliver the first frame after STREAMON.
+    def capture_frame(timeout: 10.0)
+      start_streaming unless @streaming
+      IO.select([@io], nil, nil, timeout) or raise "timed out waiting for frame from #{path}"
+      buf = dequeue_buffer
+      frame = @buffers[buf[:index]][:ptr][0, buf[:bytesused]]
+      queue_buffer(buf[:index])
+      frame
+    end
+
+    # Non-blocking: return the next frame if one is ready, else nil.
+    # Suited to GUI main loops that tick faster than the camera delivers.
+    def poll_frame
+      start_streaming unless @streaming
+      IO.select([@io], nil, nil, 0) or return nil
+      buf = dequeue_buffer
+      frame = @buffers[buf[:index]][:ptr][0, buf[:bytesused]]
+      queue_buffer(buf[:index])
+      frame
+    end
+
+    def each_frame
+      start_streaming unless @streaming
+      loop { yield capture_frame }
+    end
+
+    def to_io = @io
+
+    private
+
+    def query_capabilities
+      buf = "\0" * Ioctl::CAPABILITY_SIZE
+      @io.ioctl(Ioctl::VIDIOC_QUERYCAP, buf)
+      @driver = buf[0, 16].unpack1('Z16')
+      @card = buf[16, 32].unpack1('Z32')
+      @bus_info = buf[48, 32].unpack1('Z32')
+      @device_caps = buf[88, 4].unpack1('L')
+    end
+
+    def enumerate_controls
+      found = []
+      id = CTRL_FLAG_NEXT_CTRL
+      loop do
+        buf = [id].pack('L') + "\0" * (Ioctl::QUERYCTRL_SIZE - 4)
+        begin
+          @io.ioctl(Ioctl::VIDIOC_QUERYCTRL, buf)
+        rescue Errno::EINVAL
+          break
+        end
+        ctrl_id, type = buf.unpack('L2')
+        name = buf[8, 32].unpack1('Z32')
+        min, max, step, default = buf[40, 16].unpack('l4')
+        flags = buf[56, 4].unpack1('L')
+        ctrl = Control.new(self, id: ctrl_id, type:, name:, min:, max:,
+                                 step:, default:, flags:)
+        found << ctrl unless ctrl.type == :ctrl_class || flags & Control::FLAG_DISABLED != 0
+        id = ctrl_id | CTRL_FLAG_NEXT_CTRL
+      end
+      found
+    end
+
+    def request_buffers(count)
+      buf = [count, BUF_TYPE_VIDEO_CAPTURE, MEMORY_MMAP].pack('L3') +
+            "\0" * (Ioctl::REQUESTBUFFERS_SIZE - 12)
+      @io.ioctl(Ioctl::VIDIOC_REQBUFS, buf)
+      buf.unpack1('L')
+    end
+
+    def buffer_struct(index)
+      [index, BUF_TYPE_VIDEO_CAPTURE].pack('L2') +
+        "\0" * 52 + [MEMORY_MMAP].pack('L') + "\0" * (Ioctl::BUFFER_SIZE - 64)
+    end
+
+    def parse_buffer(buf)
+      index, _type, bytesused = buf.unpack('L3')
+      offset = buf[64, 4].unpack1('L')
+      length = buf[72, 4].unpack1('L')
+      { index:, bytesused:, offset:, length: }
+    end
+
+    def map_buffers
+      count = request_buffers(4)
+      @buffers = count.times.map do |i|
+        struct = buffer_struct(i)
+        @io.ioctl(Ioctl::VIDIOC_QUERYBUF, struct)
+        info = parse_buffer(struct)
+        ptr = MMAP.call(nil, info[:length], PROT_READ, MAP_SHARED, @io.fileno, info[:offset])
+        raise "mmap failed for buffer #{i}" if ptr.to_i == -1 || ptr.to_i == 2**64 - 1
+
+        { ptr: Fiddle::Pointer.new(ptr.to_i), length: info[:length] }
+      end
+    end
+
+    def queue_buffer(index)
+      @io.ioctl(Ioctl::VIDIOC_QBUF, buffer_struct(index))
+    end
+
+    def dequeue_buffer
+      struct = buffer_struct(0)
+      @io.ioctl(Ioctl::VIDIOC_DQBUF, struct)
+      parse_buffer(struct)
+    end
+  end
+end

data/lib/rubycam/ioctl.rb

@@ -0,0 +1,60 @@
+# V4L2 ioctl plumbing: request-code computation and struct layouts.
+#
+# ioctl request codes follow the kernel's _IOC macro:
+#   dir(2 bits) | size(14 bits) | type(8 bits) | nr(8 bits)
+# Struct sizes below must match the C layouts in <linux/videodev2.h>
+# on 64-bit; each SIZE constant is asserted against its pack template.
+module Rubycam
+  module Ioctl
+    NONE  = 0
+    WRITE = 1
+    READ  = 2
+
+    def self.ioc(dir, type, nr, size) = (dir << 30) | (size << 16) | (type.ord << 8) | nr
+    def self.iowr(type, nr, size) = ioc(WRITE | READ, type, nr, size)
+    def self.ior(type, nr, size)  = ioc(READ, type, nr, size)
+    def self.iow(type, nr, size)  = ioc(WRITE, type, nr, size)
+
+    # struct v4l2_capability { u8 driver[16]; u8 card[32]; u8 bus_info[32];
+    #   u32 version; u32 capabilities; u32 device_caps; u32 reserved[3]; }
+    CAPABILITY_SIZE = 104
+
+    # struct v4l2_queryctrl { u32 id; u32 type; u8 name[32]; s32 min; s32 max;
+    #   s32 step; s32 default; u32 flags; u32 reserved[2]; }
+    QUERYCTRL_SIZE = 68
+
+    # struct v4l2_control { u32 id; s32 value; }
+    CONTROL_SIZE = 8
+
+    # struct v4l2_format { u32 type; u8 pad[4]; union fmt[200]; } (8-aligned union)
+    FORMAT_SIZE = 208
+
+    # struct v4l2_requestbuffers { u32 count; u32 type; u32 memory;
+    #   u32 capabilities; u8 flags; u8 reserved[3]; }
+    REQUESTBUFFERS_SIZE = 20
+
+    # struct v4l2_buffer (64-bit): u32 index,type,bytesused,flags,field; pad4;
+    #   timeval(16); v4l2_timecode(16); u32 sequence,memory; union m(8);
+    #   u32 length,reserved2,request_fd; pad4;
+    BUFFER_SIZE = 88
+
+    # struct v4l2_streamparm { u32 type; union parm[200]; }
+    STREAMPARM_SIZE = 204
+
+    V = 'V'
+    VIDIOC_QUERYCAP  = ior(V, 0, CAPABILITY_SIZE)
+    VIDIOC_G_FMT     = iowr(V, 4, FORMAT_SIZE)
+    VIDIOC_S_FMT     = iowr(V, 5, FORMAT_SIZE)
+    VIDIOC_REQBUFS   = iowr(V, 8, REQUESTBUFFERS_SIZE)
+    VIDIOC_QUERYBUF  = iowr(V, 9, BUFFER_SIZE)
+    VIDIOC_QBUF      = iowr(V, 15, BUFFER_SIZE)
+    VIDIOC_DQBUF     = iowr(V, 17, BUFFER_SIZE)
+    VIDIOC_STREAMON  = iow(V, 18, 4)
+    VIDIOC_STREAMOFF = iow(V, 19, 4)
+    VIDIOC_G_PARM    = iowr(V, 21, STREAMPARM_SIZE)
+    VIDIOC_S_PARM    = iowr(V, 22, STREAMPARM_SIZE)
+    VIDIOC_G_CTRL    = iowr(V, 27, CONTROL_SIZE)
+    VIDIOC_S_CTRL    = iowr(V, 28, CONTROL_SIZE)
+    VIDIOC_QUERYCTRL = iowr(V, 36, QUERYCTRL_SIZE)
+  end
+end

data/lib/rubycam/obsbot.rb

@@ -0,0 +1,176 @@
+module Rubycam
+  # OBSBOT vendor commands, spoken over the camera's UVC Extension Unit
+  # (unit 2, GUID 9a1e7291-6843-4683-6d92-39bc7906ee49) via the uvcvideo
+  # driver's UVCIOC_CTRL_QUERY ioctl. Protocol reverse-engineered by the
+  # Tiny4Linux project (https://github.com/OpenFoxes/Tiny4Linux).
+  class Obsbot
+    UNIT = 0x02
+    SELECTOR_COMMAND = 0x02
+    SELECTOR_STATUS = 0x06
+    PAYLOAD_SIZE = 60
+
+    UVC_SET_CUR = 0x01
+    UVC_GET_CUR = 0x81
+
+    # struct uvc_xu_control_query { u8 unit; u8 selector; u8 query;
+    #   u16 size; u8 *data; } — 16 bytes with padding on 64-bit.
+    UVCIOC_CTRL_QUERY = Ioctl.iowr('u', 0x21, 16)
+
+    DEVICE_HINT = 'OBSBOT Tiny 2'.freeze
+
+    # Command packets sent to selector 0x02:
+    #   aa 25 | seq(2) | 0c 00 | checksum(2) | group(6) | cmd(6) | appendix(16)
+    # Sequence numbers and checksums are replayed verbatim from captures of
+    # the official software; the camera accepts them as-is.
+    def self.command02(seq:, checksum:, group:, cmd:, appendix: [0] * 16)
+      ([0xaa, 0x25] + seq + [0x0c, 0x00] + checksum + group + cmd + appendix)
+        .pack('C*')
+    end
+
+    GROUP_SLEEP = [0x0a, 0x02, 0xc2, 0xa0, 0x04, 0x00].freeze
+    WAKE_PACKET = command02(seq: [0xa5, 0x00], checksum: [0x5f, 0xef],
+                            group: GROUP_SLEEP,
+                            cmd: [0xbe, 0x07, 0x00, 0x00, 0x00, 0x00])
+    SLEEP_PACKET = command02(seq: [0x42, 0x00], checksum: [0xea, 0x63],
+                             group: GROUP_SLEEP,
+                             cmd: [0xbf, 0xfb, 0x01, 0x00, 0x00, 0x00])
+
+    GROUP_TRACKING_SPEED = [0x0a, 0x04, 0xc4, 0x0c, 0x01, 0x00].freeze
+    TRACKING_SPEED_PACKETS = {
+      standard: command02(seq: [0x20, 0x00], checksum: [0xab, 0xcb],
+                          group: GROUP_TRACKING_SPEED,
+                          cmd: [0xe6, 0x3f, 0x00, 0x00, 0x00, 0x00]),
+      sport: command02(seq: [0x21, 0x00], checksum: [0xfa, 0x0e],
+                       group: GROUP_TRACKING_SPEED,
+                       cmd: [0x67, 0xfe, 0x02, 0x00, 0x00, 0x00])
+    }.freeze
+
+    GROUP_PRESETS = [0x0a, 0x04, 0xc4, 0x39, 0x14, 0x00].freeze
+    PRESET_APPENDIX = ([0x00, 0x00, 0x80, 0x3f] * 4).freeze # 1.0f × 4
+    PRESET_PACKETS = [
+      command02(seq: [0x20, 0x00], checksum: [0x6b, 0xdc], group: GROUP_PRESETS,
+                cmd: [0xd6, 0xfb, 0x00, 0x00, 0x00, 0x00], appendix: PRESET_APPENDIX),
+      command02(seq: [0x1a, 0x00], checksum: [0x4b, 0x03], group: GROUP_PRESETS,
+                cmd: [0xeb, 0x2a, 0x01, 0x00, 0x00, 0x00], appendix: PRESET_APPENDIX),
+      command02(seq: [0x26, 0x00], checksum: [0x8b, 0xc3], group: GROUP_PRESETS,
+                cmd: [0xaf, 0x19, 0x02, 0x00, 0x00, 0x00], appendix: PRESET_APPENDIX)
+    ].freeze
+
+    # Switching exposure mode is two-stage: a mode-type packet on 0x02
+    # (manual vs. automatic), then for the automatic flavours a follow-up
+    # on 0x06 choosing global or face metering.
+    GROUP_EXPOSURE_TYPE = [0x0a, 0x02, 0x82, 0x29, 0x05, 0x00].freeze
+    EXPOSURE_TYPE_PACKETS = {
+      manual: command02(seq: [0x16, 0x00], checksum: [0x58, 0x91],
+                        group: GROUP_EXPOSURE_TYPE,
+                        cmd: [0xb2, 0xaf, 0x02, 0x04, 0x00, 0x00]),
+      auto: command02(seq: [0x15, 0x00], checksum: [0xa8, 0x9e],
+                      group: GROUP_EXPOSURE_TYPE,
+                      cmd: [0xf9, 0x27, 0x01, 0x32, 0x00, 0x00])
+    }.freeze
+    EXPOSURE_MODES = { manual: nil, global: [0x03, 0x01, 0x00],
+                       face: [0x03, 0x01, 0x01] }.freeze
+
+    # AI tracking modes, keyed by symbol; values are the two mode bytes as
+    # sent in the set command and reported at 0x18/0x1c of the status block.
+    AI_MODES = { no_tracking: [0, 0], normal_tracking: [2, 0],
+                 upper_body: [2, 1], close_up: [2, 2], headless: [2, 3],
+                 lower_body: [2, 4], desk_mode: [5, 0], whiteboard: [4, 0],
+                 hand: [6, 0], group: [1, 0] }.freeze
+    AI_MODE_BY_BYTES = AI_MODES.invert.freeze
+
+    TRACKING_SPEEDS = %i[standard sport].freeze
+
+    # If set, sent commands and raw status reads are logged to stderr.
+    attr_accessor :debug
+
+    def initialize(device)
+      @device = device
+      @debug = false
+    end
+
+    def wake! = send_command(WAKE_PACKET)
+    def sleep! = send_command(SLEEP_PACKET)
+
+    def ai_mode=(mode)
+      m, n = AI_MODES.fetch(mode)
+      send_status_command([0x16, 0x02, m, n].pack('C*'))
+    end
+
+    def tracking_speed=(speed)
+      send_command(TRACKING_SPEED_PACKETS.fetch(speed))
+    end
+
+    # Move the gimbal to a stored preset position (0..2). The camera ignores
+    # this while tracking, so callers normally switch to :no_tracking first.
+    def goto_preset(number)
+      send_command(PRESET_PACKETS.fetch(number))
+    end
+
+    def hdr=(on)
+      send_status_command([0x01, 0x01, on ? 1 : 0].pack('C*'))
+    end
+
+    def exposure_mode=(mode)
+      metering = EXPOSURE_MODES.fetch(mode)
+      send_command(EXPOSURE_TYPE_PACKETS.fetch(metering ? :auto : :manual))
+      send_status_command(metering.pack('C*')) if metering
+    end
+
+    # NOTE: on newer Tiny 2 firmware the status block can lag behind mode
+    # changes by several seconds; treat it as eventually consistent.
+    def status
+      raw_status.then do |bytes|
+        { asleep: bytes[0x02] == 1,
+          hdr: bytes[0x06] != 0,
+          ai_mode: AI_MODE_BY_BYTES.fetch([bytes[0x18], bytes[0x1c]], :unknown),
+          tracking_speed: decode_speed(bytes) }
+      end
+    end
+
+    def asleep? = status[:asleep]
+
+    # ---- Debug console -------------------------------------------------------
+    # Raw access to the extension unit, mirroring Tiny4Linux's debug area.
+
+    def send_hex(hex, selector: SELECTOR_STATUS)
+      send_to(selector, [hex.gsub(/\s/, '')].pack('H*'))
+    end
+
+    # Current 60-byte state of a selector as a hex string.
+    def dump(selector = SELECTOR_STATUS)
+      xu_query(UVC_GET_CUR, selector).unpack1('H*')
+    end
+
+    private
+
+    # Tiny4Linux reads speed at 0x21 (0=standard, 2=sport), but newer Tiny 2
+    # firmware keeps a constant 3 there and reports the speed at 0x24.
+    def decode_speed(bytes)
+      [bytes[0x21], bytes[0x24]].find { |b| [0, 2].include?(b) } == 2 ? :sport : :standard
+    end
+
+    def send_command(packet) = send_to(SELECTOR_COMMAND, packet)
+    def send_status_command(packet) = send_to(SELECTOR_STATUS, packet)
+
+    def send_to(selector, packet)
+      warn format('obsbot -> 0x%02x: %s', selector, packet.unpack1('H*')) if debug
+      xu_query(UVC_SET_CUR, selector, packet)
+      true
+    end
+
+    def raw_status
+      xu_query(UVC_GET_CUR, SELECTOR_STATUS).tap do |raw|
+        warn "obsbot <- status: #{raw.unpack1('H*')}" if debug
+      end.bytes
+    end
+
+    def xu_query(query, selector, payload = '')
+      buffer = Fiddle::Pointer.malloc(PAYLOAD_SIZE, Fiddle::RUBY_FREE)
+      buffer[0, payload.bytesize] = payload unless payload.empty?
+      request = [UNIT, selector, query, PAYLOAD_SIZE, buffer.to_i].pack('C3xvx2Q')
+      @device.to_io.ioctl(UVCIOC_CTRL_QUERY, request)
+      buffer[0, PAYLOAD_SIZE]
+    end
+  end
+end

data/lib/rubycam/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Rubycam
+  VERSION = "0.1.1"
+end

data/lib/rubycam.rb

@@ -0,0 +1,23 @@
+# Rubycam: pure-Ruby V4L2 webcam library (controls + MJPG/YUYV capture).
+#
+#   Rubycam::Device.open('/dev/video0') do |cam|
+#     cam[:zoom_absolute] = 50
+#     cam.set_format(width: 1920, height: 1080, pixel_format: 'MJPG')
+#     File.binwrite('frame.jpg', cam.capture_frame)
+#   end
+require_relative 'rubycam/version'
+require_relative 'rubycam/ioctl'
+require_relative 'rubycam/controls'
+require_relative 'rubycam/device'
+require_relative 'rubycam/obsbot'
+
+module Rubycam
+  # All /dev/video* nodes that are actual capture devices.
+  def self.devices
+    Dir['/dev/video*'].sort.filter_map do |path|
+      Device.open(path)
+    rescue SystemCallError
+      nil
+    end
+  end
+end

data/rubycam.gemspec

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require_relative "lib/rubycam/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "rubycam"
+  spec.version = Rubycam::VERSION
+  spec.authors = ["Nathan Kidd"]
+  spec.email = ["nathankidd@hey.com"]
+
+  spec.summary = "Pure-Ruby V4L2 webcam library and CLI, with OBSBOT Tiny support"
+
+  spec.description = <<~DESC
+    Rubycam is a pure-Ruby V4L2 library for controlling webcams and capturing
+    MJPG/YUYV frames, plus a dry-cli command-line tool. It includes a vendor
+    extension driver for OBSBOT Tiny cameras: privacy sleep/wake, AI tracking
+    modes, gimbal presets, tracking speed, HDR and exposure control. The GTK4
+    desktop viewer ships separately as the rubycam-gtk gem.
+  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 gem is the library + CLI. The GTK viewer (lib/rubycam/gtk)
+  # is the separate rubycam-gtk gem; dev-only files are left out.
+  spec.files = `git ls-files -z`.split("\x0").select do |f|
+    (f.start_with?("lib/rubycam") && !f.start_with?("lib/rubycam/gtk") && !f.end_with?(".erb")) ||
+      f == "exe/rubycam" ||
+      f == "rubycam.gemspec" ||
+      %w[README.md LICENSE TINY4LINUX_FEATURES.md].include?(f)
+  end
+  spec.bindir = "exe"
+  spec.executables = ["rubycam"]
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "dry-cli", "~> 1.0"
+
+  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,131 @@
+--- !ruby/object:Gem::Specification
+name: rubycam
+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: dry-cli
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !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: |
+  Rubycam is a pure-Ruby V4L2 library for controlling webcams and capturing
+  MJPG/YUYV frames, plus a dry-cli command-line tool. It includes a vendor
+  extension driver for OBSBOT Tiny cameras: privacy sleep/wake, AI tracking
+  modes, gimbal presets, tracking speed, HDR and exposure control. The GTK4
+  desktop viewer ships separately as the rubycam-gtk gem.
+email:
+- nathankidd@hey.com
+executables:
+- rubycam
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- TINY4LINUX_FEATURES.md
+- exe/rubycam
+- lib/rubycam.rb
+- lib/rubycam/cli.rb
+- lib/rubycam/controls.rb
+- lib/rubycam/device.rb
+- lib/rubycam/ioctl.rb
+- lib/rubycam/obsbot.rb
+- lib/rubycam/version.rb
+- rubycam.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: Pure-Ruby V4L2 webcam library and CLI, with OBSBOT Tiny support
+test_files: []