Video & Streaming

SimDeck streams live device video to the browser. Local sessions default to high quality. Remote or constrained sessions can trade detail for lower CPU and latency.

iOS simulator H.264 uses VideoToolbox for hardware encoding and x264 for software encoding.

When Encoding Runs

SimDeck starts encoding when a browser stream needs H.264 frames. The server requests an initial keyframe to answer the WebRTC or H.264 WebSocket viewer, then keeps a shared refresh pump active while frame subscribers exist.

The browser reports whether the page and stream canvas are foreground. When all known viewers are hidden or the last frame subscriber disconnects, the native session pauses encoder input and releases the active compression session. A visible viewer, explicit refresh, or stream reconnect asks for a fresh keyframe.

Pick A Stream Quality

Start with the default:

simdeck

Lower quality when the stream stutters, the machine is under load, or you are using a remote browser:

simdeck daemon restart --stream-quality low
simdeck daemon restart --stream-quality tiny
simdeck daemon restart --stream-quality ci-software

Common profiles:

Profile	Use it for
full	Local browser on a fast Mac
balanced	Good local quality with less bandwidth
economy	Remote browser or busy machine
low	Slower Wi-Fi or shared hosts
tiny	Pull request previews and low bandwidth
ci-software	Virtualized CI Macs

The browser also has stream controls for transport, resolution, FPS, and refresh.

Pick A Codec

simdeck daemon restart --video-codec auto
simdeck daemon restart --video-codec hardware
simdeck daemon restart --video-codec software

Codec	Use it for
auto	Normal use. SimDeck can move between hardware and software as needed.
hardware	Dedicated local machines where VideoToolbox hardware H.264 is reliable.
software	x264 software H.264 for CI, screen recording conflicts, or hardware encoder stalls.

When multiple simulator streams run at the same time, auto keeps one active stream on the hardware encoder path and routes additional active auto streams to software encoding. This avoids saturating the shared VideoToolbox hardware encoder while preserving explicit --video-codec hardware behavior.

For very constrained software sessions:

simdeck daemon restart --video-codec software --low-latency

WebRTC And Fallback

The browser tries WebRTC first. If WebRTC cannot render a frame, the UI can fall back to H.264 over WebSocket when the browser supports WebCodecs.

Force a mode while debugging:

http://127.0.0.1:4310?stream=webrtc
http://127.0.0.1:4310?stream=h264

Remote Browsers

For another browser on the same network, see LAN Access.

For routed remote access, use a tunnel or relay you trust. If your network requires TURN for WebRTC, set these before starting SimDeck:

SIMDECK_WEBRTC_ICE_SERVERS=turns:turn.example.com:5349?transport=tcp \
SIMDECK_WEBRTC_ICE_USERNAME=simdeck \
SIMDECK_WEBRTC_ICE_CREDENTIAL=secret \
SIMDECK_WEBRTC_ICE_TRANSPORT_POLICY=relay \
simdeck daemon start --video-codec software --stream-quality low

Stream Diagnostics

Check health:

curl http://127.0.0.1:4310/api/health

Check counters:

curl http://127.0.0.1:4310/api/metrics

Signals worth watching:

Signal	Meaning
latest_first_frame_ms	How long the most recent viewer waited for the first frame
frames_dropped_server	The server skipped frames to keep the stream fresh
keyframe_requests	The client or server requested stream recovery
encoders[].encoder.overloadState	Encoder pressure: nominal, strained, or overloaded

Stuck Stream Checklist

1. Click refresh in the browser toolbar.

2. Restart with software encoding:

   simdeck daemon restart --video-codec software

3. Lower stream quality:

   simdeck daemon restart --stream-quality low

4. Restart Apple's simulator service:

   simdeck core-simulator restart

5. See Troubleshooting.