FrameScope

中文说明 · English

Rootless Android performance overlay featuring live FPS metering, thermal diagnostics, and privileged gaming optimization via the built-in FrameScope Bridge.

Fork note: FrameScope is a derivative of the MIT-licensed FrameX-Android. This fork renames the application and adds an Android 8.1-compatible foreground-layer FPS reader based on SurfaceFlinger --latency.

---

Note

Gaming Performance Mode is optimized specifically for Android 16 and Vivo OriginOS/FuntouchOS devices (featuring hardware Mode 4 1080p @ 120Hz lock and 4 OEM Whitelists engine). For Vivo devices, enable Vivo T3 Ultra Hardware Optimizations in Settings (About) to unlock maximum gaming performance. Behavior on other Android skins may vary.

Important

Encountering "Parse Failed" or "Unsupported Hardware"?

If thermal monitoring displays "Parse Failed" or "Unsupported Hardware" on your device:

1. Clone the repository and install the Debug APK (./gradlew installDebug). (Release builds strip diagnostic logs via ProGuard).
2. Open the Thermal Diagnostics screen in FrameScope.
3. Run the following ADB commands to capture complete diagnostics:

   # 1. Capture FrameScope internal thermal logs
   adb logcat -d | grep -E "ThermalMonitor|CmdRunner"
   
   # 2. Capture raw system thermal HAL dump
   adb shell dumpsys thermalservice
   
   # 3. Capture sysfs thermal zones (if dumpsys is empty/HAL Ready: false)
   adb shell "for z in /sys/class/thermal/thermal_zone*; do echo \"\$(cat \$z/type 2>/dev/null):\$(cat \$z/temp 2>/dev/null)\"; done"

   (On Windows PowerShell for Step 1: adb logcat -d | Select-String -Pattern "ThermalMonitor|CmdRunner")
4. Open a GitHub Issue attaching the outputs above along with your device model, SoC, and Android/ROM version.

---

What it does

FrameScope displays a fully customizable, low-overhead overlay on top of any application or full-screen title.

Category	Telemetry & Features
Real-Time Telemetry	FPS · CPU Frequencies · Thermals (CPU/GPU/Skin/NPU/Battery) · RAM Usage · Network Speed · Ping
System Optimization	• Crash-Safe Snapshots: Automatic pre-game setting capture & auto-revert on exit • Process Management: Background app suspension & Doze CPU whitelisting • Emergency Safety: One-swipe reset slider to purge overrides back to stock OS defaults
OEM Hardware Locks	• Vivo OriginOS Engine: Forces hardware Mode 4 ($1080 \times 2400$ @ 120Hz) lock • Triple Whitelisting: Automatic injection across 4 native OriginOS game-booster daemons

---

Requirements

• Android 8.0 (API 26) or higher
• English and Simplified Chinese in-app UI; the initial language follows the system language and can be changed in About & Legal → Language
• Basic monitoring works without the bridge after granting the draw-over-other-apps permission
• External-app FPS access, Gaming Mode, and deep optimization require the built-in FrameScope Bridge or optional Shizuku
• The Bridge is started once through USB ADB; no computer connection is needed while it remains alive
• Works with the Sui module on rooted devices as an alternative backend

Basic Monitoring vs. Deep Optimization

FrameScope separates its features into two levels:

• Basic monitoring: works without a privileged backend and provides CPU, RAM, storage, Ping, basic thermal status, and the overlay.
• Deep optimization: uses the FrameScope Bridge (or Shizuku fallback) for external-app SurfaceFlinger FPS access, Gaming Mode, background package suspension, refresh-rate locking, fixed performance mode, and Vivo hardware optimization.

FrameScope still opens normally without the Bridge. Detailed multi-sensor temperatures, external-app FPS access, and privileged system changes remain unavailable until the Bridge or Shizuku is running.

FrameScope Bridge setup (recommended)

The Bridge is already inside the FrameScope APK. It is not a second app and does not require Shizuku. Because Android cannot let a normal app raise its own UID to shell, the Bridge must be started once by ADB.

1. Install FrameScope

adb -s <device-serial> install -r <path-to-FrameScope.apk>

2. Start the embedded Bridge

The easiest way is to double-click 启动FrameScope桥接服务.bat in the repository root. It automatically selects the only connected ADB watch; if multiple devices are connected, it asks for the watch serial number.

To stop the service, double-click 停止FrameScope桥接服务.bat.

If Windows blocks the batch file, you can run the underlying PowerShell script manually from the repository root:

From the repository root in PowerShell:

Set-ExecutionPolicy -Scope Process Bypass
.\scripts\start-framescope-bridge.ps1 -Serial <device-serial>

The same command is available in the app under Permissions → Copy ADB Command. Open FrameScope and confirm that FrameScope Bridge shows RUNNING (SHELL). The computer can now be disconnected; the app talks to the Bridge through a local shared-storage mailbox.

3. After reboot

Run the start script again. Reinstalling FrameScope or installing Shizuku is not necessary. The click-to-run launchers are in the repository root, and the underlying PowerShell scripts are in scripts/. All of these files are included in the GitHub repository. See scripts/README-Bridge.md for troubleshooting.

Optional Shizuku fallback

Shizuku is still supported for users who already have it installed. Start Shizuku normally, grant FrameScope access, and FrameScope will use it when the embedded Bridge is unavailable.

---

Screenshots

Onboarding 1	Onboarding 2	Dashboard (No Setup)	Dashboard (Running)	System Setup
Overlay Config	Appearance Settings	Performance Mode	Thermal Diagnostics	About & Legal

---

How FPS is measured

FrameScope measures frame events from the Android rendering pipeline using privileged IPC calls. It probes SurfaceFlinger --latency at runtime and accepts only layers whose names prove that they belong to the focused Activity; timestamps from multiple surfaces of that same Activity are mapped to the display periods reported by SurfaceFlinger so duplicate events in one physical display slot count once. The live FPS uses a 500 ms rolling measurement window, so it responds faster than a one-second window while naturally fluctuating more over short windows. No artificial FPS ceiling is applied. When measuring FrameScope itself and SurfaceFlinger exposes no valid history, it may use Android 8.1-compatible Window.OnFrameMetricsAvailableListener data for diagnostics, but completed-window frames are not presented as displayed FPS; listener records dropped by Android are not synthesized. For external apps, a ROM that exposes no valid presentation timestamps can use dumpsys gfxinfo <foreground-package> framestats only for diagnostics when that dump provides a matching Window: section. Package-wide gfxinfo data is rejected for the live current-page value.

The live value identifies both source and scope: SF means SurfaceFlinger presentation events for the current Activity's layers; APP-W means observed completed frames from the current Activity window and is diagnostic-only; APP-P is retained only as a diagnostic/parser label for package-wide data and is never shown as the current-page FPS. Display-period mapping removes duplicate events from the same physical slot; it does not clamp the resulting FPS. If the backend cannot prove the current page's scope, the overlay shows FPS unavailable instead of presenting another window's/rendering pipeline events as the answer. No software-only Android API can guarantee a physical panel scanout measurement on every ROM.

---

Build

Standard Android Gradle project. Requires JDK 17 and Android SDK 34.

git clone https://github.com/superj0107/FrameScope.git
cd FrameScope-Android
./gradlew assembleDebug

Download the tested APK

The repository includes the debug APK tested on an Android 8.1 watch:

• FrameScope_v0.1.0-debug.apk
• Package: com.framescope.app
• Minimum Android version: Android 8.0 (API 26)
• The basic overlay can start with the draw-over-other-apps permission; external-app FPS readings require FrameScope Bridge or Shizuku.

---

Permissions

Permission	Why
Draw over other apps	Display the overlay on top of games
Foreground service	Keep the overlay alive while the screen is on
Wake lock	Prevent CPU sleep during an active session
PACKAGE_USAGE_STATS	Identify which game is in the foreground
REQUEST_IGNORE_BATTERY_OPTIMIZATIONS	Survive aggressive OEM background-kill policies
Receive boot completed	Auto-restart overlay after reboot if it was active
Internet	Ping measurement to 8.8.8.8 (Google Public DNS) only
Kill background processes	Used to purge cached background apps during Gaming Mode activation
Access notification policy	Required to toggle Do Not Disturb mode automatically
Modify system settings	Required to deploy per-game brightness, volume, and rotation overrides
Foreground service (Special Use)	Ensures Gaming Mode stays active on Android 14+
Post Notifications (Android 13+)	Display session status & quick-control notification controls
QUERY_ALL_PACKAGES	Load installed games and apps for Game Launcher optimization
FrameScope Bridge / Shizuku	High-precision FPS metering (SurfaceFlinger), multi-sensor thermal diagnostics, ART RAM heap compaction, and OriginOS Esports hardware engine

---

Security & Privacy

• No data collection — nothing is sent anywhere
• No analytics — no Firebase, no Crashlytics, no tracking SDKs
• No accounts — FrameScope has no sign-in or user identity
• No ads — ever
• All data stays on-device

Full Privacy Policy

---

Known Limitations

A small number of metrics depend on data some device vendors don't expose. See KNOWN_LIMITATIONS.md for confirmed cases and affected devices.

---

Credits

• Shizuku by RikkaW — optional compatibility backend for privileged system access.

---

License

This project is licensed under the MIT License - see the LICENSE file for details.