Xposed Modules

Punch-hole Download Progress

English | 简体中文

Xposed module that renders download progress as an animated ring around the camera cutout.

Android CI Kotlin Android

Download progress animation

Features

  • Progress ring around the camera cutout (via native DisplayCutout API) with per-state color, thickness, opacity, and direction (active/completed/failed)
  • Completion animations with optional haptic feedback
  • Download counter badge
  • Per-rotation calibration for text and badge offsets
  • Material 3 Expressive settings UI
  • Test mode, battery saver rendering, and pill-cutout path support

Requirements

  • Android 9+ (API 28)
  • Xposed Manager with API 101 support (official LSPosed recommended)
  • Root optional (only needed for Restart SystemUI)

Installation

  1. Download the APK:

    Get it on F-Droid Get it on IzzyOnDroid Get it on GitHub Get it on Obtainium

  2. Install and enable the module in LSPosed.

  3. Scope to com.android.systemui

  4. Restart SystemUI or reboot the device

The app includes a built-in Restart SystemUI option in the overflow menu. Magisk will prompt for permission; KernelSU/APatch require adding the app manually.

Build

git clone https://github.com/hxreborn/punch-hole-download-progress.git
cd punch-hole-download-progress
./gradlew assembleRelease

Requires JDK 21 and Android SDK. Configure local.properties:

sdk.dir=/path/to/android/sdk

# Optional signing
RELEASE_STORE_FILE=<path/to/keystore.jks>
RELEASE_STORE_PASSWORD=<store_password>
RELEASE_KEY_ALIAS=<key_alias>
RELEASE_KEY_PASSWORD=<key_password>

Contributing

Pull requests welcome. Open an issue for bugs or feature requests.

Also found in

License

GPLv3

This project is licensed under the GNU General Public License v3.0. See LICENSE for details.

Releases

v2.7.0

Stable

8/14/2026, 11:38:15 AM

What's Changed

Features

Bug Fixes

  • b600db7 (ui) Keep the snackbar above the nav bar when it hides on scroll by @hxreborn

  • ec9c415 (ui) Round snackbar corners to match the settings rows by @hxreborn

Refactor

Dependencies

Assets

1

v2.6.0

Stable

7/16/2026, 6:41:34 AM

What's Changed

Features

Bug Fixes

Refactor

Dependencies

Assets

1

v2.5.0

Stable

6/24/2026, 6:25:50 PM

What's Changed

Features

Bug Fixes

Refactor

Assets

1

v2.4.0

Stable

6/10/2026, 6:26:10 AM

What's Changed

Features

Bug Fixes

Performance Improvements

Refactor

Assets

1

v2.3.2

Stable

6/1/2026, 2:52:13 PM

What's Changed

Bug Fixes

Performance Improvements

Assets

1

v2.3.1

Stable

5/29/2026, 6:55:34 AM

What's Changed

Bug Fixes

  • e04ad9a (prefs) Avoid EmptySet crash when clearing package selection by @hxreborn

Performance Improvements

  • 27e08b2 (ui) Skip recomposing unchanged rows in package selection by @hxreborn

  • 6ac2198 (ui) Parallelize app loading and cache icons in package selection by @hxreborn

Refactor

  • c0bb279 (hook) Simplify download callbacks and notification id lookup by @hxreborn

CI/CD

Assets

1

v2.3.0

Stable

5/5/2026, 4:36:20 AM

What's Changed

Features

Bug Fixes

  • d4e23ab (hook) Use calibrated pivot for pop animation and add Chinese language support by @nymanyim in #79

Refactor

CI/CD

Miscellaneous

Assets

1

v2.2.0

Stable

4/25/2026, 7:31:41 PM

What's Changed

Added

Fixed

Performance Improvements

  • 5f06bea - (hook) Drop lambda allocations in label position branches by @hxreborn

Changed

Other

Assets

1

v2.0.0

Stable

3/18/2026, 6:19:36 PM

What's Changed

Added

  • 77d1215 - Migrate to libxposed API 101 [breaking] by @hxreborn in #53

    Migrates from libxposed API 100 to 101. API 100 will no longer be supported once 101 is officially released. An LSPosed Manager with API 101 support may not be publicly available yet.

Fixed

Other

Assets

1

v1.10.0

Stable

3/5/2026, 6:39:08 PM

What's Changed

Added

  • 2868dfc - Add Material You color mapping screen by @hxreborn

    Adds palette+shade picker for progress, completion, and error colors from Android 12+ system palette resources.

  • 3c52d84 - Add configurable segment count and gap by @hxreborn

    Expose segment count and gap degree settings in the Behavior screen when completion style is set to segmented

  • 728ed00 - Add glow effect toggle by @hxreborn

    Add glow effect preferences to the Background Ring section

Fixed

  • 7d28248 - (ci) Prevent tag push race condition in release workflow by @hxreborn

  • c933897 - (prefs) Remove edit call on read-only remote prefs by @hxreborn

    Fix UnsupportedOperationException that broke the entire preference refresh, causing ring offsets and ~20 other settings to never apply in some scenarios.

  • 888432f - Correct fastlane version code to match tagged commit count by @hxreborn

  • c79f713 - Remove blank line failing ktlint in IndicatorView by @hxreborn

Changed

  • b36b1a8 - (logging) Centralize Logger and gate debug logs behind BuildConfig.DEBUG by @hxreborn

    Reduce log spam on release builds

  • ba67b03 - Remove redundant onTestProgressChanged registration in IndicatorView by @hxreborn

Assets

1

v1.10.0

Stable

3/5/2026, 6:22:31 PM

What's Changed

Added

  • 2868dfc - Add Material You color mapping screen by @hxreborn

    Adds palette+shade picker for progress, completion, and error colors from Android 12+ system palette resources.

  • 3c52d84 - Add configurable segment count and gap by @hxreborn

    Expose segment count and gap degree settings in the Behavior screen when completion style is set to segmented

  • 728ed00 - Add glow effect toggle by @hxreborn

    Add glow effect preferences to the Background Ring section

Fixed

  • 7d28248 - (ci) Prevent tag push race condition in release workflow by @hxreborn

  • c933897 - (prefs) Remove edit call on read-only remote prefs by @hxreborn

    Fix UnsupportedOperationException that broke the entire preference refresh, causing ring offsets and ~20 other settings to never apply in some scenarios.

  • c79f713 - Remove blank line failing ktlint in IndicatorView by @hxreborn

Changed

  • b36b1a8 - (logging) Centralize Logger and gate debug logs behind BuildConfig.DEBUG by @hxreborn

    Reduce log spam on release builds

  • ba67b03 - Remove redundant onTestProgressChanged registration in IndicatorView by @hxreborn

Assets

1

v1.9.0

Stable

3/2/2026, 6:41:45 AM

What's Changed

Added

  • 7d860f4 - (prefs) Per-rotation calibration offsets and vertical filename text by @hxreborn

    • Percentage, filename and badge offsets are now stored per screen rotation
    • Each orientation remembers its own calibrated position independently
    • Calibration screens show current rotation slot (Portrait 0°, Landscape Left 90°, etc.)
    • Option to stack filename characters vertically next to the ring in landscape

Changed

  • 6bbc819 - (ui) Improve orientation indicator in calibration screen by @hxreborn

    • replace ScreenRotation icon with PhoneAndroid in a pill surface
    • use plain landscape/portrait labels with degree instead of string resources

  • 9007fdc - (ui) Replace inline TextInputPreference with dialog by @hxreborn

    • inline text field couldn't be scrolled horizontally for long filenames
    • replaced with dialog using TextFieldState API for proper single-line scrolling

Assets

1

v1.8.2

Stable

2/21/2026, 11:29:53 AM

What's Changed

Fixed

  • 3e462e8 - (hook) Use removal reason to distinguish app-completed downloads by @hxreborn

    Downloads from app stores like Obtainium and Droid-ify showed the error animation instead of the success animation when completing.

Other

Assets

1

v1.8.0

Stable

2/13/2026, 3:04:02 PM

What's Changed

Added

  • c64cfc8 - (view) Add shadow layer to label text paints by @hxreborn

    • Percentage and filename labels now have a dark halo for readability on light wallpapers

  • 524ed43 - Add path renderer for pill-shaped cutouts by @hxreborn

    • Alternative drawing method using PathMeasure for non-circular cutouts (ie dynamic island like, pill etc)
    • "Path mode toggle in calibration screen under Advanced section

  • b65a278 - Add experimental support for Android 9-11 by @hxreborn

  • 0dc2785 - Add theme preference and set Google Blue 500 as default by @hxreborn

    • Add theme selection in System settings with System/Light/Dark options
    • Add dynamic color toggle for Material You wallpaper colors
    • Change default static theme to Google Blue 500 (Material 2 Pixel Blue)
    • Restructure color scheme using Material Theme Builder generated values

Fixed

  • a10a858 - (ui) Use dynamic Material You surface for splash, static M3 Neutral6 fallback by @hxreborn

Changed

Assets

1

v1.7.0

Stable

2/11/2026, 6:22:33 PM

What's Changed

Added

  • da5f8e2 - (ui) Add About section to System tab by @hxreborn

  • cf78266 - (ui) Add text styling options for percentage, filename and badge labels by @hxreborn

    Add granular typography controls to calibration screens:

    • Font size sliders all three label types
    • Bold and italic toggles for percentage and filename text
    • Character-based truncation with configurable max length
    • Ellipsize position options: start, middle, or end
    • Custom preview text for filename calibration

  • b5ab13a - (ui) Add calibration screens for text overlays by @hxreborn

    • Percentage, filename, and badge labels can now be repositioned with X/Y sliders
    • Badge calibration accessible from Behavior tab when queue counter is enabled

Fixed

  • d3e1cf6 - (ui) Prevent calibration transition flicker by @hxreborn

    refactor how LargeTopAppBar is handled when navigation state changed to avoid flickering while going to calibration screen

  • 7f53f5b - (view) Make ring calibration rotation aware by @hxreborn

    • Ring alignment should stay correct when device rotates from portrait to landscape
    • Offset vector transformed using standard 2D rotation matrix

Changed

  • 1cee8ce - (ui) Replace pref callbacks with ViewModel injection by @hxreborn

    • Drop untyped save(key, value) chain in favor of savePref(PrefSpec, T)
    • Remove dead code and unused symbols

Other

Assets

1

v1.6.0

Stable

2/7/2026, 9:05:58 AM

What's Changed

Added

  • 101df02 - (prefs) Add Google Play Store to recommended apps by @hxreborn

  • 0ff9890 - (view) Add burn-in protection for stalled downloads by @hxreborn

    hides ring after 10s of no progress change to prevent
    static pixels damaging OLED panels

  • 7271ae7 - (view) Add background ring and stroke cap style by @hxreborn

    show dimmed ring behind progress arc when enabled (default on)
    stroke cap now selectable: flat, semicircle, square (default flat)

Changed

  • ca0fa7a - (ui) Extract color palette to named constants by @hxreborn

    hardcoded hex values replaced with MaterialPalette object

  • 3e9b039 - (ui) Improve overflow menu in pkg selection by @hxreborn

    reorder items, clarify wording

Assets

1

v1.5.0

Stable

2/4/2026, 6:03:57 PM

What's Changed

Added

Fixed

  • a958b41 - (hook) Register callbacks before optional hooks by @hxreborn

    Move wireCallbacks() to hook() so callback registration is not gated by NotifCollection class loading

  • c8778bb - (hook) Recalculate progress on download complete by @hxreborn

    removing entry only updated filename, leaving average progress stale on multiple downloads

Changed

Other

Assets

1

v1.4.0

Stable

2/1/2026, 11:48:52 PM

What's Changed

Added

Performance Improvements

  • af7e15f - (ui) Fix LargeTopAppBar scroll jank by @hxreborn

    remove custom font-size interpolation causing per-frame text relayout

Changed

  • d209117 - (prefs) Centralize definitions with PrefSpec by @hxreborn

    fixes reset-to-defaults not applying to all preferences
    centralizes prefs for better maintainability

Other

Assets

1

v1.3.0

Stable

1/29/2026, 10:18:06 AM

What's Changed

Added

  • 1086d75 - (prefs) Widen calibration ranges for device variety by @hxreborn

    add more ranges to support more punch-hole/notch shapes
    and display sizes

Fixed

  • 2d74d83 - (ui) Sync default values with material picker options by @hxreborn

    Users couldn't reselect their original defaults after opening picker.

  • 0ee7710 - (view) Draw error animation as calibrated circle by @hxreborn

    drawPath(scaledPath) traced raw cutout shape (rectangle)
    instead of calibrated circle arc

  • 1803483 - (view) Respect power saver mode on error animation by @hxreborn

    move enabled/power-saver checks before the error branch

Changed

Other

  • 8c0bac7 - (ci) Show changelog before releasing by @hxreborn

    also removed poltergeist comment

New Contributors

Assets

1

v1.2.0

Stable

1/28/2026, 6:36:28 PM

What's Changed

Added

  • 105d9ae - (ui) Add calibration screen by @hxreborn

    Support elliptical/non-square punch-hole cutouts with position and scale calibration.

Assets

1

v1.1.0

Stable

1/27/2026, 11:00:30 PM

What's Changed

Added

Fixed

  • 1dfd9d6 - (ci) Detect prerelease from version name by @hxreborn

    Only mark as prerelease if version contains rc, alpha, or beta.

Other

  • 7b17f21 - (ci) Remove dependabot grouping for individual PRs by @hxreborn

    One PR per dependency update, limit increased to 20.

Assets

1

v1.0.0-rc3

Pre-release

1/25/2026, 9:09:31 AM

What's Changed

Fixed

  • fbf23cb - (hook) Handle download completion race condition by @hxreborn in #5

    • fix(hook): ignore low-progress removals to prevent false errors
      Closes #4

    • fix(hook): filter Untitled from filename display

    • style(ci): fix punctuation in feature request template

Changed

Other

  • 026dc68 - (ci) Add GitHub issue templates by @hxreborn

    Bug report form with category dropdown and optional fields.
    Feature request with guidance text.
    Blank issues enabled for everything else.

  • 93a52e6 - (ci) Add dependabot config by @hxreborn

Assets

1