Hyper Bridge

Contributing Guide

Mon, 01 Jan 0001 00:00:00 +0000

We welcome all contributions to Hyper Bridge!

Getting Started
#

Clone the repo.
Open in Android Studio (Ladybug or newer recommended).
Sync Gradle and run on a device/emulator (API 26+).

Code Style
#

We use Kotlin exclusively.
UI must be written in Jetpack Compose (Material 3).
Follow the existing package structure:
- ui/: Screens and Components.
- service/: Background logic and Translators.
- data/: Preferences and Models.

Pull Requests
#

Do not push directly to main.
Create a branch for your feature/fix.
Provide a clear description of what you changed.
If you are adding a UI feature, attach a screenshot to the PR.

Reporting Bugs
#

Please use the Issues tab and provide:

Design Studio & Hub

Mon, 01 Jan 0001 00:00:00 +0000

The Design Hub (DesignScreen) in Hyper Bridge 0.6.0 is your creative control center. Located in the bottom navigation bar alongside Active Apps and Library, the Design screen brings together all personalization aspects of your Xiaomi HyperOS HyperIsland experience in a unified Material 3 Expressive interface.

Dynamic Island Engine

Mon, 01 Jan 0001 00:00:00 +0000

The core engine maps notifications into 6 main categories:

Media Playback: Track title, artist, live audio waveforms, and playback buttons.
Active Calls: Call duration, contact avatar, mute and hangup buttons.
Downloads & Progress: Dynamic progress bars with percentage tracking.
Navigation: Turn-by-turn directions and distance metrics.
Timers: Live countdown indicators.
Standard Notifications: Instant island preview with smart dismissal.

Frequently Asked Questions (FAQ)

Mon, 01 Jan 0001 00:00:00 +0000

Find answers to common questions about how Hyper Bridge works, its architecture, compatibility, and privacy guarantees.

What does Hyper Bridge do?
#

Hyper Bridge is an application that acts as a bridge, reading standard Android notifications and translating them into native, featured notifications for Xiaomi HyperOS to display seamlessly on the HyperIsland (HyperIsland / Dynamic Island).

Installation & Requirements

Mon, 01 Jan 0001 00:00:00 +0000

Learn about system requirements and how to install Hyper Bridge on your device.

System Requirements
#

Operating System: Xiaomi HyperOS 3.0 or Xiaomi HyperOS 4.0 (Android 15 / Android 16 / Android 17).
Supported ROMs: Global, EEA, India, Taiwan, and CN (China) ROMs (CN ROMs require Shizuku or Sui for the Xiaomi bypass).
Root: Not required! Hyper Bridge operates without root access.

Download & Installation
#

You can install Hyper Bridge from the Google Play Store or download the APK directly from GitHub Releases.

Notification Listener Access

Mon, 01 Jan 0001 00:00:00 +0000

Note: This page is currently Work in Progress.

HyperBridge needs access to system notifications to detect active music, downloads, timers, and messages.

Shizuku Setup Guide

Mon, 01 Jan 0001 00:00:00 +0000

Setting up Shizuku is completely rootless and takes less than two minutes using Android’s built-in Wireless Debugging.

Prerequisites
#

Connect your Xiaomi device to a Wi-Fi network.
Enable Developer options (tap OS Version 7 times in About phone).

Setup Steps
#

1. Install Shizuku
#

Install Shizuku from Google Play or GitHub.

System Health & Setup Guide

Mon, 01 Jan 0001 00:00:00 +0000

Xiaomi HyperOS is known for its strict background memory management and multi-tiered permission system. To ensure that Hyper Bridge can reliably intercept incoming notifications, render islands seamlessly, and stay alive in the background, the app includes a central System Health Dashboard (SetupHealthScreen) and a dedicated Floating Notification Setup manager.

Theme Creator Guide

Mon, 01 Jan 0001 00:00:00 +0000

This guide covers how to customize and create themes using the In-App Theme Creator in Hyper Bridge:

Build, preview, and customize colors, geometric masks, call styles, and engine behaviors directly on your device.
Export your creations or import themes shared by the community.

Looking for the developer package specification or Android Intent API?
See the Theme Packaging Specification (.hbr) in the Advanced & Developer documentation.

Visual Theme Creator (In-App)
#

Hyper Bridge 0.6.0 includes a full-featured Visual Theme Creator (ThemeCreatorScreen). You can build, preview, edit, and apply beautiful custom island themes directly on your phone without touching JSON or ZIP files.

Translators Technical Specification

Mon, 01 Jan 0001 00:00:00 +0000

This document provides the authoritative technical reference for the Custom Translators Framework (.htrans) in Hyper Bridge 0.6.0. It is designed for developers, theme authors, and power users building custom notification pipelines, automation tools, or community packages.

Custom Translators Guide

Mon, 01 Jan 0001 00:00:00 +0000

Hyper Bridge 0.6.0 introduces the Custom Translators Framework, a declarative engine that lets you customize exactly how notifications from any app are transformed into native Xiaomi HyperOS HyperIsland (HyperIsland) cards and compact status pills.

Diagnostics & System Health Monitor

Mon, 01 Jan 0001 00:00:00 +0000

The Diagnostics Screen in Hyper Bridge provides real-time visibility into the internal operating state of the bridge engine. It gives you instant insight into listener service connectivity, permission health, recent notification event streams, and translation statistics.

First Steps & Onboarding Wizard

Mon, 01 Jan 0001 00:00:00 +0000

When you open Hyper Bridge for the first time, an intuitive 22-step visual onboarding wizard guides you through compatibility validation, essential Android permissions, background optimizations, and core island behaviors.

This guide walks you through every screen of the wizard with visual screenshots.

HyperOS Focus Notifications

Mon, 01 Jan 0001 00:00:00 +0000

On HyperOS, dynamic islands require the Featured Notifications (also known as Focus Notifications) permission.

If you don’t see dynamic islands appearing around the camera punch-hole, this permission is almost always the reason! Note: This page is currently Work in Progress.

Steps to Enable
#

Work in Progress

Known Issues & HyperOS Quirks

Mon, 01 Jan 0001 00:00:00 +0000

Common Issues & Fixes
#

Islands disappear after locking screen
#

Fix: Whitelist HyperBridge in the Xiaomi Security app by setting Autostart to Allowed and Battery saver to No restrictions.

Smartwatch notifications stopped working
#

Fix: In HyperBridge settings, ensure Remove original notification is disabled.

Chinese (CN) ROM not displaying islands
#

Fix: Set up Shizuku and toggle the Shizuku workaround in HyperBridge Theme Editor Engine settings.

Native System Apps & Options

Mon, 01 Jan 0001 00:00:00 +0000

Hyper Bridge includes native system island adapters for essential HyperOS and Android platform services: Screen Recording, System Updates, and VPN connections. These system modules have specialized layouts, live timers, progress bars, and custom side display configurations.

Privileged Features Overview

Mon, 01 Jan 0001 00:00:00 +0000

Note: This page is currently Work in Progress.

When Shizuku is authorized, Hyper Bridge gains access to advanced system capabilities:

Smart Actions & Context Buttons

Mon, 01 Jan 0001 00:00:00 +0000

Smart Actions supercharge your notifications by automatically detecting actionable entities—such as 2FA verification codes, street addresses, map links, phone numbers, and package tracking numbers—and injecting contextual 1-tap action buttons directly onto the HyperIsland (HyperIsland) and notification shade.

Theme Packaging Specification (.hbr / .htheme)

Mon, 01 Jan 0001 00:00:00 +0000

This specification defines the packaging format and Android integration contract for distributing standalone Hyper Bridge Theme Packages (.hbr or .htheme).

It is intended for third-party Android theme developers, icon pack authors, and modders building automated distribution pipelines or companion apps.

Website & Docs Translation Guide

Mon, 01 Jan 0001 00:00:00 +0000

Thank you for your interest in making Hyper Bridge accessible to users worldwide!

This guide explains how to translate the website and documentation hosted on GitHub: HyperBridge-Site.

Translating the Android App vs. the Website:

Android App Strings: Translated via our Crowdin Project.
Website & Documentation: Translated directly via Pull Requests on GitHub (HyperBridge-Site).

Adding Smart Actions Support for Your Language

Mon, 01 Jan 0001 00:00:00 +0000

Smart Actions find verification codes, addresses, links, phone numbers and parcel numbers in notification text. Numbers and links look the same everywhere, but the words around them don’t: “code”, “Calle”, “Straße” and “посылка” all have to be listed somewhere. This guide shows where those lists live and how to add your language.

Battery Saver & Autostart Whitelist

Mon, 01 Jan 0001 00:00:00 +0000

Xiaomi devices aggressively kill background services by default. Follow these steps to keep Hyper Bridge running smoothly:

1. Enable Autostart
#

Go to Security app > Manage apps > Hyper Bridge > Toggle Autostart to Allowed.

Bug Reporting & Issue Diagnosis

Mon, 01 Jan 0001 00:00:00 +0000

Hyper Bridge includes an integrated, privacy-first Bug Report Generator that combines your description of an issue with an automated hardware and permission snapshot.

Submitting a complete bug report helps the development team pinpoint issues on specific Xiaomi device models, HyperOS regional builds, and notification styles without tedious back-and-forth debugging.

Island Templates & Designs

Mon, 01 Jan 0001 00:00:00 +0000

Starting with Hyper Bridge 0.6.0, you can display incoming notifications using Xiaomi’s 10 Official HyperIsland Layout Templates (IslandTemplateCatalog).

Templates take the guesswork out of designing notification cards: each template provides a purpose-built visual architecture with optimal typography, progress elements, and button layouts optimized specifically for HyperOS 3 HyperIsland.

Managing & Enabling Apps

Mon, 01 Jan 0001 00:00:00 +0000

After completing the initial setup, you can control precisely which applications are bridged into dynamic islands. The Active Apps management screen provides fine-grained controls, category filters, and automatic rules for new installations.

Permanent Island

Mon, 01 Jan 0001 00:00:00 +0000

Permanent Island allows your device’s camera punch hole to always blend seamlessly into a continuous, interactive dynamic island—even when no music is playing and no active notifications are present.

How Permanent Island Works
#

In standard behavior, the HyperIsland only appears when an active event occurs (such as incoming notifications, music playback, or navigation cues) and collapses completely once dismissed or timed out.

App Settings & Preferences

Mon, 01 Jan 0001 00:00:00 +0000

The Settings menu in Hyper Bridge provides complete command over engine behaviors, queuing limits, privacy exclusions, and diagnostic tools. Tap the gear icon in the top right corner of the app to access settings.

Inline Reply

Mon, 01 Jan 0001 00:00:00 +0000

Inline Reply brings immediate, seamless chat responses to your HyperOS dynamic island. Instead of pulling down the entire notification shade or switching away from your current app or game, tapping reply on any supported message immediately launches a sleek floating input box.

System Widgets on HyperIsland

Mon, 01 Jan 0001 00:00:00 +0000

Hyper Bridge 0.6.0 features a native Android AppWidget Host, allowing you to place any standard Android home-screen widget (Spotify, Google Keep, Weather, Clock, Calendar, Smart Home toggles, etc.) directly into your Xiaomi HyperOS HyperIsland!

Custom Widget Studio: Overview & In-App Builder

Mon, 01 Jan 0001 00:00:00 +0000

Introduced in Hyper Bridge 0.6.0-beta4, the Micro-Widgets Studio brings KWGT-style element-by-element design capabilities directly to Xiaomi HyperOS HyperIsland (Super Island).

Instead of being restricted to fixed layout templates, you can now construct freeform, layer-based micro-widgets with custom typography, responsive progress bars, interactive buttons, dynamic image masks, and Material 3 expressive color schemes.

Custom Widget Elements & Visual Properties

Mon, 01 Jan 0001 00:00:00 +0000

Every design built in the Micro-Widgets Studio is composed of an Abstract Syntax Tree (AST) of visual nodes (CustomWidgetNode). When compiled, Hyper Bridge maps these elements into optimized Android RemoteViews compatible with Xiaomi HyperOS HyperIsland.

Formulas, Dynamic Data & Visibility Conditions

Mon, 01 Jan 0001 00:00:00 +0000

A key strength of the Micro-Widgets Studio in Hyper Bridge 0.6.0-beta4 is its dynamic execution engine. Rather than rendering static mockups, every property can be tied to live notification data, media sessions, device telemetry, and conditional rules.

Color Schemes & Material 3 Dynamic Palettes

Mon, 01 Jan 0001 00:00:00 +0000

Starting with Hyper Bridge 0.6.0-beta4, the custom widget engine features a full Material 3 Dynamic Color Architecture (DynamicColorSchemeResolver).

Instead of hardcoding static hex colors into your widgets, you can now bind visual elements to semantic color roles. Widgets can adapt automatically to your wallpaper, the notifying app’s launcher icon, or album artwork—or follow a custom YAML color palette you create!

Packaging, Sharing & Handcrafting .hwidget Files

Mon, 01 Jan 0001 00:00:00 +0000

Every design created in Hyper Bridge can be packaged, backed up, and shared across devices as a standalone .hwidget file.

Under the hood, a .hwidget file is a standard ZIP archive containing the widget’s structural tree (widget.json), its notification binding rules (translator.json), and any embedded image or vector graphics (assets/).

Changelog

Mon, 01 Jan 0001 00:00:00 +0000

Follow the latest updates, features, and release history for HyperBridge.

HyperBridge v0.6.0-beta3 🚀
#

Welcome to v0.6.0-beta3! This release introduces the all-new Design Hub with a Bento Grid layout, a visual Island Template Composer supporting all 10 official Xiaomi HyperOS island layouts, critical fixes for Xiaomi HyperOS 4 Beta compatibility, and a streamlined documentation section.

Changelog

Mon, 01 Jan 0001 00:00:00 +0000

Follow the latest updates, features, and release history for HyperBridge.

Hyper Bridge

Contributing Guide

Getting Started #

Code Style #

Pull Requests #

Reporting Bugs #

Design Studio & Hub

Dynamic Island Engine

Frequently Asked Questions (FAQ)

What does Hyper Bridge do? #

Installation & Requirements

System Requirements #

Download & Installation #

Notification Listener Access

Shizuku Setup Guide

Prerequisites #

Setup Steps #

1. Install Shizuku #

System Health & Setup Guide

Theme Creator Guide

Visual Theme Creator (In-App) #

Translators Technical Specification

Custom Translators Guide

Diagnostics & System Health Monitor

First Steps & Onboarding Wizard

HyperOS Focus Notifications

Steps to Enable #

Known Issues & HyperOS Quirks

Common Issues & Fixes #

Islands disappear after locking screen #

Smartwatch notifications stopped working #

Chinese (CN) ROM not displaying islands #

Native System Apps & Options

Privileged Features Overview

Smart Actions & Context Buttons

Theme Packaging Specification (.hbr / .htheme)

Website & Docs Translation Guide

Adding Smart Actions Support for Your Language

Battery Saver & Autostart Whitelist

1. Enable Autostart #

Bug Reporting & Issue Diagnosis

Island Templates & Designs

Managing & Enabling Apps

Permanent Island

How Permanent Island Works #

App Settings & Preferences

Inline Reply

System Widgets on HyperIsland

Custom Widget Studio: Overview & In-App Builder

Custom Widget Elements & Visual Properties

Formulas, Dynamic Data & Visibility Conditions

Color Schemes & Material 3 Dynamic Palettes

Packaging, Sharing & Handcrafting .hwidget Files

Changelog

HyperBridge v0.6.0-beta3 🚀 #

Changelog

HyperBridge v0.6.0-beta3 🚀 #

Getting Started
#

Code Style
#

Pull Requests
#

Reporting Bugs
#

What does Hyper Bridge do?
#

System Requirements
#

Download & Installation
#

Prerequisites
#

Setup Steps
#

1. Install Shizuku
#

Visual Theme Creator (In-App)
#

Steps to Enable
#

Common Issues & Fixes
#

Islands disappear after locking screen
#

Smartwatch notifications stopped working
#

Chinese (CN) ROM not displaying islands
#

1. Enable Autostart
#

How Permanent Island Works
#

HyperBridge v0.6.0-beta3 🚀
#

HyperBridge v0.6.0-beta3 🚀
#