Translators Technical Specification

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.

Architectural Overview

#

Hyper Bridge operates as an event-driven translation engine that intercepts incoming StatusBarNotification events from the Android Notification Listener Service and transforms them into native Xiaomi HyperOS HyperIsland specifications.

flowchart TD
    A["Incoming Android Notification (StatusBarNotification)"] --> B["NotificationReaderService"]
    B --> C["TranslatorRegistry Query"]
    C --> D{"Active Match Found?"}
    
    D -- Yes --> E["DynamicTranslator Engine"]
    D -- No --> F["Built-in Fallback Translators (Media, Call, Standard)"]
    
    E --> G["Extract Type-Specific Data (Messaging, Media, Calls, Progress)"]
    G --> H["Resolve Variable Templating ({notif.title}, {notif.sender}, etc.)"]
    H --> I["Resolve Action Slots & Smart Actions (OTP, Map, Reply)"]
    I --> J["Resolve Theme Binding & Highlight Accents"]
    J --> K{"Engine Mode"}
    
    K -- "CUSTOM_ISLAND (Default)" --> L["HyperIslandNotification.Builder"]
    K -- "NATIVE_LIVE_UPDATE" --> M["LiveUpdateTranslator (Xiaomi Live Channel)"]
    
    L --> N["Xiaomi HyperIsland Framework (HyperIsland)"]
    M --> N
    F --> N

Interception Pipeline Rules

#

1. Allowlist Bypass: If a Custom Translator explicitly targets a specific package (via SPECIFIC_APPS or SYSTEM_APPS), the application bypasses the global app allowlist. It is processed even if the user has not enabled the app in the global library list.
2. Evaluation Precedence: The in-memory TranslatorRegistry indexes all active rules into prioritized buckets: $$\text{SPECIFIC_APPS} \succ \text{SYSTEM_APPS} \succ \text{NOTIFICATION_TYPE} \succ \text{GLOBAL}$$ Within each scope tier, translators are evaluated in descending order of their priority integer (e.g. 200 executes before 100).
3. Short-Circuit Evaluation: The first translator whose TranslatorConditions and TypeSpecificConditions evaluate to true claims the notification.

The .htrans Package Anatomy

#

A Custom Translator can be packaged as a single .htrans archive or distributed as a raw .json file.

my_translator.htrans (ZIP Archive)
├── translator.json        (Required: Schema definition)
└── icons/                 (Optional: Custom graphics)
    ├── ic_custom_action.png
    └── ic_badge.webp

Packaging & Security Specifications

#

• ZIP Container: Standard Deflate-compressed ZIP container renamed to .htrans.
• Zip-Slip Protection: When extracting, the TranslatorRepository validates every canonical entry path against the target directory to prevent directory traversal attacks.
• Internal Storage Location: Extracted icon assets are stored locally under:

  context.filesDir/translators/{translator_id}/icons/

• Theme Bundling: Themes (.htheme / .hbr) can bundle translators in a root translators/ directory:

  neon_theme.htheme (ZIP Archive)
  ├── theme.json
  └── translators/
      ├── spotify_enhanced.htrans
      └── delivery_tracker.json

Complete JSON Schema Reference

#

1. Root: CustomTranslator

#

2. TranslatorMetadata

#

3. TargetScope Enum

#

4. TranslatorConditions

#

5. TypeSpecificConditions

#

A. Messaging (messaging)

#

B. Media (media)

#

C. Calls (call)

#

D. Navigation (navigation)

#

E. Progress (progress)

#

6. DataExtractionConfig

#

7. ActionSlotConfig

#

ActionMatcher

#

8. PresentationConfig & CompactPillConfig

#

Compact Pill Slot Options

#

• left_design (PillLeftDesign):
  • ICON_AND_TEXT (Default): Shows app/slot icon and short title.
  • ICON_ONLY: Shows only the masked icon.
  • TEXT_ONLY: Shows only title text.
  • AVATAR: Shows contact avatar (extracted from Messaging notifications).
  • HIDDEN: Hides the left side of the pill.
• right_design (PillRightDesign):
  • AUTO (Default): Automatically chooses progress, timer, or status.
  • PROGRESS_PERCENT: Shows numeric percentage (e.g. 78%).
  • TIMER: Displays active ticking chronometer/countdown.
  • HIGHLIGHT_TEXT: Shows accented badge text.
  • NONE: Leaves right side empty.

9. EngineMode & BehaviorOverride

#

10. CustomVariableDefinition (custom_variables)

#

The custom_variables pipeline allows translators to extract arbitrary pieces of information, parse regex capture groups, calculate step progress from keywords, or load custom graphics:

VariableSource Options

#

StepExtractionConfig

#

Used when type is STEP_PROGRESS to map delivery or process states into an integer step:

VariableImageConfig

#

Used when type is IMAGE to customize how the image is styled and bundled into miui.focus.pics:

11. CustomActionDefinition (custom_actions)

#

The custom_actions pipeline enables binding native notification actions, Smart Action utilities, or inline replies directly to Xiaomi HyperIsland action slots or RAW_PARAM_V2 action keys:

12. Direct Xiaomi Island Protocol: PresentationMode.RAW_PARAM_V2

#

For advanced developers and reverse-engineers who want byte-level control over the native Xiaomi HyperOS HyperIsland payload, Hyper Bridge 0.6.0 introduces PresentationMode.RAW_PARAM_V2.

Instead of relying on predefined visual slots (text_slot, progress_slot, pill), you provide a native Xiaomi param_v2 JSON template string. Hyper Bridge handles the heavy lifting: evaluating variables, extracting graphics, wiring PendingIntents into the Android resource bundle, validating the JSON schema, and transmitting the packet directly to HyperOS.

"presentation": {
  "mode": "RAW_PARAM_V2",
  "raw_param_v2": {
    "json_template": "{\"param_v2\": { ... }}",
    "fallback_to_standard_on_error": true,
    "bundle_pictures": true,
    "bundle_actions": true
  }
}

RawParamV2Config Properties

#

Automatic Normalization & Structural Guarantees

#

Hyper Bridge’s validateOrNormalizeParamV2 engine inspects the template output and guarantees protocol compliance:

1. Root Wrapping: If the template provides a bare object (e.g. starting with {"bigIslandArea": ...}), the engine automatically wraps it in {"param_v2": { ... }}.
2. Param Island Verification: Ensures param_island exists with islandProperty: 1.
3. Small Island Auto-Generation: If smallIslandArea is omitted, the engine automatically derives it using the primary picture candidate and hidden_pixel.
4. Big Island Auto-Generation: If bigIslandArea is omitted but baseInfo is present, the engine constructs an imageTextInfoLeft layout automatically.
5. Key Duplication in Bundles: In both miui.focus.pics and miui.focus.actions, keys are populated with both their raw name (e.g. pic_avatar) and their prefixed name (miui.focus.pic_avatar) so templates work regardless of key formatting.

Dynamic Variable Templating Engine

#

All template strings (json_template, title_template, subtitle_template, etc.) are processed by the interpolation engine.

Cascading Fallback & Default Syntax

#

Hyper Bridge supports robust fallback cascades to ensure notification cards never display empty fields or broken placeholders:

{primary_token | secondary_token | "Default Literal"}
{primary_token ?: Default Literal}

• Pipe Operator (| or ||): Evaluates tokens from left to right. Selects the first non-empty, non-blank variable.
• Elvis Operator (?:): Provides a fallback default value if the preceding token is missing or blank.
• Quoted Literals ("..." or '...'): Explicitly defines a string literal fallback (e.g. {"YouTube"}).
• Unquoted Literals: If the final alternative does not match any known variable token, it is treated as a default literal string.
• Image Key Safety: When cascading picture tokens (e.g. {pic.avatar | pic.large_icon | pic.app_icon}), the engine checks whether each candidate image actually exists in the bundle before selecting it!

Cascading Examples

#

• {media.artist | notif.text | "Unknown Artist"} → Uses media.artist; if empty, uses notif.text; if still empty, resolves to "Unknown Artist".
• {var.eta ?: "Arriving soon"} → Uses extracted variable var.eta; if blank, outputs "Arriving soon".
• {pic.driver_photo | pic.large_icon | pic.app_icon} → Safely picks the first graphic that was successfully extracted or loaded into miui.focus.pics.

Complete Runtime Variable Dictionary

#

The following table lists all built-in tokens available during interpolation:

Production Examples

#

Example 1: Food Delivery Live Waypoint Tracker

#

Interprets delivery progress from a food app, extracts numeric percentage, and displays a waypoint template with a 1-tap call driver button.

{
  "id": "com.fooddelivery.live_tracker",
  "meta": {
    "name": "Food Delivery Waypoint Tracker",
    "author": "HyperBridge Team",
    "version": 1,
    "description": "Transforms food delivery notifications into a live tracked island.",
    "icon_name": "LocalShipping"
  },
  "target_scope": "SPECIFIC_APPS",
  "target_packages": ["com.ubercab.eats", "com.doordash.driverapp"],
  "priority": 250,
  "is_enabled": true,
  "conditions": {
    "title_regex": "(?i).*(order|delivering|driver|courier).*",
    "has_progress": true
  },
  "data_extraction": {
    "extract_progress_from_text": true,
    "progress_regex": "(\\d+)%\\s*completed"
  },
  "presentation": {
    "mode": "TEMPLATE",
    "template_id": "tpl_ride_delivery",
    "text_slot": {
      "title_template": "{notif.title}",
      "subtitle_template": "{notif.text}",
      "highlight_text_template": "{notif.progress}%"
    },
    "progress_slot": {
      "type": "PROGRESS_BAR",
      "progress_source": "AUTO_DETECT",
      "color_source": "THEME_HIGHLIGHT",
      "show_percentage": true
    },
    "action_slots": [
      {
        "slot_position": 0,
        "is_visible": true,
        "source": "SMART_ACTION",
        "smart_action_type": "DIAL_NUMBER",
        "display_mode": "ICON_AND_TEXT",
        "custom_label": "Call Driver"
      }
    ],
    "pill": {
      "left_design": "ICON_AND_TEXT",
      "right_design": "PROGRESS_PERCENT"
    }
  },
  "theme_binding": {
    "override_highlight_color": "#06C167"
  },
  "behavior_override": {
    "is_float": true,
    "float_timeout_seconds": 6
  }
}

Example 2: WhatsApp VIP Contact with Inline Reply

#

Elevates messages from a specific VIP contact, displays their contact avatar, applies custom green theme branding, and enables an interactive inline reply button.

{
  "id": "com.whatsapp.vip_contact",
  "meta": {
    "name": "WhatsApp VIP Contact",
    "author": "PowerUser",
    "version": 1,
    "description": "High-priority styling with custom avatar and inline reply for VIP contacts.",
    "icon_name": "Star"
  },
  "target_scope": "SPECIFIC_APPS",
  "target_packages": ["com.whatsapp"],
  "priority": 500,
  "is_enabled": true,
  "conditions": {
    "type_specific_conditions": {
      "messaging": {
        "sender_name_regex": "(?i)Mom|Sarah|Boss"
      }
    }
  },
  "presentation": {
    "mode": "STANDARD",
    "left_slot": {
      "source": "AVATAR",
      "shape": "circle"
    },
    "text_slot": {
      "title_template": "⭐ {notif.sender}",
      "subtitle_template": "{notif.text}"
    },
    "action_slots": [
      {
        "slot_position": 0,
        "is_visible": true,
        "source": "INLINE_REPLY",
        "display_mode": "ICON_AND_TEXT",
        "custom_label": "Reply"
      },
      {
        "slot_position": 1,
        "is_visible": true,
        "source": "NOTIFICATION_ACTION",
        "action_matcher": {
          "match_by": "TITLE",
          "title_regex": "(?i)read|mark"
        },
        "display_mode": "TEXT_ONLY",
        "custom_label": "Read"
      }
    ],
    "pill": {
      "left_design": "AVATAR",
      "right_design": "HIGHLIGHT_TEXT"
    }
  },
  "theme_binding": {
    "override_highlight_color": "#25D366"
  },
  "behavior_override": {
    "is_float": true,
    "float_timeout_seconds": 8,
    "enable_inline_reply": true
  }
}

Example 3: Smart Two-Factor Authentication (OTP) Auto-Copier

#

Detects incoming SMS or authenticator codes, extracts the verification code, and injects a 1-tap clipboard copy action.

{
  "id": "global.smart_otp_copier",
  "meta": {
    "name": "Smart 2FA / OTP Copy Action",
    "author": "HyperBridge Security",
    "version": 1,
    "description": "Detects verification codes and inserts a 1-tap OTP copy button.",
    "icon_name": "Key"
  },
  "target_scope": "GLOBAL",
  "priority": 900,
  "is_enabled": true,
  "conditions": {
    "text_regex": "(?i).*(\\b\\d{4,8}\\b|code|verification|otp|password).*"
  },
  "presentation": {
    "mode": "STANDARD",
    "text_slot": {
      "title_template": "🔐 Verification Code",
      "subtitle_template": "{notif.text}"
    },
    "action_slots": [
      {
        "slot_position": 0,
        "is_visible": true,
        "source": "SMART_ACTION",
        "smart_action_type": "OTP_COPY",
        "display_mode": "ICON_AND_TEXT",
        "custom_label": "Copy Code"
      }
    ],
    "pill": {
      "left_design": "ICON_AND_TEXT",
      "right_design": "NONE"
    }
  },
  "theme_binding": {
    "override_highlight_color": "#007AFF"
  },
  "behavior_override": {
    "is_float": true,
    "float_timeout_seconds": 10
  }
}

Example 4: Direct RAW_PARAM_V2 Ride-Share Live Tracker

#

An advanced developer example using PresentationMode.RAW_PARAM_V2. It parses driver name, ETA minutes, and vehicle model via regular expressions, bundles a custom driver avatar and call button, and renders a native Xiaomi HyperOS HyperIsland directly:

{
  "id": "com.rideshare.live_driver_v2",
  "meta": {
    "name": "Ride-Share HyperIsland (RAW_PARAM_V2)",
    "author": "HyperBridge Pro Dev",
    "version": 2,
    "description": "Native Xiaomi param_v2 ride tracker with regex extraction, dynamic fallback cascade, and direct action bundling.",
    "icon_name": "DirectionsCar"
  },
  "target_scope": "SPECIFIC_APPS",
  "target_packages": ["com.uber.driverapp", "com.rideshare.passenger"],
  "priority": 750,
  "is_enabled": true,
  "conditions": {
    "title_regex": "(?i)driver|arriving|ride",
    "text_regex": "(?i).*(\\d+)\\s*mins?.*"
  },
  "custom_variables": [
    {
      "id": "eta_mins",
      "label": "ETA Minutes",
      "type": "NUMBER",
      "source": "NOTIFICATION_TEXT",
      "regex_pattern": "(\\d+)\\s*mins?",
      "regex_group": "1",
      "fallback_value": "5"
    },
    {
      "id": "driver_name",
      "label": "Driver Name",
      "type": "TEXT",
      "source": "NOTIFICATION_TITLE",
      "regex_pattern": "(?i)([a-zA-Z]+)\\s+is arriving",
      "regex_group": "1",
      "fallback_chain": ["notif.sender", "notif.title"],
      "fallback_value": "Your Driver"
    },
    {
      "id": "driver_avatar",
      "label": "Driver Photo",
      "type": "IMAGE",
      "source": "NOTIFICATION_LARGE_ICON",
      "image_config": {
        "shape_id": "circle",
        "padding_percent": 0,
        "fallback_image_source": "NOTIFICATION_APP_ICON"
      }
    }
  ],
  "custom_actions": [
    {
      "id": "contact_driver",
      "label": "Call Driver",
      "source": "NOTIFICATION_ACTION_TITLE_REGEX",
      "title_regex": "(?i)call|contact"
    }
  ],
  "presentation": {
    "mode": "RAW_PARAM_V2",
    "raw_param_v2": {
      "fallback_to_standard_on_error": true,
      "bundle_pictures": true,
      "bundle_actions": true,
      "json_template": "{\"param_v2\":{\"protocol\":1,\"business\":\"transport\",\"enableFloat\":true,\"updatable\":true,\"ticker\":\"{var.driver_name} is {var.eta_mins} mins away\",\"param_island\":{\"islandProperty\":1,\"bigIslandArea\":{\"imageTextInfoLeft\":{\"type\":1,\"picInfo\":{\"type\":1,\"pic\":\"{pic.driver_avatar | pic.large_icon | pic.app_icon}\"},\"textInfo\":{\"title\":\"{var.driver_name}\",\"content\":\"{var.eta_mins} mins away\"}},\"actionArea\":{\"actionKeys\":[\"{action.contact_driver | action.0}\"]}},\"smallIslandArea\":{\"picInfo\":{\"type\":1,\"pic\":\"{pic.driver_avatar | pic.app_icon}\"}}},\"baseInfo\":{\"type\":2,\"title\":\"{var.driver_name}\",\"subTitle\":\"Arriving in {var.eta_mins} min\",\"content\":\"Ride in progress\",\"pic\":\"{pic.driver_avatar | pic.app_icon}\"}}}"
    }
  },
  "theme_binding": {
    "override_highlight_color": "#000000"
  },
  "behavior_override": {
    "is_float": true,
    "float_timeout_seconds": 12
  }
}