Metadata-Version: 2.4
Name: link-studio
Version: 1.0.4
Summary: Native Linux controller for Insta360 Link webcams
Author: Link Studio contributors
License-Expression: MIT
Project-URL: Homepage, https://jweaver60.github.io/link-studio/
Project-URL: Documentation, https://jweaver60.github.io/link-studio/docs/
Project-URL: Repository, https://github.com/jweaver60/link-studio
Project-URL: Issues, https://github.com/jweaver60/link-studio/issues
Keywords: insta360,webcam,uvc,v4l2,gtk,arch-linux
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: X11 Applications :: GTK
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Multimedia :: Video
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: THIRD_PARTY_NOTICES.md
Requires-Dist: mediapipe>=1.0.1
Requires-Dist: numpy>=2.0
Requires-Dist: opencv-contrib-python>=4.10
Requires-Dist: qrcode[pil]>=8.0
Provides-Extra: dev
Requires-Dist: build>=1.3; extra == "dev"
Requires-Dist: installer>=0.7; extra == "dev"
Requires-Dist: ruff>=0.12; extra == "dev"
Dynamic: license-file

# Link Studio

Link Studio is an unofficial, open-source Linux control application for Insta360 Link webcams. It
is hardware-tested with the **Insta360 Link 2** (`2e1a:4c04`) on Arch Linux and combines direct,
cooperative V4L2/UVC control with a GTK4/libadwaita interface. Video, audio, AI inference, remote
control, and configuration remain local unless you explicitly open an Insta360 download link.

Version 1.0 completes the safe Linux application scope. It implements every official-client area
that can be reproduced through validated Link 2 controls or a local Linux equivalent. The few
vendor-only operations that cannot safely be cloned are identified in the
[parity contract](docs/PARITY.md); they are external protocol or service boundaries, not unfinished
buttons hidden in the application.

Project documentation lives at <https://jweaver60.github.io/link-studio/>. The canonical public
source repository is [`jweaver60/link-studio`](https://github.com/jweaver60/link-studio).

## Features

- Live 720p, 1080p, 1440p, and 4K preview at every frame rate currently advertised by the camera
- PNG screenshots and H.264/AAC MP4 recording, with selectable destinations and microphone
- Pan, tilt, center, 1–4× zoom, autofocus/manual focus, mirror, privacy, and output rotation
- Hardware AI Tracking, Whiteboard, Overhead, and DeskView modes
- Hardware framing, tracking speed, gesture zoom, HDR, exposure, white balance, anti-flicker, and
  complete color controls
- Local single-person and group tracking with a tracking boundary and up to six pause areas
- Local background blur, bokeh, background replacement, green screen, beautify, makeup, and Smart
  Whiteboard, powered by bundled MediaPipe models
- Link 2 Voice Focus, Voice Suppression, and Music Balance microphone modes; PipeWire mute and volume
- Processed virtual-camera output through an optional `v4l2loopback` device
- Ten full scene presets with rename/update/delete/default-on-startup lifecycle
- Twenty independent color templates
- Token-authenticated LAN phone remote with QR pairing
- Compact toolbar and 14 compositor-managed global actions through the XDG GlobalShortcuts portal
- Teleprompter scripts with import/editing, speed, size, colors, opacity, guide, loop, and countdown
- Local voice-note sessions with pause, timestamped notes and screenshot markers, optional offline
  Whisper transcription, and Markdown summaries
- Firmware/build reporting, JSON diagnostics, rotating logs, and privacy-conscious support bundles
- Automatic light/dark appearance, with optional live Omarchy palette support

## Run from the repository

On Arch Linux, install the native stack if it is not already present: `gtk4`, `libadwaita`,
`python-gobject`, `gstreamer`, `gst-plugins-base`, `gst-plugins-good`, `gst-plugins-bad`, `gst-libav`,
and `v4l-utils`. The launcher creates a local environment anchored to the system Python so
Arch's GTK bindings and Link Studio's Python dependencies are both available.

```bash
./scripts/run-dev
```

Useful diagnostics:

```bash
./scripts/run-dev --diagnose
./scripts/run-dev --version
./scripts/run-dev --device /dev/video2
./scripts/run-dev --no-preview
```

`--diagnose` is read-only and prints detected cameras, camera state, firmware information, and the
active appearance palette as JSON.

## Install for the current user

```bash
./scripts/install-user
```

This installs an isolated environment below `${XDG_DATA_HOME:-~/.local/share}/link-studio`, creates
`link-studio` in `${XDG_BIN_HOME:-~/.local/bin}`, and installs desktop/AppStream entries. It does
not require root or edit desktop configuration.

The maintained Arch package recipe lives under `packaging/aur`. New AUR account registration is
currently closed upstream, so its initial AUR submission is pending. Build the same package locally
in the meantime:

```bash
yay -S python-mediapipe
cd packaging/aur
makepkg -si
```

Every package source is publicly downloadable from the GitHub releases.

Optional local integrations:

```bash
link-studio-setup-virtual-camera
link-studio-setup-local-ai
```

The helpers use `pacman` for the required Arch packages. The virtual-camera helper loads a temporary
`/dev/video20` device. The AI helper installs `whisper-cpp` and verifies the downloaded multilingual
base model against a pinned SHA-256 checksum.

## Desktop appearance

Link Studio follows the normal libadwaita light/dark appearance. On Omarchy it also respects the
active color palette automatically; no theme hook or user configuration is required.

Global actions use the desktop portal rather than editing Hyprland bindings. Enable them under
Device → Application. Desktops with a portal configuration dialog can assign keys there. On
Hyprland, list the registered action names with `hyprctl globalshortcuts`, then use its `global`
dispatcher in `~/.config/hypr/hyprland.lua`, for example:

```lua
hl.bind("SUPER + SHIFT + R", hl.dsp.global("io.github.linkstudio.LinkStudio:record"))
hl.bind("SUPER + SHIFT + S", hl.dsp.global("io.github.linkstudio.LinkStudio:screenshot"))
```

## Safety model

- The backend never detaches `uvcvideo`; this avoids a known Link 2 failure mode where detach/rebind
  cycles can leave USB present without a working video node.
- Hardware mode writes are serialized, paced, and read back where the protocol supports it.
- Unknown firmware-update, factory-reset, and compatibility-mode writes are never guessed. The
  Device page reports firmware and links to Insta360's recovery-safe U-Disk flow.
- Privacy mode is the camera's gimbal-down mode, not a physical shutter.
- Phone control is LAN-only, uses an unguessable per-session token, and is off by default.
- MediaPipe effects and Whisper transcription run locally.

## Architecture

```text
GTK4 / libadwaita application
 ├─ V4L2 standard controls ─────────── gimbal, zoom, image, focus
 ├─ validated UVC extension controls ─ AI modes, HDR, exposure, privacy, audio
 ├─ GStreamer pipelines ───────────── preview, screenshots, MP4, virtual camera
 ├─ MediaPipe + OpenCV ────────────── effects, face tracking, Smart Whiteboard
 ├─ local tools ───────────────────── phone remote, teleprompter, meetings
 ├─ XDG desktop portals ───────────── compositor-managed global actions
 └─ XDG JSON stores ───────────────── scenes, scripts, output locations, settings
```

## Development and verification

```bash
.venv/bin/python -m unittest discover -v
uvx ruff check src tests scripts
.venv/bin/python -m compileall -q src tests
./scripts/run-dev --diagnose
```

Link Studio is MIT-licensed. Third-party model and research attribution is in
[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md). Insta360 and Insta360 Link are trademarks of their
respective owner; this project is not affiliated with or endorsed by Insta360.
