remote-phone 1.0.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 dpk
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,227 @@
1
+ Metadata-Version: 2.4
2
+ Name: remote-phone
3
+ Version: 1.0.0
4
+ Summary: Mirror and control your Android phone from your Linux desktop over WiFi
5
+ Author: dpk
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/dpk404/remote-phone
8
+ Project-URL: Repository, https://github.com/dpk404/remote-phone
9
+ Project-URL: Issues, https://github.com/dpk404/remote-phone/issues
10
+ Keywords: android,mirror,remote,phone,screen-sharing,wifi
11
+ Classifier: Development Status :: 4 - Beta
12
+ Classifier: Environment :: X11 Applications :: Qt
13
+ Classifier: Intended Audience :: End Users/Desktop
14
+ Classifier: Operating System :: POSIX :: Linux
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3.10
17
+ Classifier: Programming Language :: Python :: 3.11
18
+ Classifier: Programming Language :: Python :: 3.12
19
+ Classifier: Topic :: Communications
20
+ Classifier: Topic :: Multimedia :: Video :: Display
21
+ Classifier: Topic :: System :: Networking
22
+ Requires-Python: >=3.10
23
+ Description-Content-Type: text/markdown
24
+ License-File: LICENSE
25
+ Requires-Dist: PyQt6>=6.5
26
+ Requires-Dist: websocket-client>=1.6
27
+ Requires-Dist: av>=12.0
28
+ Requires-Dist: numpy>=1.24
29
+ Requires-Dist: sounddevice>=0.4
30
+ Dynamic: license-file
31
+
32
+ # RemotePhone
33
+
34
+ **Mirror and control your Android phone from your Linux desktop — no USB debugging required.**
35
+
36
+ RemotePhone is a two-part system: an Android app that captures and streams your phone's screen, and a Linux desktop client that displays the stream and lets you control the phone with your mouse and keyboard.
37
+
38
+ Unlike scrcpy (which requires ADB/USB debugging), RemotePhone works entirely over WiFi using standard Android APIs.
39
+
40
+ ---
41
+
42
+ ## Features
43
+
44
+ - **Native resolution** screen mirroring over WiFi
45
+ - **Full remote control** — tap, swipe, long press, scroll, system keys
46
+ - **Audio mirroring** with automatic phone speaker muting (Android 10+)
47
+ - **No USB debugging** — no ADB, no developer mode needed
48
+ - **Keyboard input** — type text directly into phone text fields, including PIN pad support
49
+ - **Low latency** — H.264 hardware encoding, CBR mode, direct frame routing, smart frame dropping
50
+ - **Auto-discovery** — scans local network and auto-connects to the phone
51
+ - **Auto-reconnect** — reconnects automatically on connection loss with exponential backoff
52
+ - **Wake on input** — wakes the phone screen when you interact from the desktop
53
+ - **Dark theme** — sleek UI on both phone and desktop
54
+
55
+ ## Architecture
56
+
57
+ ```
58
+ ┌─────────────────────┐ WebSocket (WiFi) ┌──────────────────────┐
59
+ │ Android Phone │ <------------------------------> │ Linux Desktop │
60
+ │ │ │ │
61
+ │ MediaProjection --> │ H.264 video frames ----------> │ PyAV decoder │
62
+ │ MediaCodec H.264 │ Raw PCM audio ---------------> │ sounddevice player │
63
+ │ AudioPlaybackCapt. │ <-- Touch/key JSON commands -- │ PyQt6 display │
64
+ │ AccessibilityServ. │ │ Mouse/keyboard │
65
+ └─────────────────────┘ └──────────────────────┘
66
+ ```
67
+
68
+ ---
69
+
70
+ ## Setup
71
+
72
+ ### 1. Android App
73
+
74
+ **Requirements:** Android 7.0+ (API 24). Audio mirroring requires Android 10+.
75
+
76
+ **Option A — Install pre-built APK:**
77
+
78
+ 1. Transfer `RemotePhone-debug.apk` to your phone and install it
79
+ 2. Open the app and tap **"Open Accessibility Settings"** -> find **RemotePhone** -> **Enable** it
80
+
81
+ **Option B — Build from source:**
82
+
83
+ 1. Open the `android/` folder in **Android Studio**
84
+ 2. Let Gradle sync and download dependencies
85
+ 3. Connect your phone (or use wireless install) and click **Run**
86
+ 4. Enable the accessibility service as above
87
+
88
+ ### 2. Linux Client
89
+
90
+ **Requirements:** Python 3.10+, FFmpeg libraries.
91
+
92
+ **Option A — Install via pip (recommended):**
93
+
94
+ ```bash
95
+ # Install system dependencies (Ubuntu/Debian)
96
+ sudo apt install ffmpeg libportaudio2
97
+
98
+ # Install RemotePhone
99
+ pip install remote-phone
100
+
101
+ # Run it
102
+ remotephone
103
+ ```
104
+
105
+ **Option B — Run from source:**
106
+
107
+ ```bash
108
+ # Install system dependencies (Ubuntu/Debian)
109
+ sudo apt install python3 python3-venv python3-pip libportaudio2 ffmpeg
110
+
111
+ # Run the client
112
+ cd remotephone
113
+ chmod +x run.sh
114
+ ./run.sh
115
+ ```
116
+
117
+ The launcher script automatically creates a virtual environment and installs Python dependencies.
118
+
119
+ ---
120
+
121
+ ## Usage
122
+
123
+ 1. **On your phone:** Open RemotePhone -> tap **"Start Mirroring"** -> grant the screen capture permission
124
+ 2. **On your laptop:** Run the Linux client — it auto-scans the network and connects if one phone is found
125
+ 3. If auto-connect doesn't work, enter the phone's IP (shown in the app) and click **Connect**
126
+
127
+ ### Controls
128
+
129
+ | Input | Action |
130
+ |-------|--------|
131
+ | Left click | Tap |
132
+ | Click + drag | Swipe |
133
+ | Hold click (> 0.5s) | Long press |
134
+ | Scroll wheel | Scroll |
135
+ | Horizontal scroll (2-finger trackpad) | Back gesture |
136
+ | Right click | Back |
137
+ | Middle click | Back |
138
+ | Escape | Back |
139
+ | Home key | Home |
140
+ | F2 | Recent apps |
141
+ | F5 | Notifications |
142
+ | F6 | Quick Settings |
143
+ | F10 | Lock screen |
144
+ | F11 | Fullscreen toggle |
145
+ | Any typing | Text input into focused field |
146
+ | Backspace | Delete character (or Back if no text field) |
147
+ | Delete | Delete forward |
148
+ | Ctrl+A / C / X / V | Select all / Copy / Cut / Paste |
149
+ | Enter | Confirm / IME action / PIN submit |
150
+
151
+ ### Keyboard and Text Input
152
+
153
+ When you tap a text field on the phone, you can type directly from your desktop keyboard. The text is inserted at the cursor position with full cursor-aware editing.
154
+
155
+ **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.
156
+
157
+ ### Audio
158
+
159
+ Toggle the **Audio** checkbox in the Linux client to stream phone audio to your laptop. 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.
160
+
161
+ Requires Android 10+ and `libportaudio2` on Linux.
162
+
163
+ ---
164
+
165
+ ## Protocol
166
+
167
+ Communication uses WebSocket on port **8765**.
168
+
169
+ - **Video:** H.264 NAL units with a 9-byte binary header (frame type, timestamp, size)
170
+ - **Audio:** Raw PCM (16-bit LE, 44100 Hz, stereo) with the same binary header
171
+ - **Control:** JSON text messages for tap, swipe, scroll, key actions, text input
172
+
173
+ ### Encoding Settings
174
+
175
+ | Setting | Value |
176
+ |---------|-------|
177
+ | Codec | H.264 (AVC) hardware-accelerated |
178
+ | Profile | Main |
179
+ | Bitrate | Adaptive (8 bits/pixel, 4-40 Mbps) |
180
+ | Frame rate | 30 FPS |
181
+ | Bitrate mode | CBR |
182
+ | Keyframe interval | 1 second |
183
+ | Low latency | Enabled (Android 11+) |
184
+
185
+ ---
186
+
187
+ ## Known Limitations
188
+
189
+ - **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).
190
+ - **Secure screens** (banking apps, DRM content) also display as black for the same reason.
191
+ - Both devices must be on the **same WiFi network**.
192
+ - Some device manufacturers may restrict the AccessibilityService or MediaProjection behavior.
193
+ - Text input uses `ACTION_SET_TEXT` which may not work in all apps (games, custom views).
194
+
195
+ ---
196
+
197
+ ## Project Structure
198
+
199
+ ```
200
+ remote_phone/
201
+ ├── android/ # Android app (Kotlin)
202
+ │ ├── app/src/main/java/com/remotephone/
203
+ │ │ ├── MainActivity.kt # UI + permission flow
204
+ │ │ ├── ScreenCaptureService.kt # MediaProjection + H.264 encoding
205
+ │ │ ├── RemoteAccessibilityService.kt # Gesture dispatch + text input
206
+ │ │ └── MirrorWebSocketServer.kt # WebSocket server + backpressure
207
+ │ └── app/src/main/res/ # Layouts, drawables, configs
208
+ │
209
+ ├── remotephone/ # Python desktop client (pip install remote-phone)
210
+ │ ├── main.py # Entry point
211
+ │ ├── ui/main_window.py # PyQt6 window + video display
212
+ │ ├── network/ws_client.py # WebSocket client + auto-reconnect
213
+ │ ├── network/scanner.py # Network auto-discovery
214
+ │ ├── decoder/video_decoder.py # H.264 decoding (PyAV/FFmpeg)
215
+ │ ├── decoder/audio_player.py # PCM audio playback
216
+ │ ├── input/input_handler.py # Mouse/keyboard + gesture detection
217
+ │ ├── requirements.txt
218
+ │ └── run.sh # Auto-setup launcher (for running from source)
219
+ │
220
+ ├── pyproject.toml # Python package config
221
+ ├── .github/workflows/ # CI/CD (APK build + PyPI publish)
222
+ └── README.md
223
+ ```
224
+
225
+ ## License
226
+
227
+ MIT
@@ -0,0 +1,196 @@
1
+ # RemotePhone
2
+
3
+ **Mirror and control your Android phone from your Linux desktop — no USB debugging required.**
4
+
5
+ RemotePhone is a two-part system: an Android app that captures and streams your phone's screen, and a Linux desktop client that displays the stream and lets you control the phone with your mouse and keyboard.
6
+
7
+ Unlike scrcpy (which requires ADB/USB debugging), RemotePhone works entirely over WiFi using standard Android APIs.
8
+
9
+ ---
10
+
11
+ ## Features
12
+
13
+ - **Native resolution** screen mirroring over WiFi
14
+ - **Full remote control** — tap, swipe, long press, scroll, system keys
15
+ - **Audio mirroring** with automatic phone speaker muting (Android 10+)
16
+ - **No USB debugging** — no ADB, no developer mode needed
17
+ - **Keyboard input** — type text directly into phone text fields, including PIN pad support
18
+ - **Low latency** — H.264 hardware encoding, CBR mode, direct frame routing, smart frame dropping
19
+ - **Auto-discovery** — scans local network and auto-connects to the phone
20
+ - **Auto-reconnect** — reconnects automatically on connection loss with exponential backoff
21
+ - **Wake on input** — wakes the phone screen when you interact from the desktop
22
+ - **Dark theme** — sleek UI on both phone and desktop
23
+
24
+ ## Architecture
25
+
26
+ ```
27
+ ┌─────────────────────┐ WebSocket (WiFi) ┌──────────────────────┐
28
+ │ Android Phone │ <------------------------------> │ Linux Desktop │
29
+ │ │ │ │
30
+ │ MediaProjection --> │ H.264 video frames ----------> │ PyAV decoder │
31
+ │ MediaCodec H.264 │ Raw PCM audio ---------------> │ sounddevice player │
32
+ │ AudioPlaybackCapt. │ <-- Touch/key JSON commands -- │ PyQt6 display │
33
+ │ AccessibilityServ. │ │ Mouse/keyboard │
34
+ └─────────────────────┘ └──────────────────────┘
35
+ ```
36
+
37
+ ---
38
+
39
+ ## Setup
40
+
41
+ ### 1. Android App
42
+
43
+ **Requirements:** Android 7.0+ (API 24). Audio mirroring requires Android 10+.
44
+
45
+ **Option A — Install pre-built APK:**
46
+
47
+ 1. Transfer `RemotePhone-debug.apk` to your phone and install it
48
+ 2. Open the app and tap **"Open Accessibility Settings"** -> find **RemotePhone** -> **Enable** it
49
+
50
+ **Option B — Build from source:**
51
+
52
+ 1. Open the `android/` folder in **Android Studio**
53
+ 2. Let Gradle sync and download dependencies
54
+ 3. Connect your phone (or use wireless install) and click **Run**
55
+ 4. Enable the accessibility service as above
56
+
57
+ ### 2. Linux Client
58
+
59
+ **Requirements:** Python 3.10+, FFmpeg libraries.
60
+
61
+ **Option A — Install via pip (recommended):**
62
+
63
+ ```bash
64
+ # Install system dependencies (Ubuntu/Debian)
65
+ sudo apt install ffmpeg libportaudio2
66
+
67
+ # Install RemotePhone
68
+ pip install remote-phone
69
+
70
+ # Run it
71
+ remotephone
72
+ ```
73
+
74
+ **Option B — Run from source:**
75
+
76
+ ```bash
77
+ # Install system dependencies (Ubuntu/Debian)
78
+ sudo apt install python3 python3-venv python3-pip libportaudio2 ffmpeg
79
+
80
+ # Run the client
81
+ cd remotephone
82
+ chmod +x run.sh
83
+ ./run.sh
84
+ ```
85
+
86
+ The launcher script automatically creates a virtual environment and installs Python dependencies.
87
+
88
+ ---
89
+
90
+ ## Usage
91
+
92
+ 1. **On your phone:** Open RemotePhone -> tap **"Start Mirroring"** -> grant the screen capture permission
93
+ 2. **On your laptop:** Run the Linux client — it auto-scans the network and connects if one phone is found
94
+ 3. If auto-connect doesn't work, enter the phone's IP (shown in the app) and click **Connect**
95
+
96
+ ### Controls
97
+
98
+ | Input | Action |
99
+ |-------|--------|
100
+ | Left click | Tap |
101
+ | Click + drag | Swipe |
102
+ | Hold click (> 0.5s) | Long press |
103
+ | Scroll wheel | Scroll |
104
+ | Horizontal scroll (2-finger trackpad) | Back gesture |
105
+ | Right click | Back |
106
+ | Middle click | Back |
107
+ | Escape | Back |
108
+ | Home key | Home |
109
+ | F2 | Recent apps |
110
+ | F5 | Notifications |
111
+ | F6 | Quick Settings |
112
+ | F10 | Lock screen |
113
+ | F11 | Fullscreen toggle |
114
+ | Any typing | Text input into focused field |
115
+ | Backspace | Delete character (or Back if no text field) |
116
+ | Delete | Delete forward |
117
+ | Ctrl+A / C / X / V | Select all / Copy / Cut / Paste |
118
+ | Enter | Confirm / IME action / PIN submit |
119
+
120
+ ### Keyboard and Text Input
121
+
122
+ When you tap a text field on the phone, you can type directly from your desktop keyboard. The text is inserted at the cursor position with full cursor-aware editing.
123
+
124
+ **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.
125
+
126
+ ### Audio
127
+
128
+ Toggle the **Audio** checkbox in the Linux client to stream phone audio to your laptop. 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.
129
+
130
+ Requires Android 10+ and `libportaudio2` on Linux.
131
+
132
+ ---
133
+
134
+ ## Protocol
135
+
136
+ Communication uses WebSocket on port **8765**.
137
+
138
+ - **Video:** H.264 NAL units with a 9-byte binary header (frame type, timestamp, size)
139
+ - **Audio:** Raw PCM (16-bit LE, 44100 Hz, stereo) with the same binary header
140
+ - **Control:** JSON text messages for tap, swipe, scroll, key actions, text input
141
+
142
+ ### Encoding Settings
143
+
144
+ | Setting | Value |
145
+ |---------|-------|
146
+ | Codec | H.264 (AVC) hardware-accelerated |
147
+ | Profile | Main |
148
+ | Bitrate | Adaptive (8 bits/pixel, 4-40 Mbps) |
149
+ | Frame rate | 30 FPS |
150
+ | Bitrate mode | CBR |
151
+ | Keyframe interval | 1 second |
152
+ | Low latency | Enabled (Android 11+) |
153
+
154
+ ---
155
+
156
+ ## Known Limitations
157
+
158
+ - **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).
159
+ - **Secure screens** (banking apps, DRM content) also display as black for the same reason.
160
+ - Both devices must be on the **same WiFi network**.
161
+ - Some device manufacturers may restrict the AccessibilityService or MediaProjection behavior.
162
+ - Text input uses `ACTION_SET_TEXT` which may not work in all apps (games, custom views).
163
+
164
+ ---
165
+
166
+ ## Project Structure
167
+
168
+ ```
169
+ remote_phone/
170
+ ├── android/ # Android app (Kotlin)
171
+ │ ├── app/src/main/java/com/remotephone/
172
+ │ │ ├── MainActivity.kt # UI + permission flow
173
+ │ │ ├── ScreenCaptureService.kt # MediaProjection + H.264 encoding
174
+ │ │ ├── RemoteAccessibilityService.kt # Gesture dispatch + text input
175
+ │ │ └── MirrorWebSocketServer.kt # WebSocket server + backpressure
176
+ │ └── app/src/main/res/ # Layouts, drawables, configs
177
+ │
178
+ ├── remotephone/ # Python desktop client (pip install remote-phone)
179
+ │ ├── main.py # Entry point
180
+ │ ├── ui/main_window.py # PyQt6 window + video display
181
+ │ ├── network/ws_client.py # WebSocket client + auto-reconnect
182
+ │ ├── network/scanner.py # Network auto-discovery
183
+ │ ├── decoder/video_decoder.py # H.264 decoding (PyAV/FFmpeg)
184
+ │ ├── decoder/audio_player.py # PCM audio playback
185
+ │ ├── input/input_handler.py # Mouse/keyboard + gesture detection
186
+ │ ├── requirements.txt
187
+ │ └── run.sh # Auto-setup launcher (for running from source)
188
+ │
189
+ ├── pyproject.toml # Python package config
190
+ ├── .github/workflows/ # CI/CD (APK build + PyPI publish)
191
+ └── README.md
192
+ ```
193
+
194
+ ## License
195
+
196
+ MIT
@@ -0,0 +1,45 @@
1
+ [build-system]
2
+ requires = ["setuptools>=68.0", "wheel"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "remote-phone"
7
+ version = "1.0.0"
8
+ description = "Mirror and control your Android phone from your Linux desktop over WiFi"
9
+ readme = "README.md"
10
+ license = "MIT"
11
+ authors = [{name = "dpk"}]
12
+ requires-python = ">=3.10"
13
+ keywords = ["android", "mirror", "remote", "phone", "screen-sharing", "wifi"]
14
+ classifiers = [
15
+ "Development Status :: 4 - Beta",
16
+ "Environment :: X11 Applications :: Qt",
17
+ "Intended Audience :: End Users/Desktop",
18
+ "Operating System :: POSIX :: Linux",
19
+ "Programming Language :: Python :: 3",
20
+ "Programming Language :: Python :: 3.10",
21
+ "Programming Language :: Python :: 3.11",
22
+ "Programming Language :: Python :: 3.12",
23
+ "Topic :: Communications",
24
+ "Topic :: Multimedia :: Video :: Display",
25
+ "Topic :: System :: Networking",
26
+ ]
27
+ dependencies = [
28
+ "PyQt6>=6.5",
29
+ "websocket-client>=1.6",
30
+ "av>=12.0",
31
+ "numpy>=1.24",
32
+ "sounddevice>=0.4",
33
+ ]
34
+
35
+ [project.urls]
36
+ Homepage = "https://github.com/dpk404/remote-phone"
37
+ Repository = "https://github.com/dpk404/remote-phone"
38
+ Issues = "https://github.com/dpk404/remote-phone/issues"
39
+
40
+ [project.scripts]
41
+ remotephone = "remotephone.main:main"
42
+
43
+ [tool.setuptools.packages.find]
44
+ where = ["."]
45
+ include = ["remotephone*"]