android-emulator-webrtc 1.0.18 → 2.0.1

package/dist/src/components/emulator/emulator.d.ts

@@ -0,0 +1,64 @@
+import React from "react";
+export interface EmulatorProps {
+    /** Endpoint where we can reach the emulator gateway (host:port or http(s)://host:port). */
+    uri: string;
+    /** The authentication service to use, or null for no authentication. */
+    auth?: any;
+    /** True if the audio should be disabled. */
+    muted?: boolean;
+    /** Volume between [0, 1] when audio is enabled. 0 is muted, 1.0 is 100% */
+    volume?: number;
+    /** Called upon state change, one of ["connecting", "connected", "disconnected"] */
+    onStateChange?: (state: string) => void;
+    /** Called when the audio becomes (un)available. True if audio is available, false otherwise. */
+    onAudioStateChange?: (audio: boolean) => void;
+    /** The width of the component */
+    width?: number;
+    /** The height of the component */
+    height?: number;
+    /** A [GeolocationCoordinates](https://developer.mozilla.org/en-US/docs/Web/API/GeolocationCoordinates) like object indicating where the device is. */
+    gps?: {
+        latitude: number;
+        longitude: number;
+        altitude?: number;
+        heading?: number;
+        speed?: number;
+    };
+    /** Callback that will be invoked in case of errors. */
+    onError?: (error: any) => void;
+}
+export interface EmulatorRef {
+    sendKey(key: string): void;
+}
+/**
+ * A React component that displays a remote android emulator.
+ *
+ * The emulator will mount a webrtc view component to display the current state
+ * of the emulator. It will translate mouse and touch events on this component and send them
+ * to the actual emulator over WebRTC Data Channels.
+ *
+ * #### Authentication Service
+ *
+ * The authentication service should implement the following methods:
+ *
+ * - `authHeader()` which must return a set of headers that should be send along with a request.
+ * - `unauthorized()` a function that gets called when a 401 was received.
+ *
+ * Note that chrome will not autoplay the video if it is not muted and no interaction
+ * with the page has taken place. See https://developers.google.com/web/updates/2017/09/autoplay-policy-changes.
+ *
+ * #### Pressing hardware buttons
+ *
+ * This component has a method `sendKey` that sends a key to the emulator.
+ * You can use this to send physical button events to the emulator for example:
+ *
+ * "AudioVolumeDown" - 	Decreases the audio volume.
+ * "AudioVolumeUp"   -	Increases the audio volume.
+ * "Power"	         -  The Power button or key, turn off the device.
+ * "AppSwitch"       -  Should bring up the application switcher dialog.
+ * "GoHome"          -  Go to the home screen.
+ * "GoBack"          -  Open the previous screen you were looking at.
+ *
+ */
+declare const Emulator: React.ForwardRefExoticComponent<EmulatorProps & React.RefAttributes<EmulatorRef>>;
+export default Emulator;

package/dist/src/components/emulator/net/emulator_status.d.ts

@@ -0,0 +1,45 @@
+export interface AuthService {
+    authHeader?(): Record<string, string>;
+    unauthorized?(): void;
+}
+export interface EmulatorStatusData {
+    status?: string;
+    hardwareConfig?: Record<string, string>;
+    [key: string]: any;
+}
+/**
+ * Utility class to query and manage the emulator's status by communicating
+ * with its REST configuration endpoint. It parses the hardware configuration
+ * and caches the status.
+ *
+ * @export
+ * @class EmulatorStatus
+ */
+declare class EmulatorStatus {
+    statusUrl: string;
+    auth: AuthService | null;
+    status: EmulatorStatusData | null;
+    /**
+     * Creates an EmulatorStatus object that can retrieve the status of the running emulator.
+     *
+     * @param statusUrl The REST endpoint to retrieve status.
+     * @param auth The authentication service to use, or null for no authentication.
+     */
+    constructor(statusUrl: string, auth?: AuthService | null);
+    /**
+     * Gets the cached status object.
+     *
+     * @returns The cached emulator status or null if not yet loaded.
+     * @memberof EmulatorStatus
+     */
+    getStatus: () => EmulatorStatusData | null;
+    /**
+     * Retrieves the current status from the emulator REST endpoint.
+     *
+     * @param fnNotify Callback invoked when the status is retrieved. Receives the status object.
+     * @param cache If true, uses the cached status if available instead of fetching.
+     * @memberof EmulatorStatus
+     */
+    updateStatus: (fnNotify: (status: EmulatorStatusData) => void, cache?: boolean) => EmulatorStatusData;
+}
+export default EmulatorStatus;

package/dist/src/components/emulator/net/logger.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @fileoverview Configures and exports a loglevel logger instance scoped to
+ * the 'android-emulator-webrtc' package.
+ */
+import log from "loglevel";
+declare const logger: log.Logger;
+export default logger;

package/dist/src/components/emulator/net/ws_jsep_protocol_driver.d.ts

@@ -0,0 +1,213 @@
+export interface WsJsepConfig {
+    enableLogging?: boolean;
+    onError?: (error: Error | Event) => void;
+    maxReconnectAttempts?: number;
+    reconnectDelay?: number;
+    reconnectBackoffFactor?: number;
+    [key: string]: any;
+}
+export interface StreamCallbacks {
+    onConnected?: (track: MediaStreamTrack) => void;
+    onDisconnected?: (driver: WsJsepProtocol) => void;
+}
+export interface EmulatorController {
+    sendMouse?(msg: any): void;
+    sendKey?(msg: any): void;
+    sendTouch?(msg: any): void;
+}
+export interface JsepSignal {
+    start?: RTCConfiguration;
+    type?: "offer" | "answer";
+    sdp?: RTCSessionDescriptionInit | string;
+    candidate?: RTCIceCandidateInit | string;
+    bye?: boolean;
+}
+/**
+ * A JSEP protocol driver that uses WebSockets for signaling.
+ *
+ * @export
+ * @class WsJsepProtocol
+ */
+export default class WsJsepProtocol {
+    wsUrl: string;
+    emulator: EmulatorController | null;
+    config: WsJsepConfig;
+    onError?: (error: Error | Event) => void;
+    maxReconnectAttempts: number;
+    reconnectDelay: number;
+    reconnectBackoffFactor: number;
+    connected: boolean;
+    event_forwarders: Record<string, RTCDataChannel>;
+    peerConnection: RTCPeerConnection | null;
+    ws: WebSocket | null;
+    pendingCandidates: (RTCIceCandidateInit | string)[];
+    remoteDescriptionSet: boolean;
+    signalQueue: JsepSignal[];
+    isProcessingSignal: boolean;
+    onConnected: ((track: MediaStreamTrack) => void) | null;
+    onDisconnected: ((driver: WsJsepProtocol) => void) | null;
+    reconnectAttempts: number;
+    reconnectTimeoutId: any | null;
+    /**
+     * Creates an instance of WsJsepProtocol.
+     *
+     * @param wsUrl The WebSocket JSEP signaling URL.
+     * @param emulator Fallback emulator controller for sending events when WebRTC is unavailable.
+     * @param config Configuration options.
+     */
+    constructor(wsUrl: string, emulator?: EmulatorController | null, config?: WsJsepConfig);
+    /**
+     * Establishes the WebSocket connection and starts the signaling process.
+     * Cleans up any existing connection beforehand.
+     *
+     * @param callbacks Callbacks for stream lifecycle events.
+     */
+    startStream: (callbacks?: StreamCallbacks) => void;
+    /**
+     * Internal method to establish WebSocket connection.
+     *
+     * @private
+     */
+    _connect: () => void;
+    /**
+     * Queues a reconnection attempt with exponential backoff.
+     *
+     * @private
+     */
+    _queueReconnect: () => void;
+    /**
+     * Internal handler for incoming WebSocket messages. Parses the signal
+     * and queues it for sequential processing.
+     *
+     * @private
+     * @param event The WebSocket message event.
+     */
+    _handleWsMessage: (event: MessageEvent) => void;
+    /**
+     * Sequentially processes JSEP signals from the queue.
+     *
+     * @private
+     */
+    _processSignalQueue: () => Promise<void>;
+    /**
+     * Handles WebSocket connection close events.
+     *
+     * @private
+     * @param event The WebSocket close event.
+     */
+    _handleWsClose: (event: CloseEvent) => void;
+    /**
+     * Handles WebSocket error events.
+     *
+     * @private
+     * @param error The WebSocket error event.
+     */
+    _handleWsError: (error: Event) => void;
+    /**
+     * Processes a single JSEP signal (e.g., start, offer, answer, candidate, bye).
+     *
+     * @private
+     * @param signal The JSEP signaling message.
+     */
+    _handleSignal: (signal: JsepSignal) => Promise<void>;
+    /**
+     * Initializes the RTCPeerConnection and local data channels based on the start configuration.
+     *
+     * @private
+     * @param config The signaling start configuration.
+     */
+    _handleStart: (config: RTCConfiguration) => Promise<void>;
+    /**
+     * Handles incoming media track events from the RTCPeerConnection.
+     *
+     * @private
+     * @param e The track event.
+     */
+    _handlePeerConnectionTrack: (e: RTCTrackEvent) => void;
+    /**
+     * Handles ICE candidate generation from the local RTCPeerConnection.
+     *
+     * @private
+     * @param e The ICE candidate event.
+     */
+    _handlePeerIceCandidate: (e: RTCPeerConnectionIceEvent) => void;
+    /**
+     * Monitors connection state changes on the RTCPeerConnection to trigger disconnection.
+     *
+     * @private
+     * @param e The state change event.
+     */
+    _handlePeerConnectionStateChange: (e: Event) => void;
+    /**
+     * Registers a data channel for event forwarding.
+     *
+     * @private
+     * @param channel The data channel.
+     */
+    _setupDataChannel: (channel: RTCDataChannel) => void;
+    /**
+     * Handles remote data channel creation.
+     *
+     * @private
+     * @param e The data channel event.
+     */
+    _handleDataChannel: (e: RTCDataChannelEvent) => void;
+    /**
+     * Processes a remote SDP offer or answer, applying it to the RTCPeerConnection.
+     *
+     * @private
+     * @param sdp The session description.
+     */
+    _handleSDP: (sdp: RTCSessionDescriptionInit) => Promise<void>;
+    /**
+     * Adds a remote ICE candidate to the RTCPeerConnection.
+     *
+     * @private
+     * @param candidate The ICE candidate object or string.
+     */
+    _addIceCandidate: (candidate: RTCIceCandidateInit | string) => void;
+    /**
+     * Handles an incoming remote ICE candidate, queueing it if the remote description is not yet set.
+     *
+     * @private
+     * @param candidate The remote ICE candidate.
+     */
+    _handleCandidate: (candidate: RTCIceCandidateInit | string) => void;
+    /**
+     * Handles the 'bye' signal from the remote side, triggering disconnection.
+     *
+     * @private
+     */
+    _handleBye: () => void;
+    /**
+     * Serializes and sends a JSEP JSON message over the WebSocket.
+     *
+     * @private
+     * @param jsonObject The JSON payload.
+     */
+    _sendJsep: (jsonObject: JsepSignal) => void;
+    /**
+     * Sends a control message (mouse, keyboard, touch) over either the corresponding
+     * WebRTC DataChannel or via the fallback emulator controller.
+     *
+     * @param label The channel label ("mouse", "keyboard", "touch").
+     * @param msg The protobuf message instance.
+     */
+    send: (label: string, msg: any) => void;
+    /**
+     * Cleans up the current connection's WebSocket and PeerConnection state,
+     * but does not mark the driver as permanently disconnected or trigger
+     * the onDisconnected callback. Used during reconnection.
+     *
+     * @private
+     */
+    _disconnectState: () => void;
+    /**
+     * Disconnects both the WebSocket signaling connection and the WebRTC PeerConnection.
+     */
+    disconnect: () => void;
+    /**
+     * Fully cleans up signaling and WebRTC state.
+     */
+    cleanup: () => void;
+}

package/dist/src/components/emulator/views/event_handler.d.ts

@@ -0,0 +1,37 @@
+import React from "react";
+import WsJsepProtocol from "../net/ws_jsep_protocol_driver";
+export interface MouseKeyHandlerProps {
+    /** The REST endpoint to retrieve status. */
+    statusUrl: string;
+    /** Jsep protocol driver, used to send mouse & touch events. */
+    jsep: WsJsepProtocol;
+    /** The authentication service to use. */
+    auth?: any;
+    /** The width of the component. */
+    width?: number;
+    /** The height of the component. */
+    height?: number;
+    [key: string]: any;
+}
+export interface MouseKeyHandlerRef {
+    scaleCoordinates(xp: number, yp: number): {
+        x: number;
+        y: number;
+        scaleX: number;
+        scaleY: number;
+    };
+    setDeviceWidth: React.Dispatch<React.SetStateAction<number>>;
+    setDeviceHeight: React.Dispatch<React.SetStateAction<number>>;
+    handlerRef: React.RefObject<HTMLDivElement>;
+}
+/**
+ * A handler that extends a view to send key/mouse events to the emulator.
+ * It wraps the inner component in a div, and will use the jsep handler
+ * to send key/mouse/touch events over the proper channel.
+ *
+ * It will translate the mouse events based upon the returned display size of
+ * the emulator.
+ *
+ * You usually want to wrap a EmulatorRtcview, or EmulatorPngView in it.
+ */
+export default function withMouseKeyHandler<P extends object>(WrappedComponent: React.ComponentType<P>): React.ForwardRefExoticComponent<React.PropsWithoutRef<MouseKeyHandlerProps & P> & React.RefAttributes<MouseKeyHandlerRef>>;

package/dist/src/components/emulator/views/webrtc_view.d.ts

@@ -0,0 +1,27 @@
+import React from "react";
+import WsJsepProtocol from "../net/ws_jsep_protocol_driver";
+export interface EmulatorWebrtcViewProps {
+    /** The JSEP protocol driver instance. */
+    jsep: WsJsepProtocol;
+    /** Callback for connection state changes ("connecting", "connected", "disconnected"). */
+    onStateChange?: (state: string) => void;
+    /** Callback when audio track status changes. */
+    onAudioStateChange?: (audio: boolean) => void;
+    /** Whether the audio should be muted. */
+    muted?: boolean;
+    /** Audio volume (between 0.0 and 1.0). */
+    volume?: number;
+    /** Callback invoked on signaling or playback errors. */
+    onError?: (error: Error) => void;
+    /** Component width. */
+    width?: number;
+    /** Component height. */
+    height?: number;
+}
+/**
+ * A React component that renders the WebRTC video stream of the emulator.
+ * Handles establishing the stream via the JSEP protocol driver and managing
+ * local playback (including handling autoplay constraints).
+ */
+declare const EmulatorWebrtcView: React.FC<EmulatorWebrtcViewProps>;
+export default EmulatorWebrtcView;

package/dist/src/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @fileoverview Main entry point for the android-emulator-webrtc package.
+ * Exports the primary Emulator React component and the EmulatorStatus utility.
+ */
+import Emulator from "./components/emulator/emulator";
+import EmulatorStatus from "./components/emulator/net/emulator_status";
+import logger from "./components/emulator/net/logger";
+export { Emulator, EmulatorStatus, logger };

package/dist/src/proto/emulator_controller_pb.d.ts

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,29 +1,23 @@
 {
   "name": "android-emulator-webrtc",
-  "version": "1.0.18",
+  "version": "2.0.1",
   "description": "Android Emulator WebRTC module",
+  "files": [
+    "dist",
+    "proto",
+    "README.md",
+    "LICENSE"
+  ],
   "scripts": {
-    "build": "babel src -d dist",
+    "build": "babel src -d dist && tsc",
     "test": "jest"
   },
-  "babel": {
-    "presets": [
-      "@babel/preset-env",
-      "@babel/preset-react"
-    ],
-    "plugins": [
-      "@babel/plugin-proposal-class-properties"
-    ]
-  },
   "jest": {
-    "verbose": true,
-    "transformIgnorePatterns": [
-      "/node_modules/@juggle/resize-observer/"
-    ]
+    "verbose": true
   },
   "dependencies": {
     "google-protobuf": "^3.21.2",
-    "grpc-web": "^1.4.2",
+    "loglevel": "^1.9.2",
     "prop-types": "^15.8.1"
   },
   "peerDependencies": {
@@ -37,23 +31,29 @@
     "@babel/plugin-transform-runtime": "^7.21.4",
     "@babel/preset-env": "^7.21.5",
     "@babel/preset-react": "^7.18.6",
+    "@babel/preset-typescript": "^7.29.7",
     "@testing-library/jest-dom": "^5.16.5",
     "@testing-library/react": "^14.0.0",
+    "@types/jest": "^30.0.0",
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
     "babel-core": "7.0.0-bridge.0",
     "babel-jest": "^29.5.0",
     "babel-loader": "^9.1.2",
     "babel-polyfill": "^6.26.0",
     "jest": "^29.5.0",
     "jest-environment-jsdom": "^29.5.0",
+    "protoc-gen-js": "^3.21.4-4",
     "react": "^18.2.0",
     "react-docgen-markdown-renderer": "^2.1.3",
     "react-dom": "^18.2.0",
     "resize-observer-polyfill": "^1.5.1",
+    "typescript": "^6.0.3",
     "yalc": "^1.0.0-pre.53"
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/google/android-emulator-webrtc.git"
+    "url": "git+https://github.com/pokowaka/android-emulator-webrtc.git"
   },
   "keywords": [
     "webrtc",