feat: Enhance Android H.264 streaming support and refactor related components

- Updated StreamQualityLimits struct to be cloneable and public.
- Introduced stream_quality_limits_for_payload function to resolve quality limits from payload.
- Refactored Android H.264 socket handling to utilize new quality resolution logic.
- Renamed native encoder function to encode BGRA frames instead of RGBA.
- Removed deprecated RGBA WebRTC transport handling in favor of H.264.
- Implemented shared video frame encoding for Android using native H.264 encoder.
- Improved error handling and logging for stream quality updates and encoding failures.
- Updated SimDeck documentation to reflect changes in Android live viewing capabilities.

Author: DjDeveloperr

README.md

@@ -39,7 +39,7 @@ view inside the editor.
 
 ## Features
 
-- Supports streaming both iOS simulators and Android emulators
+- Supports native H.264 streaming for both iOS simulators and Android emulators
 - Full simulator control & inspection using private iOS accessibility APIs and Android UIAutomator - available using `simdeck` CLI
 - Real-time screen `describe` command using accessibility view tree - available in token-efficient format for agents
 - Profiling built-in: CPU, memory, disk writes, network throughput, hang signals, and stack sampling

docs/api/rest.md

@@ -173,7 +173,7 @@ Performance query parameters:
 | `GET`  | `/api/simulators/{udid}/control`      | Alias for input control WebSocket      |
 | `POST` | `/api/simulators/{udid}/refresh`      | Request a fresh frame or keyframe      |
 
-For normal clients, copy the browser behavior instead of hand-coding a raw decoder. The UI supports WebRTC first and H.264 WebSocket fallback.
+For normal clients, copy the browser behavior instead of hand-coding a raw decoder. The UI supports WebRTC first and H.264 WebSocket fallback. Android emulator IDs use the same endpoints; their H.264 frames are produced from the emulator `-share-vid` display surface, not screenshot polling.
 
 Minimal WebRTC request:
 

docs/guide/architecture.md

@@ -26,7 +26,7 @@ This is why a long-lived service feels faster than repeatedly calling lower-leve
 
 ## Video flow
 
-The browser opens a live stream for the selected device. SimDeck sends fresh frames, drops stale ones when a client falls behind, and lets the browser request refreshes. The UI can use WebRTC or H.264-over-WebSocket fallback depending on browser support and network behavior.
+The browser opens a live stream for the selected device. SimDeck sends fresh frames, drops stale ones when a client falls behind, and lets the browser request refreshes. iOS frames come from the native display bridge and are encoded on the Mac; Android frames come from the emulator `-share-vid` shared display surface and are encoded on the Mac. The UI can use WebRTC or H.264-over-WebSocket fallback depending on browser support and network behavior.
 
 Tune this from the user-facing controls or with:
 

docs/guide/troubleshooting.md

@@ -137,6 +137,8 @@ curl http://127.0.0.1:4310/api/metrics
 
 If `frames_dropped_server` keeps climbing, the client or network cannot keep up. Move closer to the host, reduce quality, or switch to software encoding.
 
+For Android emulator streams, SimDeck uses the emulator `-share-vid` shared display surface. If Android video never starts, confirm `adb devices` shows the emulator as `device`, that it has fully booted, and that externally launched emulators were started with `-share-vid`. SimDeck-owned Android boots add the flag automatically.
+
 ### Browser cannot establish WebRTC
 
 Force the H.264 WebSocket fallback while testing:

docs/guide/video.md

@@ -3,12 +3,15 @@
 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.
+Android emulator H.264 uses the emulator `-share-vid` display surface. SimDeck reads BGRA frames from the `videmulator<console-port>` shared memory region and encodes them on the Mac, so normal Android live video stays on the native shared display path.
 
 ## 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.
+SimDeck starts encoding when a browser stream needs H.264 frames. For iOS, 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.
+For Android, SimDeck starts emulators with `-share-vid`, maps the shared display
+region, and feeds changed BGRA frames into the native host H.264 encoder.
 
 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
@@ -58,6 +61,12 @@ simdeck service restart --video-codec software
 | `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. |
 
+The codec setting controls iOS simulator host encoding. Android emulator streams
+use a dedicated host encoder for shared display frames; set
+`SIMDECK_ANDROID_VIDEO_CODEC=hardware` or `software` before starting the service
+when you need to override Android's encoder choice. Stream quality controls the
+encoded Android frame size.
+
 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

packages/client/src/api/types.ts

@@ -50,7 +50,7 @@ export interface SimulatorMetadata {
   isBooted: boolean;
   android?: {
     avdName?: string;
-    grpcPort?: number;
+    consolePort?: number;
     serial?: string;
   };
   privateDisplay?: PrivateDisplayInfo;

packages/client/src/features/stream/streamWorkerClient.test.ts

@@ -4,7 +4,6 @@ import {
   buildStreamTarget,
   initialStreamBackend,
   preferredStreamBackend,
-  shouldUseLocalAndroidRgbaWebRtc,
 } from "./streamWorkerClient";
 
 describe("streamWorkerClient", () => {
@@ -25,16 +24,16 @@ describe("streamWorkerClient", () => {
     expect(preferredStreamBackend(target)).toBe("webrtc");
   });
 
-  it("treats explicit RGBA transport as a WebRTC backend", () => {
+  it("ignores unknown stream query parameters", () => {
     const previousWindow = globalThis.window;
     Object.defineProperty(globalThis, "window", {
       configurable: true,
-      value: { location: { search: "?stream=rgba" } },
+      value: { location: { search: "?stream=unknown" } },
     });
 
     try {
       expect(preferredStreamBackend(buildStreamTarget("android:Pixel_8"))).toBe(
-        "webrtc",
+        "auto",
       );
     } finally {
       Object.defineProperty(globalThis, "window", {
@@ -62,63 +61,4 @@ describe("streamWorkerClient", () => {
       ).RTCPeerConnection = previousPeerConnection;
     }
   });
-
-  it("uses RGBA WebRTC transport for local loopback Android streams", () => {
-    const previousWindow = globalThis.window;
-    Object.defineProperty(globalThis, "window", {
-      configurable: true,
-      value: { location: { hostname: "127.0.0.1", search: "" } },
-    });
-
-    try {
-      expect(
-        shouldUseLocalAndroidRgbaWebRtc(
-          buildStreamTarget("android:Pixel_8", {
-            platform: "android-emulator",
-            transport: "auto",
-          }),
-        ),
-      ).toBe(true);
-    } finally {
-      Object.defineProperty(globalThis, "window", {
-        configurable: true,
-        value: previousWindow,
-      });
-    }
-  });
-
-  it("keeps Android RGBA disabled for h264 or remote streams", () => {
-    const previousWindow = globalThis.window;
-    const location = { hostname: "127.0.0.1", search: "?stream=h264" };
-    Object.defineProperty(globalThis, "window", {
-      configurable: true,
-      value: { location },
-    });
-
-    try {
-      expect(
-        shouldUseLocalAndroidRgbaWebRtc(
-          buildStreamTarget("android:Pixel_8", {
-            platform: "android-emulator",
-            transport: "auto",
-          }),
-        ),
-      ).toBe(false);
-      location.search = "";
-      expect(
-        shouldUseLocalAndroidRgbaWebRtc(
-          buildStreamTarget("android:Pixel_8", {
-            platform: "android-emulator",
-            remote: true,
-            transport: "auto",
-          }),
-        ),
-      ).toBe(false);
-    } finally {
-      Object.defineProperty(globalThis, "window", {
-        configurable: true,
-        value: previousWindow,
-      });
-    }
-  });
 });