brad
f7e42f7132
Wraps linkctl so the Insta360 Link 2's AI tracking and gimbal presets are reachable from a keypress and from OBS, instead of a terminal. bin/linkctl-macro resolves the linkctl binary itself, because a desktop shortcut is launched with a far sparser PATH than an interactive shell and would otherwise just fail silently. It defaults to --force on the grounds that a deliberate keypress means "act now" even when nothing holds the camera open, which is precisely the state the Link parks itself in. Results go to a desktop notification, since tracking state and gimbal position are invisible otherwise, and linkctl's documented exit codes are mapped to actionable text. kde/install-shortcuts.sh registers Plasma global shortcuts via .desktop entries plus kglobalshortcutsrc. These work under Wayland, where OBS's own hotkeys only fire while OBS has focus. It writes with the shortcut daemon stopped, because the daemon rewrites that file on exit and would discard the entries. Supports --dry-run, --list and --uninstall. obs/obs-linkctl.lua adds OBS hotkeys, test buttons, and scene-to-action mapping, so switching scenes can set the camera state unattended. Its startup action defaults to loading the home preset, which undoes the gimbal's idle parking when OBS launches. Commands are backgrounded so the OBS UI thread never waits on the camera, and identical commands within 250ms are collapsed to absorb the repeated events studio mode emits. Tested: 22 offline Lua checks over shell quoting, action tokenizing, scene map parsing and command construction; the wrapper exercised against a stub linkctl for every documented exit code; the KDE installer dry-run, install, list and uninstall paths run against stubbed Plasma tools in a throwaway HOME. shellcheck clean. Not yet run against a live camera or a real Plasma session.
Insta360 Link 2 integration for OBS and KDE
Hotkey and OBS integration on top of linkctl,
so AI tracking and gimbal presets are a keypress rather than a terminal command.
Three pieces, usable independently:
| Path | What it gives you |
|---|---|
bin/linkctl-macro |
A wrapper that makes linkctl safe to bind to a hotkey: finds the binary in a desktop session's sparse PATH, passes --force, and reports the result as a desktop notification. |
kde/install-shortcuts.sh |
Registers KDE Plasma global shortcuts, so the keys work from anywhere including under Wayland. |
obs/obs-linkctl.lua |
OBS hotkeys, buttons, and scene automation: a scene switch can set tracking or load a preset on its own. |
Prerequisites
linkctl installed and working (linkctl status reports your camera), and a
saved home preset:
linkctl preset save home # point the camera where you want "home" first
Install
./kde/install-shortcuts.sh --dry-run # review, changes nothing
./kde/install-shortcuts.sh
Default bindings, editable in the BINDINGS table at the top of that script:
| Key | Action |
|---|---|
Meta+Alt+T |
toggle AI tracking |
Meta+Alt+1 |
tracking on |
Meta+Alt+0 |
tracking off |
Meta+Alt+H |
preset load home |
Meta+Alt+C |
recenter gimbal |
Check them afterwards with ./kde/install-shortcuts.sh --list, or in System
Settings under Keyboard, Shortcuts, searching for "Insta360". Reverse the whole
thing with --uninstall.
OBS
Tools, Scripts, +, then pick obs/obs-linkctl.lua.
Set the linkctl binary path if it is not on OBS's PATH, then bind the
hotkeys under Settings, Hotkeys (search "Insta360").
Scene automation. Press Insert current scene names to prefill the mapping box, then give the scenes you care about an action:
Talking Head = tracking on
Overhead = preset load overhead
Slides = tracking off
The left side is the scene name, the right side is any linkctl arguments.
Blank actions and # comments are ignored.
Startup action runs when OBS finishes loading, and defaults to
preset load home. This is the setting worth keeping: the Link parks its
gimbal facing down when idle, so launching OBS puts it back on its own.
Under Wayland, OBS's own hotkeys only fire while OBS has focus. That is an OBS limitation, and the reason the KDE shortcuts exist; install both and use the KDE ones for anything you need mid-stream.
Configuration
Optional, at ~/.config/linkctl-macro.conf (see linkctl-macro.conf.example):
LINKCTL=/usr/local/bin/linkctl # if not on PATH
LINKCTL_DEVICE=/dev/video0 # pin the camera if you have more than one
LINKCTL_FORCE=1 # 0 respects linkctl's idle-camera guard
LINKCTL_NOTIFY=always # always | error | never
--force is on by default because a deliberate keypress means "do it now",
including when nothing currently holds the camera open. That is exactly the
case where the gimbal is parked facing down.
Testing without a camera
lua tests/test_obs_linkctl.lua # pure helpers: quoting, parsing, commands
bin/linkctl-macro --print tracking on # show the command without running it
shellcheck bin/linkctl-macro kde/install-shortcuts.sh
Troubleshooting
Shortcut does nothing. Run the action directly first:
bin/linkctl-macro tracking on. A failure notification names the cause. If
that works but the key does not, re-run the installer with SHOW_IN_MENU=1;
some Plasma builds only resolve launcher-visible application entries.
tracking fails with exit 12. AI tracking is experimental in linkctl and
goes through the camera's vendor extension unit. Pan, tilt, zoom and presets use
standard UVC and are unaffected.
Permission denied (exit 6). Add yourself to the video group, or install
the udev rule from linkctl's contrib/99-insta360-link.rules.
Nothing moves at all. The Link 2 rejects single-axis pan/tilt writes and
needs both axes set in one VIDIOC_S_EXT_CTRLS call. linkctl does this
correctly; raw v4l2-ctl needs --set-ctrl pan_absolute=0,tilt_absolute=0
as one argument.
Status
The Lua helpers and the shell scripts are tested offline, and the KDE installer
is dry-runnable and reversible. None of it has been exercised against a live
camera or a running Plasma session by the author of this commit, so treat the
first run as the real test and use --dry-run first.