VMOS Edge Documentation

English

简体中文

English

简体中文

Appearance

Vmos Edge Web SDK ​

📖 Introduction ​

Vmos Edge Web SDK is a JavaScript/TypeScript SDK for remotely controlling Android devices in web browsers. It provides video stream rendering, touch event handling, key control, text input, and other features, allowing you to view and control Android devices in real-time on web pages.

⚠️ Note: The current version does not support audio stream transmission, only video stream and touch control are supported.

Key Features ​

  • ✅ Real-time Video Stream: Supports WebGL/Canvas 2D rendering with automatic performance optimization
  • ✅ Low-latency Control: Optimized touch event handling with multi-touch support
  • ✅ Device Control: Supports keys, text input, and clipboard synchronization
  • ✅ Group Control: Supports controlling multiple devices simultaneously
  • ✅ Event System: Comprehensive lifecycle and error handling events
  • ✅ TypeScript Support: Complete type definitions for excellent development experience

📦 Installation ​

bash
npm install @vmosedge/web-sdk
bash
pnpm add @vmosedge/web-sdk
bash
yarn add @vmosedge/web-sdk

⚠️ Important Limitations ​

🔴 Usage Environment Restrictions

The SDK currently only supports the following environments:

  • Local file protocol file://
  • localhost or 127.0.0.1

⚠️ HTTP and HTTPS protocols are not supported (except localhost)

The SDK currently only supports running under local file protocol (file://) or localhost environment. It's recommended to open HTML files directly using file:// protocol, or access through localhost on a local web server.

💡 Usage:

  • Method 1 (Recommended): Create an HTML file locally and open it directly in a browser (file:// protocol)
  • Method 2: Access through a local web server using localhost or 127.0.0.1
  • Ensure the device-side WebSocket service supports WS protocol connections
🌟 Recommended Solution: Use Desktop Application Frameworks

For better user experience and feature integration, we strongly recommend using the following desktop application frameworks in client applications:

  • Electron - Build cross-platform desktop apps with web technologies
  • Tauri - Build lightweight desktop apps with Rust and web frontend
  • Other desktop application frameworks that support WebView

Advantages:

  • ✅ Full control over the runtime environment, ensuring SDK works properly
  • ✅ Can integrate more native features (file system, system notifications, etc.)
  • ✅ Better performance and user experience
  • ✅ Can be packaged as standalone desktop applications
  • ✅ Avoid browser security policy restrictions

In these frameworks, the SDK can run normally as they provide a secure context environment similar to file:// or localhost.

🚀 Quick Start ​

Before using the SDK, it's recommended to detect whether the current environment supports it:

typescript
import { VmosEdgeClient } from "@vmosedge/web-sdk";

if (!VmosEdgeClient.isWebCodecsSupported()) {
  console.error("Current environment does not support SDK usage");
  console.error("Please open the HTML file using file:// protocol, or access through localhost");
  return;
}

// Environment supports SDK, can continue using it

Simple Usage Example ​

typescript
import { VmosEdgeClient, VmosEdgeClientEvents } from "@vmosedge/web-sdk";

// 0. Environment detection (recommended)
if (!VmosEdgeClient.isWebCodecsSupported()) {
  console.error("Current environment does not support SDK usage. Please open the HTML file using file:// protocol, or access through localhost");
  return;
}

// 1. Prepare a DOM container (for displaying device screen)
const container = document.getElementById("device-container");

// 2. Create client instance (LAN mode: network_mode === 'macvlan')
const client = new VmosEdgeClient({
  container: container!,
  config: {
    ip: "192.168.1.100",        // Use device's ip field
    deviceId: "EDGE418ASOC2LX9C",  // Use device's dbid field
    ports: {
      video: 9999,              // LAN mode fixed port
      touch: 9997,              // LAN mode fixed port
    },
  },
});

// 3. Listen for connection success event
client.on(VmosEdgeClientEvents.STARTED, () => {
  console.log("Device connected successfully!");
});

// 4. Start connection
client.start();
typescript
import { VmosEdgeClient, VmosEdgeClientEvents } from "@vmosedge/web-sdk";

// 0. Environment detection (recommended)
if (!VmosEdgeClient.isWebCodecsSupported()) {
  console.error("Current environment does not support SDK usage. Please open the HTML file using file:// protocol, or access through localhost");
  return;
}

// 1. Prepare a DOM container (for displaying device screen)
const container = document.getElementById("device-container");

// 2. Create client instance (Non-LAN mode)
const client = new VmosEdgeClient({
  container: container!,
  config: {
    ip: "example.com",          // Use device's hostip field
    deviceId: "EDGE418ASOC2LX9C",  // Use device's dbid field
    ports: {
      video: 22003,             // Use device's tcp_port field
      touch: 24003,             // Use device's tcp_control_port field
    },
  },
});

// 3. Listen for connection success event
client.on(VmosEdgeClientEvents.STARTED, () => {
  console.log("Device connected successfully!");
});

// 4. Start connection
client.start();

Configuration Guide ​

  • deviceId: Corresponds to the dbid field in device information
  • ip:
    • LAN mode (network_mode === 'macvlan'): Use device's ip field
    • Non-LAN mode: Use device's hostip field
  • ports.video:
    • LAN mode: Fixed to 9999
    • Non-LAN mode: Use device's tcp_port field
  • ports.touch:
    • LAN mode: Fixed to 9997
    • Non-LAN mode: Use device's tcp_control_port field

📚 Import/Export Guide ​

Complete Import List ​

The SDK provides the following exports, which you can selectively import as needed:

1. Core Class ​

typescript
import { VmosEdgeClient } from "@vmosedge/web-sdk";

// Use static method for environment detection
VmosEdgeClient.isWebCodecsSupported();

2. Configuration Types (TypeScript types for type checking) ​

typescript
import type {
  VmosEdgeClientConfig,           // Device connection configuration
  VmosEdgeClientOptions,           // Client initialization options
  VmosEdgeSizeChangedEvent,        // Size change event data
  VmosEdgeErrorEvent,              // Error event data
  VmosEdgeChannelConnectedEvent,   // Channel connection event data
  VmosEdgeClientEventMap,          // Event map (advanced usage)
  VmosEdgeClientEventListener,     // Event listener type (advanced usage)
  VmosEdgeClientEventName,         // Event name type (advanced usage)
  ChannelStatus,                   // Channel status type
  AllChannelsStatus,               // All channels status type
} from "@vmosedge/web-sdk";

Type Details:

3. Enums and Constants (runtime values) ​

typescript
import {
  VmosEdgeClientEvents,    // Event name enum
  VmosEdgeErrorCode,       // Error code enum
  VmosEdgeErrorType,       // Error type enum
} from "@vmosedge/web-sdk";

Enum Details:

4. Android Control Related Enums ​

typescript
import {
  AndroidKeyCode,              // Android key code enum
  AndroidKeyEventAction,       // Key action enum (press/release)
  AndroidMotionEventAction,    // Touch action enum
  AndroidMotionEventButton,    // Touch button enum
  AndroidMetaState,            // Meta key state enum (Shift/Ctrl/Alt etc.)
} from "@vmosedge/web-sdk";

Enum Details:

Common Import Combinations ​

typescript
import {
  VmosEdgeClient,
  VmosEdgeClientEvents,
  type VmosEdgeClientConfig,
  type VmosEdgeErrorEvent,
} from "@vmosedge/web-sdk";

Full Import (for all features) ​

typescript
import {
  VmosEdgeClient,
  VmosEdgeClientEvents,
  VmosEdgeErrorCode,
  VmosEdgeErrorType,
  AndroidKeyCode,
  AndroidKeyEventAction,
  type VmosEdgeClientConfig,
  type VmosEdgeClientOptions,
  type VmosEdgeErrorEvent,
  type VmosEdgeSizeChangedEvent,
} from "@vmosedge/web-sdk";

📖 Documentation Navigation ​

Powered by VMOS Edge Team

© 2026 VMOS Edge