Display Modes

Specchio offers multiple display modes to suit different needs — from pixel-perfect video streaming to ultra-low-bandwidth synthetic UI.

Table of Contents

1. Mode Overview
2. Auto Mode
3. USB Video Mode
4. Screenshot Mode
5. Lite Mode (Accessibility)
6. Choosing the Right Mode

---

Mode Overview

Mode	Transport	FPS	Quality	Bandwidth	License
Auto	Best available	Up to 60	Best	Varies	Free
USB Video	USB (CoreMediaIO)	30-60	Pixel-perfect	High	Free
Screenshot	HTTP polling	5-15	Pixel-perfect	Medium	Free
Lite (A11y)	HTTP XML diff	2-5	Synthetic UI	Very low	Free

When to Use Each Mode

• Auto: Let Specchio choose the best mode automatically
• USB Video: Maximum quality and smoothness (USB only)
• Screenshot: Reliable pixel-perfect mirroring
• Lite: Poor network or need minimal bandwidth

---

Auto Mode

Auto mode automatically selects the best available display mode based on your connection type and device capabilities.

How Auto Mode Chooses

1. USB Connection: Uses USB Video if device supports it
2. WiFi Connection: Uses Screenshot mode
3. Fallback: Automatically degrades if issues detected

Advantages

Benefit	Description
🤖 Automatic	No manual mode switching needed
🎯 Best Quality	Always uses best available mode
🔄 Adaptive	Degrades gracefully if issues occur

When to Use Auto

• ✅ Most users should use Auto mode
• ✅ Don't know which mode to pick
• ✅ Want automatic optimization
• ✅ Switch between USB and WiFi frequently

---

USB Video Mode

USB Video mode uses CoreMediaIO to capture H.264 video stream directly from your iPhone over USB.

How it Works

1. Specchio uses CMIO to create a USB video capture session
2. iPhone streams H.264 encoded video over USB
3. Specchio decodes and displays in real-time
4. Input is sent separately via WebDriverAgent

Advantages

Benefit	Description
🎬 Smooth Video	Hardware-accelerated H.264 decoding
🖼️ Pixel-Perfect	Exact representation of iPhone screen
⚡ Low Latency	Direct USB video path
🔋 Efficient	Hardware encoding/decoding

Requirements

• USB connection required
• iPhone with USB Video capability (most modern devices)
• CoreMediaIO support in macOS

Performance

Metric	Value
Frame Rate	30-60 FPS
Latency	5-15ms
Resolution	Native device resolution
CPU Usage	Low (hardware decode)

When to Use USB Video

• ✅ Connected via USB
• ✅ Need smooth, real-time video
• ✅ Gaming or dynamic content
• ✅ Want best possible quality

---

Screenshot Mode

Screenshot mode polls WebDriverAgent for periodic screenshots of your iPhone screen.

How it Works

1. Specchio requests screenshots via HTTP GET /screenshot
2. WDA captures current screen as JPEG/PNG
3. Image is sent back over HTTP
4. Specchio displays the image

Advantages

Benefit	Description
🎯 Pixel-Perfect	Exact screenshot from device
🔌 Works on WiFi	No special hardware needed
✅ Reliable	Simple HTTP, less to go wrong
📱 Universal	Works on all iOS devices

Performance

Metric	Value
Frame Rate	5-15 FPS
Latency	50-200ms
Resolution	Native device resolution
CPU Usage	Medium (image decode)

When to Use Screenshot

• ✅ WiFi connection
• ✅ Pixel-perfect quality needed
• ✅ Content is mostly static
• ✅ USB Video not available

---

Lite Mode (Accessibility)

Lite mode uses the iOS accessibility tree to render a synthetic version of your iPhone's UI.

How it Works

1. Specchio fetches accessibility tree via HTTP GET /source
2. XML represents UI hierarchy and element properties
3. Specchio renders a simplified UI using SwiftUI
4. Only changed elements are updated (diffing)

Advantages

Benefit	Description
📉 Minimal Bandwidth	XML is tiny compared to images
🎨 Clean UI	Synthetic, readable interface
🔍 Accessible	Shows accessibility metadata
⚡ Efficient	Only updates changed elements

Limitations

Limitation	Impact
Not Pixel-Perfect	Synthetic UI, not screenshots
Lower Frame Rate	2-5 FPS
Missing Visuals	Custom graphics, videos, animations may not show

Performance

Metric	Value
Frame Rate	2-5 FPS
Latency	100-300ms
Resolution	Synthetic (not pixel-based)
Bandwidth	Very low (XML)

When to Use Lite

• ✅ Poor network connection
• ✅ Need minimal bandwidth usage
• ✅ Static content (forms, text)
• ✅ Accessibility testing

---

Choosing the Right Mode

Decision Tree

Need best quality?
├─ Yes → USB Video (if USB connected)
│        → Screenshot (if WiFi)
└─ No / Poor network?
   └─ Lite Mode

Quick Reference

Your Situation	Recommended Mode
USB connected, want smooth video	USB Video
USB connected, don't care	Auto
WiFi connected, want quality	Screenshot
Poor network, need basic mirroring	Lite
Don't know	Auto

Performance Comparison

Quality: USB Video > Screenshot > Lite
Speed:  USB Video > Screenshot > Lite
Efficiency: Lite > Screenshot > USB Video

---

Switching Display Modes

How to Switch

1. In the Specchio menu bar, click the display mode indicator
2. Select your preferred mode from the dropdown
3. The switch takes effect immediately

Mode Persistence

Specchio remembers your mode preference:

• Per device (USB vs WiFi)
• Resets to Auto on new devices
• Can be changed in Settings

---

Troubleshooting Display Modes

USB Video Not Available

Problem: USB Video mode option is greyed out.

Solutions:

• Make sure you're connected via USB
• Try disconnecting and reconnecting
• Check if your device supports USB Video
• Restart Specchio

Screenshot Mode Slow/Laggy

Problem: Screenshot updates are very slow.

Diagnostic commands:

# Test screenshot endpoint directly
time curl http://localhost:8100/screenshot --output test.png

# Check file size (smaller = faster)
ls -lh test.png

Solutions:

• Try Lite mode for better performance
• Check your USB cable quality
• Close other apps using USB bandwidth
• Try USB Video mode if available

Lite Mode Shows Blank Screen

Problem: Lite mode shows nothing or incomplete UI.

Diagnostic commands:

# Test accessibility endpoint
curl http://localhost:8100/source

# Should return XML with UI tree

Solutions:

• Some apps don't expose accessibility properly
• Switch to Screenshot mode for those apps
• Ensure Accessibility permissions are granted to WDA

For more help, see Troubleshooting.