English Version | 中文版本

High-performance Rust implementation of the Apple TV Companion Link and MediaRemote (MRP) protocols. Discover, pair, and control targets directly using the native Apple TV Remote widget in iOS / iPadOS Control Center without jailbreak or dedicated hardware:

1. macOS (Mac mini / MacBook / iMac):
   • Native Swift menu bar app (AppleTVRemote.app) and cross-platform CLI.
   • Ultra-smooth adaptive dynamic acceleration mouse cursor and D-pad dual-mode seamless switching, with native hardware media key and volume control integration.
   • Built-in Web Inspector and Swift Host Diagnostics dashboards, delivering real-time visualization of touchpad gestures, hardware volume levels, and millisecond-level protocol events.
2. Android TV / Google TV / TV Boxes / Emulators:
   • Native Standalone APK: Driven by JNI + embedded ADB (dadb) + Android Accessibility Service (AtvAccessibilityService), auto-starts on boot with independent mDNS broadcasting.
   • Remote Network ADB Mode: Run the daemon on a Mac mini or PC, forwarding remote keys and swipes over TCP ADB in real time.

• I. Live Interfaces & Real-World Showcase
  • 1. macOS & iOS Interactive Interfaces
    • ① iOS Remote Directly Controlling macOS
    • ② macOS Web Inspector (Port 8765)
    • ③ macOS Swift Host Diagnostics & Runtime Logs (Port 8766)
    • ④ macOS Native Menu Bar App & Key Features
  • 2. Android TV Interfaces & Remote Navigation
    • ① Control Dashboard & Configuration Dialogs
    • ② Android TV Launcher Gesture & Focus Movement
• II. Prerequisites & Permissions Checklist (Essential)
  • 1. macOS Prerequisites & Gatekeeper Clearance
  • 2. Android TV Prerequisites & Critical Permissions
  • 3. LAN & Network Pairing Requirements
• III. Quick Start & Operational Guides
  • 1. Running on macOS
  • 2. Running on Android TV
  • 3. Android Emulator Bridge Setup
• IV. Implementation Principles & Architecture
  • 1. Touchpad Gestures & Focus Accumulation Algorithm
  • 2. Emulator Bridge Architecture & mDNS Topology
  • 3. Driver Dispatch Hierarchy & Security Sandboxing
• V. Key & Gesture Mapping Reference
• VI. Troubleshooting & FAQ

No third-party iOS app required. Simply pull down the iOS Control Center and tap the native Apple TV Remote icon to immediately discover the host Mac (as shown below, connected directly to Yuhao's MacBook (2)):

• Full Touch Surface Support: The expansive touch area supports micro-pixel dragging, rapid swipes, tap-to-select, and edge gestures.
• Hardware Controls & Direct Feedback:
  • Play / Pause (⏯): Natively linked with macOS system-wide media playback.
  • Back Chevron (<): Mapped to macOS Escape key.
  • TV Icon (TV): Triggers configurable desktop actions or Mission Control.
  • Hardware Volume & Mute: The iPhone's physical volume rocker triggers macOS hardware volume with native HUD feedback.
  • Siri / Mic Key: Instantly toggles between Dynamic Mouse Cursor and D-pad modes.

When running the daemon or menu bar app on macOS, visit http://127.0.0.1:8765 in your browser to open the interactive inspection console (captured live with active finger swipe vectors and event logs):

• Real-time Touch Vector Canvas: High-frequency rendering of finger coordinates, gesture lifecycle phases (Began, Moved, Ended), velocity vectors, and direction detection.
• Interactive Virtual Remote: Click virtual buttons directly on the web page to test Mac or TV responses without holding a phone.
• Ballistics & Sensitivity Presets: Instant switching between 0.5x Precise, 1.0x Standard, 1.5x Fast, and 2.2x Ultra-Wide Screen dynamics profiles.
• Connected Device & Volume Telemetry: Displays connected remote device metadata and live volume feedback.

Navigate to http://127.0.0.1:8766 to inspect the Swift host process health, active port bindings, and live protocol handshakes:

• Real-time Session Tracing: Live stream of Companion client connections (e.g., iPhone at 192.168.101.206), SRP authentication, and MRP encrypted control channel initialization.
• Process Telemetry: Live indicators for Core API port (8765), Web Debug port (8766), MediaRemote port (49152), background PID, text search filter, and process restart controls.

Running AppleTVRemote.app places a lightweight native Swift icon in the macOS menu bar, consuming as little as 18MB of RAM:

• Cursor & D-Pad Hot Switching:
  • Mouse Cursor Mode: Ergonomic non-linear acceleration curve for pinpoint precision and rapid multi-monitor travel.
  • D-Pad Directional Mode: Dispatches arrow keys ↑ ↓ ← → and Enter.
  • Mode Toggle: Press the remote's Siri button or click on the Web Inspector—macOS displays an instant native notification banner!
• Deep Media Key Integration:
  • Single Click ⏯: Play / Pause (native NX_KEYTYPE_PLAY for YouTube, Safari, Spotify, IINA, etc.).
  • Double Click ⏯: Next Track (⏭).
  • Triple Click ⏯: Previous Track (⏮).
  • Volume Up / Down / Mute: Directly controls system master output volume with the native macOS HUD.

Launch the app on Android TV to monitor driver status and customize key bindings:

Main Dashboard	Input Injection Mode	Menu Key Binding

• Triple-Channel Driver Health: Real-time status indicators for /dev/input/event* hardware drivers, local Dadb daemon (127.0.0.1:5555), and AtvAccessibilityService.
• Input Injection Strategy: Select between Local ADB Only, Accessibility Service Only, ADB Preferred (Fallback to Accessibility), or Hardware Preferred.
• Menu Key Rebinding: Remap Play/Pause, Home, or Mute to the Android system KEYCODE_MENU for legacy TV apps.

Swiping on the iPhone touchpad smoothly shifts the TV focus highlight across the UI grid:

[Top Navigation Tabs (For you / Apps)]
              ↕ (Swipe Down)
[Featured Hero Banner Focus]
              ↕ (Swipe Down)
[Application Row (YouTube / VLC / Settings)]

1. Top Navigation Focus	2. Hero Banner Focus	3. App Card Row Focus

• Tap or Click Center SELECT: Open the selected card or stream immediately.
• Back Chevron <: Return to previous screen (GLOBAL_ACTION_BACK).
• TV Icon Home: Instantly return to the Android TV launcher home screen.

Review the following system requirements before initial launch:

Release builds are signed with a dedicated developer certificate (Corvo Development). On macOS, Gatekeeper may flag untrusted apps:

• Option A (Recommended): Import the certificate into system Keychain:

  ./scripts/import_certificate.sh Corvo_Development.p12

• Option B (Quick Bypass): Strip the quarantine attribute:

  xattr -dr com.apple.quarantine /Applications/AppleTVRemote.app

  (Or right-click the app in Finder while holding Control, select Open, and confirm.)

Simulating keyboard strokes and smooth mouse cursor movements requires macOS Accessibility permissions:

1. Navigate to System Settings -> Privacy & Security -> Accessibility.
2. Enable AppleTVRemote (or your terminal application like Terminal / iTerm if running via CLI).

• Why is ADB required?
  • Android security policies prevent regular apps from injecting global D-Pad and Select keys across third-party streaming apps.
  • Embedded Dadb connects directly to 127.0.0.1:5555 to dispatch Linux keycodes with <8ms ultra-low latency.
• Setup Steps:
  1. Open TV Settings -> About.
  2. Click Build Number 7 times until developer mode is unlocked.
  3. Return to Settings -> System -> Developer Options.
  4. Enable USB Debugging and Network Debugging.

When the app initializes the local Dadb connection, an Android system security prompt will appear:

⚠️ CRITICAL: Using your physical TV remote, check "Always allow from this computer" and click "Allow / OK". Rejecting this prompt will cause Unauthorized connection errors and prevent remote input.

• Purpose: Serves as a fallback input channel and handles system-level global actions (GLOBAL_ACTION_BACK, GLOBAL_ACTION_HOME).
• Setup Steps:
  1. Click ACCESSIBILITY SETTINGS on the main dashboard.
  2. Locate Apple TV Remote Receiver (shows "Off" by default).
  3. Turn it On and confirm in the system permission dialog.

Step 1: Accessibility List	Step 2: Confirmation Dialog	Step 3: Service Ready

1. Same Wi-Fi Subnet: The iPhone and TV / Mac must share the same local router subnet (2.4G and 5G bands are compatible).
2. Disable AP Isolation: Commercial routers with "AP Isolation" or "Guest Mode" block UDP 5353 Bonjour multicast packets. Ensure client-to-client communication is permitted.
3. Initial Pairing PIN: When connecting from the iPhone Control Center, enter the default PIN 1111 to complete the SRP cryptographic handshake.

# Build standalone DMG package
./scripts/build_dmg.sh

Mount build/AppleTVRemote-arm64.dmg and drag the application to /Applications. Launch the app and access controls via the menu bar icon.

# Build and install APK
./scripts/build_android.sh
adb install -r android-tv/app/build/outputs/apk/debug/app-debug.apk

# Launch app
adb shell am start -n com.corvofeng.fakeatv/.MainActivity

For testing inside Android Studio's Android TV Virtual Devices (AVD):

Start an Android TV AVD (API 30+ recommended). Run adb devices to verify emulator-5554 is online.

./scripts/build_android.sh
adb -s emulator-5554 install -r android-tv/app/build/outputs/apk/debug/app-debug.apk
adb -s emulator-5554 shell am start -n com.corvofeng.fakeatv/.MainActivity

# Start background daemon
python3 scripts/bridge_emulator.py start

# Or run foreground with live logs
python3 scripts/bridge_emulator.py start -f

• Useful management commands:

  python3 scripts/bridge_emulator.py status    # Check port forwarding & mDNS state
  python3 scripts/bridge_emulator.py logs -f   # Tail bridge logs
  python3 scripts/bridge_emulator.py stop      # Stop bridge daemon

1. Connect iPhone to the same Wi-Fi as your Mac.
2. Open iOS Control Center -> Apple TV Remote.
3. Select Android TV Emulator.
4. Enter default PIN 1111 to start controlling the emulator!

When swiping on the iPhone touchpad, the Companion Link protocol streams high-frequency differential delta coordinates. atv-core converts these inputs into smooth grid focus shifts on Android TV and ergonomic cursor acceleration on macOS:

1. Delta Accumulator: Aggregates continuous micro-displacements to prevent jitter and accidental touches.
2. Direction Deadzone & Thresholds: Determines primary intent (horizontal vs. vertical) while filtering diagonal noise.
3. Platform Dispatch:
   • Android TV: Emits KEYCODE_DPAD_UP/DOWN/LEFT/RIGHT focus events.
   • macOS: Computes velocity-based ballistics curves and emits smooth cursor motion via CGEvent.

Because the Android emulator runs within an isolated host NAT subnet (fixed virtual IP 10.0.2.15), local physical devices cannot discover it directly:

1. ADB Port Forwarding: Ports 49152, 49153, and 49154 are forwarded directly into the emulator guest OS via adb forward.
2. mDNS Host Proxy: The host proxies Bonjour records (_mediaremotetv._tcp and _companion-link._tcp) onto the physical Wi-Fi network.
3. Transparent Connection: The iPhone connects directly to the host's LAN IP, seamlessly routed to the emulator.

atv-core uses a layered driver strategy to ensure lowest possible latency and dependable fallback:

• Android Dispatch:
  • Primary (Dadb): Local loopback to 127.0.0.1:5555 for direct Linux input keycode dispatch (<8ms latency).
  • Fallback (Accessibility): Handles global window events (GLOBAL_ACTION_BACK, GLOBAL_ACTION_HOME).
• macOS Dispatch:
  • Accessibility API (CGEvent): Drives mouse motion, ballistics acceleration, and system-level keystrokes.
  • CoreAudio / MediaRemote Framework: Direct hardware master volume and media HUD control.

1. Ensure both iPhone and target device are on the exact same Wi-Fi subnet (disable router AP Isolation / Guest Mode).
2. On macOS, run dns-sd -B _mediaremotetv._tcp to verify local Bonjour advertisement.
3. For Android emulator, verify the bridge is running via python3 scripts/bridge_emulator.py status.

1. Open TV Developer Options and verify both "Network ADB" and "USB Debugging" are enabled.
2. Relaunch the app and look for the system RSA key dialog on screen. Check "Always allow" and click "Allow".
3. If no prompt appears, execute adb connect <TV_IP>:5555 from your computer to trigger initial trust.

Certain customized Android TV skins hide standard accessibility menus. Click the "ACCESSIBILITY SETTINGS" dialog in the app to view terminal activation commands, or run:

adb shell settings put secure enabled_accessibility_services com.corvofeng.fakeatv/.AtvAccessibilityService
adb shell settings put secure accessibility_enabled 1

Strip the Gatekeeper quarantine attribute:

xattr -dr com.apple.quarantine /Applications/AppleTVRemote.app

Or import the repository self-signed certificate:

./scripts/import_certificate.sh Corvo_Development.p12

This project is licensed under the MIT License. Intended for educational and local device interoperability research.