remote-phone 1.3.0

Mirror and control your Android phone from your desktop, no USB debugging required.

RemotePhone is a two-part system: an Android app that captures and streams your phone's screen, and a desktop client for Linux, macOS, and Windows that displays the stream and lets you control the phone with your mouse and keyboard.

Unlike scrcpy (which requires ADB/USB debugging), RemotePhone works entirely over WiFi using standard Android APIs.

Features

• Native resolution screen mirroring over WiFi
• Full remote control — tap, swipe, long press, scroll, system keys
• Audio mirroring with automatic phone speaker muting (Android 10+)
• No USB debugging — no ADB, no developer mode needed
• Keyboard input — type text directly into phone text fields, including PIN pad support
• Low latency — H.264 hardware encoding, CBR mode, direct frame routing, smart frame dropping
• Auto-discovery — scans local network and auto-connects to the phone
• Auto-reconnect — reconnects automatically on connection loss with exponential backoff
• Wake on input — wakes the phone screen when you interact from the desktop
• Dark theme — sleek UI on both phone and desktop

Architecture

┌──────────────────────┐         WebSocket (WiFi)         ┌──────────────────────┐
│    Android Phone     │ <------------------------------> │   Desktop Client     │
│                      │                                  │                      │
│  MediaProjection --> │  H.264 video frames ---------->  │  PyAV decoder        │
│  MediaCodec H.264    │  Raw PCM audio --------------->  │  sounddevice player  │
│  AudioPlaybackCapt.  │  <-- Touch/key JSON commands --  │  PyQt6 display       │
│  AccessibilityServ.  │                                  │  Mouse/keyboard      │
└──────────────────────┘                                  └──────────────────────┘

Setup

1. Android App

Requirements: Android 7.0+ (API 24). Audio mirroring requires Android 10+.

Option A — Install pre-built APK:

1. Download the latest APK from Releases and install it
2. Android 13+ only: Go to Settings -> Apps -> RemotePhone -> ⋮ menu -> "Allow restricted settings" (required for sideloaded apps to use accessibility)
3. Open the app and tap "Open Accessibility Settings" -> find RemotePhone -> Enable it

Option B — Build from source:

1. Open the android/ folder in Android Studio
2. Let Gradle sync and download dependencies
3. Connect your phone (or use wireless install) and click Run
4. Enable the accessibility service as above

2. Desktop Client (Linux, macOS, Windows)

Requirements: Python 3.10+. The pip wheels bundle FFmpeg on every platform and PortAudio on macOS and Windows. Linux needs the system PortAudio library for audio playback.

Option A: install via pip (recommended)

# Linux only (Debian/Ubuntu): PortAudio for audio playback
sudo apt install libportaudio2

# All platforms
pip install remote-phone
remotephone

Option B: run from source

# Linux only (Debian/Ubuntu). macOS and Windows just need Python 3.10+.
sudo apt install python3 python3-venv python3-pip libportaudio2

# Linux / macOS: extract the tarball (if downloaded from Releases), then run
chmod +x run.sh
./run.sh

# Windows
python -m venv venv
venv\Scripts\activate
pip install -e .
remotephone

The launcher script creates a virtual environment and installs the package into it.

Usage

1. On your phone: Open RemotePhone -> tap "Start Mirroring" -> grant the screen capture permission
2. On your computer: Run the desktop client. It auto-scans the network and connects if one phone is found
3. If auto-connect doesn't work, enter the phone's IP (shown in the app) and click Connect

Controls

Keyboard and Text Input

When you tap a text field on the phone, you can type directly from your desktop keyboard. On Android 13+ this goes through the real input pipeline automatically, works in every app including text fields inside web pages, and your normal on-screen keyboard stays selected. On Android 12 and older, enable and select the RemotePhone Keyboard (the app's Remote Typing Setup card opens the settings) for the same reliability; without it, typing falls back to accessibility text actions, which work in native text fields but are unreliable in browsers.

PIN/Password fields are handled specially — keyboard digits click the on-screen PIN pad buttons via the accessibility tree, and Enter searches for the confirm/OK button.

Audio

Toggle the Audio checkbox in the desktop client to stream phone audio to your computer. When enabled, the phone speakers are automatically muted so audio only plays on the desktop. Volume is restored when audio streaming is disabled or mirroring stops.

Requires Android 10+ and libportaudio2 on Linux.

Protocol

Communication uses WebSocket on port 8765.

• Video: H.264 NAL units with a 9-byte binary header (frame type, timestamp, size)
• Audio: Raw PCM (16-bit LE, 44100 Hz, stereo) with the same binary header
• Control: JSON text messages for tap, swipe, scroll, key actions, text input

Encoding Settings

Known Limitations

• Lock screen displays as black — this is an Android OS security restriction on MediaProjection. You can still type your PIN from the keyboard (digits click the PIN pad buttons).
• Secure screens (banking apps, DRM content) also display as black for the same reason.
• Both devices must be on the same WiFi network.
• Some device manufacturers may restrict the AccessibilityService or MediaProjection behavior.
• Text input uses ACTION_SET_TEXT which may not work in all apps (games, custom views).

Project Structure

remote_phone/
├── android/                    # Android app (Kotlin)
│   ├── app/src/main/java/com/remotephone/
│   │   ├── MainActivity.kt              # UI + permission flow
│   │   ├── ScreenCaptureService.kt       # MediaProjection + H.264 encoding
│   │   ├── RemoteAccessibilityService.kt # Gesture dispatch + text input
│   │   └── MirrorWebSocketServer.kt      # WebSocket server + backpressure
│   └── app/src/main/res/                 # Layouts, drawables, configs
│
├── remotephone/                # Python desktop client (pip install remote-phone)
│   ├── main.py                 # Entry point
│   ├── ui/main_window.py       # PyQt6 window + video display
│   ├── network/ws_client.py    # WebSocket client + auto-reconnect
│   ├── network/scanner.py      # Network auto-discovery
│   ├── decoder/video_decoder.py # H.264 decoding (PyAV/FFmpeg)
│   ├── decoder/audio_player.py  # PCM audio playback
│   └── input/input_handler.py   # Mouse/keyboard + gesture detection
│
├── run.sh                      # Auto-setup launcher for Linux/macOS (running from source)
├── pyproject.toml              # Python package config
├── .github/workflows/          # CI/CD (APK build + PyPI publish)
└── README.md

License

MIT