Live View

luotsi view opens a long-lived session that mirrors a connected Android device into a local SDL window while also emitting structured JSONL events on stdout.

luotsi view --device <serial> --preset safe
luotsi view --profile desk
luotsi view --last

Representative device content mirrored through Luotsi during the Buggy Controller walkthrough. — The operator window is the visible part of the workflow, but the same session also writes replay metadata and JSONL events that stay useful after the device disconnects.

Runtime path

Luotsi live view sequence diagram separating video packets, host-routed control input, JSONL event artifacts, read-only observer sessions, and replay metadata. — The live view path separates video transport, host-routed input, JSONL session events, artifact capture, and read-only observer joins so replay can start from saved evidence later.

What it is good at

Local operator control with toolbar buttons and hotkeys
Shared stream state for agents and CI via JSONL events such as view_started, view_stats, and view_ended
Presets and profiles for repeatable view setups
Artifact capture for screenshots, recordings, diagnostics, and replay metadata

Defaults that matter

--preset safe is the conservative launch tuning
--capture-backend auto prefers MediaProjection and falls back to screenrecord
--stats-interval-ms 1000 controls JSONL view_stats cadence, and 0 disables those periodic stats events
--renderer-stats-interval-ms 0 controls how often the local renderer/title consumes stats independently from JSONL emission
--record <file.h264|file.mp4|file.mkv> chooses a startup recording target; raw .h264 does not require ffmpeg, container outputs do
Artifact roots default to a timestamped temp directory unless you pass --artifacts

Useful commands

luotsi view setup --device <serial>
luotsi view-doctor --device <serial>
luotsi view-doctor --device <serial> --fix
luotsi view --device <serial> --save-profile lab-device
luotsi reconnect --profile lab-device

Use view setup --dry-run when you want Luotsi to explain what it would stage without changing the selected device. Use view-doctor --fix when you want the diagnostic entry point to continue into setup/repair instead of only reporting readiness.

Operator controls that matter

F7 opens the current artifact root so screenshots, recordings, and replay metadata are one shortcut away.
F9 toggles local recording and reuses the --record directory and naming pattern when you supplied one at startup.
F10 or the help button reveals the in-window legend, which is the fastest way to teach a new operator the local shortcuts.
The toolbar mirrors the main hotkeys, and the multi-device shelf appears automatically when more than one adb-visible transport is available.

Session outputs that matter

Every view session is both a local operator loop and a replayable artifact source.

view_started includes the resolved artifact root, negotiated stream settings, and stats cadence
session-timeline.jsonl mirrors the session event stream into the artifact root
session-replay.json gives replay-oriented metadata for later replay summarize, replay capsule, replay timeline, or replay open commands
Screenshot, recording, share, and file-transfer actions emit their own JSONL events so CI or agents can track behavior without scraping terminal text
replay packet, replay open, and artifacts open all work against that same root after the session ends; start with replay packet for the production packet/check handoff, use replay open for replay-specific next actions, and use artifacts open when you specifically need the generic artifact browser

The higher-signal event families to watch are:

startup and diagnostics: view_startup_phase, view_diagnostic
stream health: view_stats, view_reconnect_requested, view_reconnected, view_error, view_ended
local capture: view_screenshot_captured, view_recording_started, view_recording_stopped, view_artifacts_opened
sharing and observers: view_share_started, view_share_client_connected
operator and file actions: view_clipboard_pasted, view_file_pushed, view_file_pulled, view_package_installed

Source sessions can relay the live stream over TCP:

luotsi view --device <serial> --share-bind 0.0.0.0:9000
luotsi view --join-share 192.168.0.10:9000

Joined share sessions are forced into read-only observer mode. The stream renders, but input is blocked intentionally.

Observer-only windows also block screenshot and recording controls with view_input_blocked because the source session owns those device-facing capture operations.

Source sessions emit view_share_started when the relay is bound and view_share_client_connected when an observer joins. The shared transport also replays the cached bootstrap packets plus the latest keyframe to late observers so they do not connect into an undecodable stream.

The relay is intended for trusted lab or dev networks. It is raw TCP today, with no TLS and no authentication.

When to use something else

Use inspect when you need structured JSONL snapshots and command loops instead of a live window.
Use scenario runs when you need repeatability, reports, and versioned playbooks.