buutuu/scrcpy-over-webrtc repository overview

⁠ScrcpyOverWebRTC All-in-One Docker Image

English⁠ | 中文说明⁠

⁠🌐 English

ScrcpyOverWebRTC (buutuu/scrcpy-over-webrtc) is an out-of-the-box All-in-One (AIO) Docker image designed for managing Android devices and cloud phones via WebRTC directly in your web browser with ultra-low latency (30ms~50ms).

⁠📦 What is Included in this Image?

• Go Signaling Server (webrtc-signaling): Ultra-high concurrency WebSocket signaling negotiation and device registry.
• Web Console Dashboard (assets): Modern Vue 3 + WebCodecs hardware-accelerated management portal.
• Embedded coturn Media Relay: Built-in STUN/TURN server ensuring 100% connectivity across strict symmetric NATs and enterprise firewalls.
• Zero Server-Side Transcoding: Media streams P2P directly between Android devices and browser clients without consuming host server CPU/GPU resources.

⁠🚀 Key Features

• ⚡ Ultra-Low Latency: 30ms ~ 50ms end-to-end glass-to-glass delay using WebRTC UDP + Hardware PTS Passthrough.
• 🎮 Full-Featured Controls: Multi-touch gestures, keymapping (Joystick/WASD/Tap/Swipe), 100% Chinese/Unicode IME injection, and physical button emulation.
• 💻 WebADB & Terminal: Direct in-browser terminal debugging powered by xterm.js without installing ADB locally.
• 📁 P2P File Manager: Fast file browser, drag-and-drop file upload/download, and 1-click silent APK install.
• 📊 Fleet Monitoring & Group Control: Real-time multi-device preview grid, independent Canvas direct control, and batch command broadcast.
• 📱 Broad Device Compatibility: Android physical phones (USB/Wi-Fi/Root/Non-Root), Docker Redroid cloud phones, and PC emulators.
• 🏗️ Multi-Arch Native Support: Out-of-the-box support for both linux/amd64 and linux/arm64.

⁠⚡ Quick Start

⁠Method 1: Host Network Mode (Recommended)

Best performance with zero NAT overhead. Ideal for Linux hosts with direct IP access:

docker run -d \
  --pull=always \
  --restart=always \
  --name cp-aio \
  --net=host \
  -v ./data:/app/data \
  -e PUBLIC_IP=<YOUR_HOST_OR_PUBLIC_IP> \
  buutuu/scrcpy-over-webrtc:latest

Open your browser and navigate to: https://<YOUR_HOST_OR_PUBLIC_IP>:8443
(Default login: admin / admin123)

⁠Method 2: Bridge Port Mapping Mode (macOS / Windows / Strict Port Isolation)

For environments where --net=host is not supported. Limits UDP ports to prevent docker-proxy memory exhaust:

docker run -d \
  --pull=always \
  --restart=always \
  --name cp-aio \
  -p 8443:8443 \
  -p 3478:3478/tcp \
  -p 3478:3478/udp \
  -p 55000-55100:55000-55100/udp \
  -v ./data:/app/data \
  -e PUBLIC_IP=<YOUR_HOST_OR_PUBLIC_IP> \
  -e COTURN_MIN_PORT=55000 \
  -e COTURN_MAX_PORT=55100 \
  buutuu/scrcpy-over-webrtc:latest

⁠Method 3: Docker Compose

Create a docker-compose.yml:

version: "3.8"

services:
  cloudphone:
    image: buutuu/scrcpy-over-webrtc:latest
    container_name: cp-aio
    restart: always
    network_mode: host
    volumes:
      - ./data:/app/data
    environment:
      - PUBLIC_IP=${PUBLIC_IP:-127.0.0.1}
      - SIGNALING_PORT=8443
      - TURN_USER=cloudphone_user
      - TURN_PASSWORD=cloudphone_secure_password

Start the service:

docker compose up -d

⁠🔧 Environment Variables

⁠📱 Connecting Devices (Agent Setup)

After starting the server, connect target Android devices using any of the following methods:

1. WebUSB (Browser 1-Click): Open the Web UI, plug in your phone with USB debugging enabled, and click WebUSB Deploy.
2. PC Script Push: Download agent-deploy.zip from Web UI and run ./run.sh (Linux/Mac) or run.bat (Windows).
3. Magisk / Root Module: Flash the module for persistent boot auto-start and background daemon management.
4. Android App: Install the official App to run either as a Controller or a Host Agent (Root or Shizuku mode).
5. Docker Redroid Cloud Phones: Run redroid containers and inject the agent binary with matching UDP port mapping.

⁠📚 Official Resources

• 🌐 Official Website: https://webrtc-phone.com⁠
• 📖 Documentation: https://webrtc-phone.com/docs/⁠
• 💻 GitHub Repository: https://github.com/hqw700/ScrcpyOverWebRTC⁠
• 🎮 Online Live Demo: https://webrtc-phone.com/demo.html⁠

⁠🇨🇳 中文说明

穿云投屏 (ScrcpyOverWebRTC) 官方一体化 Docker 镜像（buutuu/scrcpy-over-webrtc）是一款面向企业级与开发者的低延迟 WebRTC 云手机与 Android 远程控制基础设施。无需在客户端电脑安装任何软件，通过任意现代浏览器即可实现 30ms 极速高清投屏与批量群控。

⁠📦 镜像内置核心组件

• Go 信令服务器 (webrtc-signaling)：高并发 WebSocket 信令协商路由、设备注册与大盘指标分发。
• Web 控制大盘 (assets)：基于 Vue 3 + WebCodecs 硬件显存直通硬解渲染的前端管理面板。
• 内置 coturn 媒体中继：开箱即用的 STUN/TURN 服务，保障在对称 NAT 与严格企业防火墙下 100% 穿透成功。
• 零服务端转码开销：媒体流在 Android 设备与浏览器之间点对点传输，宿主机不进行繁重的音视频二次编解码，单台服务器可纳管数十至上百台设备。

⁠🚀 核心功能全景

• ⚡ 极致超低延迟：WebRTC UDP + 硬件渲染时间戳直通（HW-PTS Passthrough），操作延迟低至 30ms ~ 50ms。
• 🎮 全场景交互控制：支持真机多点触控与手势缩放、全套按键映射（摇杆/单击/滑动）、100% 汉字落屏输入法、物理按键模拟与快捷键。
• 💻 免驱动 WebADB 终端：浏览器内置 xterm.js，无需安装 ADB 驱动直接在网页中执行 Android Shell 调试。
• 📁 P2P 文件管理器：基于 WebRTC DataChannel 的点对点文件中心，支持目录浏览、拖拽上传、大文件流控下载与 APK 静默安装。
• 📊 大盘监控与群控矩阵：高频二进制预览大盘、独立 Canvas 预览直控（免建 WebRTC 即可触控）、批量指令与批量文本广播。
• 📱 多形态设备纳管：统一纳管物理真机（USB/Wi-Fi/Root/免Root）、Docker Redroid 容器云手机、安卓模拟器。
• 🏗️ 多架构原生兼容：原生支持 linux/amd64 与 linux/arm64（Apple Silicon / 飞腾 / 鲲鹏 / 树莓派）。

⁠⚡ 极速部署指南

⁠1. 国内服务器加速配置 (强烈推荐)

国内服务器直接拉取 Docker Hub 镜像容易出现超时，建议先在宿主机配置镜像加速站：

sudo mkdir -p /etc/docker
sudo tee /etc/docker/daemon.json <<-'EOF'
{
  "registry-mirrors": ["https://docker.m.daocloud.io"]
}
EOF
sudo systemctl daemon-reload
sudo systemctl restart docker

⁠2. 方式一：Host 网络模式 (首选，性能最佳)

适用于有独立公网 IP 或局域网环境的 Linux 宿主机，零 NAT 损耗：

docker run -d \
  --pull=always \
  --restart=always \
  --name cp-aio \
  --net=host \
  -v ./data:/app/data \
  -e PUBLIC_IP=<您的宿主机真实IP或公网IP> \
  buutuu/scrcpy-over-webrtc:latest

打开浏览器访问：https://<您的服务器IP>:8443
(初始默认管理员账号：admin，密码：admin123)

⁠3. 方式二：Bridge 端口映射模式 (macOS / Windows / 严格端口策略)

若在 Docker Desktop 虚拟机运行或出于安全隔离策略必须使用 -p 映射端口，请收窄 UDP 端口段以防止系统内存 OOM 崩溃：

docker run -d \
  --pull=always \
  --restart=always \
  --name cp-aio \
  -p 8443:8443 \
  -p 3478:3478/tcp \
  -p 3478:3478/udp \
  -p 55000-55100:55000-55100/udp \
  -v ./data:/app/data \
  -e PUBLIC_IP=<您的宿主机真实IP> \
  -e COTURN_MIN_PORT=55000 \
  -e COTURN_MAX_PORT=55100 \
  buutuu/scrcpy-over-webrtc:latest

⁠4. 方式三：Docker Compose 一键部署

创建 docker-compose.yml 文件：

version: "3.8"

services:
  cloudphone:
    image: buutuu/scrcpy-over-webrtc:latest
    container_name: cp-aio
    restart: always
    network_mode: host
    volumes:
      - ./data:/app/data
    environment:
      - PUBLIC_IP=${PUBLIC_IP:-127.0.0.1}
      - SIGNALING_PORT=8443
      - TURN_USER=cloudphone_user
      - TURN_PASSWORD=cloudphone_secure_password

启动容器：

docker compose up -d

⁠🔧 容器环境变量说明

⁠📱 设备端 Agent 接入方式

服务启动后，Android 目标设备支持多种灵活方式接入：

1. 网页端 WebUSB 一键部署：使用 Chrome/Edge 浏览器打开管理大盘，数据线插上开启 USB 调试的手机，直接在网页内一键免驱动推送上线（小白首选）。
2. 电脑脚本一键接入：从大盘右上角下载 agent-deploy.zip，在 PC/Mac 终端运行 ./run.sh 或 run.bat，支持有线与局域网无线 ADB 并发推送。
3. Magisk / Root 模块开机自启：Root 真机刷入专用模块，实现开机守护自启、参数预设与无人值守机房长期纳管。
4. Android App 原生客户端：安装官方 App，支持手机免电脑作为被控端（Root 或 Shizuku 免 Root 模式）上线。
5. Docker Redroid 容器云手机：在服务器拉起 redroid 实例并通过容器内部执行或 ADB 映射将 Agent 注入运行。

⁠📖 官方文档与社区支持

• 🌐 项目官网：https://webrtc-phone.com⁠
• 📖 官方完整技术手册：https://webrtc-phone.com/docs/⁠
• 💻 GitHub 开源仓库：https://github.com/hqw700/ScrcpyOverWebRTC⁠
• 🎮 免部署 Demo 在线大盘：https://webrtc-phone.com/demo.html⁠