miui-browser-tab-keepalive

KO | EN

gitlite — search

#javascript #python #hacktoberfest #react #ai #typescript #llm #go #golang #android #machine-learning #rust #deep-learning #linux

miui-browser-tab-keepalive

★ 11 Open GitHub ↗

Tampermonkey userscript that prevents MIUI/HyperOS from killing mobile browser tabs. Works with Firefox, Edge, Yandex, Kiwi, and other browsers. No root required.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# MIUI Browser Tab KeepAlive

A Tampermonkey userscript that helps prevent mobile browser tabs from being killed by aggressive Android memory management (MIUI, HyperOS, ColorOS, FunTouchOS, and similar).

Works with Firefox Mobile, Microsoft Edge, Yandex Browser, Kiwi Browser, Lemur Browser, and other Tampermonkey-compatible mobile browsers.

---

## Table of Contents

- [The Problem](#the-problem)
- [How This Script Helps](#how-this-script-helps)
- [Features](#features)
- [Requirements](#requirements)
- [Supported Browsers](#supported-browsers)
- [Installation](#installation)
- [Usage Guide](#usage-guide)
  - [Understanding the Master Tab Concept](#understanding-the-master-tab-concept)
  - [Usage](#usage)
  - [Deactivating the KeepAlive](#deactivating-the-keepalive)
  - [Using Profile 2 (Aggressive Mode)](#using-profile-2-aggressive-mode)
  - [Switching the Master Tab](#switching-the-master-tab)
  - [Visual Indicator Reference](#visual-indicator-reference)
- [Profile Configuration](#profile-configuration)
  - [Understanding the Two Profiles](#understanding-the-two-profiles)
  - [Where to Find the Configuration](#where-to-find-the-configuration)
  - [Parameter Reference](#parameter-reference)
  - [Tuning Strategy](#tuning-strategy)
- [Limitations and Known Issues](#limitations-and-known-issues)
- [Troubleshooting](#troubleshooting)
- [Tested Devices](#tested-devices)
- [Community and Configuration Sharing](#community-and-configuration-sharing)
- [License](#license)
- [Support](#support)

---

## The Problem

Xiaomi's MIUI, HyperOS, and similar aggressive Android skins implement memory management that kills background applications and browser tabs without warning. This affects mobile browser users in several ways:

- Switching away from your browser for even a few minutes causes tabs to be killed
- Turning off the screen terminates the browser entirely
- Watching a video and briefly switching to another app results in the tab being discarded
- Form data and session state is lost
- The browser must reload tabs from scratch, losing your place

Android's standard application lifecycle is ignored by these ROMs, and there is no reliable way to prevent this behavior through system settings alone.

---

## How This Script Helps

This userscript makes Android treat your browser as an active media application. Android ROMs, including aggressive ones like MIUI, usually avoid killing apps while they are actively playing media.

The script can keep the browser "alive" in two ways:

1. **Video KeepAlive**: Creates an invisible canvas-based video stream and plays it as a hidden video element.
2. **Audio KeepAlive**: Generates a quiet audio tone and plays it through a hidden audio element.

In both modes, the script registers a **MediaSession** that appears in Android's media controls as **"Video KeepAlive"** or **"Audio KeepAlive"**. As long as this notification is present, the system is much less likely to kill the browser and discard tabs.

---

## Features

- **Multi-Browser Support**: Works on any mobile browser with Tampermonkey extension
- **No Root Required**: Works entirely through a userscript, no system modifications needed
- **Master Tab System**: Only one tab runs the keepalive mechanism at a time, conserving battery
- **Two Configurable Profiles**: A normal profile for everyday use and an aggressive profile for difficult situations
- **Quick Profile Switching**: Short tap for normal activation, long press for aggressive mode
- **Video + Audio Modes**: Use hidden video playback or hidden audio playback (configurable per profile)
- **Configurable Priority/Fallback**: If both audio and video are enabled, you can choose which one is started first
- **Visual Feedback**: A badge in the corner shows the current state with distinct colors for each profile
- **Multi-Tab Awareness**: Seamlessly transfer the keepalive to another tab by tapping its badge
- **Battery Conscious**: Configurable parameters allow you to balance stability against battery consumption
- **Non-Intrusive**: Avoids overriding MediaSession while real media is playing on the page
- **Optional Notification Controls**: Allow or block pause/play from Android notification controls per mode

---

## Requirements

- A mobile browser with Tampermonkey extension support (see Supported Browsers below)
- Tampermonkey extension installed
- A device with aggressive memory management (Xiaomi, Redmi, POCO, Realme, Oppo, Vivo, or similar)

---

## Supported Browsers

This script works with any mobile browser that supports the Tampermonkey extension:

| Browser                                | Status      | Notes                                                      |
|----------------------------------------|-------------|------------------------------------------------------------|
| Firefox Mobile                         | Recommended | Primary development and testing browser                    |
| Firefox Forks (Fennec, Mull, Iceraven) | Supported   | Should work identically to Firefox Mobile                  |
| Microsoft Edge                         | Supported   |                                                            |
| Yandex Browser                         | Supported   |                                                            |
| Kiwi Browser                           | Supported   |                                                            |
| Lemur Browser                          | Supported   |                                                            |
| Safari (iOS)                           | Supported   | Use "Userscripts" by Quoid from App Store, or similar Apps |

**Note for browsers that block YouTube userscripts:** Some browsers may prevent userscripts from running on YouTube. If you encounter this issue, you can use Vimeo as an alternative. The script already includes support for `vimeo.com`.

---

## Installation

1. Install Tampermonkey from your browser's add-on/extension store:
   - Firefox: https://addons.mozilla.org/firefox/addon/tampermonkey/
   - Other browsers: Search for "Tampermonkey" in your browser's extension store

2. Visit the Greasy Fork page and tap "Install":
   https://greasyfork.org/en/scripts/563527-miui-browser-tab-keepalive

3. Confirm the installation when Tampermonkey prompts you

4. Open any YouTube or Vimeo page to verify the installation — you should see a small circle badge in the bottom-right corner

5. (Optional) If videos stop playing when the browser is in the background or when the screen is switched off, you can also install this companion script:

**Install Mobile Browser Background Video**
   https://greasyfork.org/en/scripts/563528-mobile-browser-background-video

---

## Usage Guide

### Understanding the Master Tab Concept

The script uses a **Master Tab** system. When you activate KeepAlive on any YouTube or Vimeo tab, that tab becomes the master. The important part is that the master tab protects **all browser tabs**, not just itself.

The recommended approach is to dedicate one YouTube or Vimeo tab as your permanent master tab. This tab does not need to play any real video content — it simply needs to exist and have KeepAlive activated.

### Usage

Most mobile browsers require a user gesture before they allow background media playback and MediaSession controls.

1. Open YouTube or Vimeo
2. Start any video once
3. Pause it again
4. Tap the badge once to activate KeepAlive
5. A white lock icon will appear inside the circle
6. Check Android notifications — you should now see **"Video KeepAlive"** or **"Audio KeepAlive"** in the media player controls

### Deactivating the KeepAlive

To stop KeepAlive:

1. Go to the master tab (the one showing the lock icon)
2. Tap the badge again
3. The lock will disappear, leaving only the empty circle
4. The KeepAlive media notification will be removed

Alternatively, simply close the master tab.

### Controlling KeepAlive from Notifications

By default, KeepAlive ignores pause commands from Android notification controls. This prevents accidental deactivation and makes KeepAlive more robust against other apps trying to stop it.

If you prefer to control KeepAlive via the notification player:

1. Set `VideoKeepAliveAllowInput: true` and/or `AudioKeepAliveAllowInput: true` in the profile configuration
2. You can now pause and resume KeepAlive using the notification media controls
3. KeepAlive will stay paused until you manually resume it or reactivate via the badge

### Using Profile 2 (Aggressive Mode)

Profile 2 provides more aggressive KeepAlive settings for devices that need stronger protection.

1. Long press the badge (hold for approximately half a second)
2. A red lock icon will appear, indicating Profile 2 is active
3. KeepAlive restarts using Profile 2 settings

To return to Profile 1, tap the badge to deactivate KeepAlive. The next short tap activation will use Profile 1 again.

### Switching the Master Tab

The master tab can be transferred to any other YouTube or Vimeo tab:

1. Go to another YouTube or Vimeo tab
2. Tap the badge on that tab
3. The previous master tab releases automatically, and the new tab becomes the master

Only one tab can be the master at any time.

### Visual Indicator Reference

| Badge Appearance | Meaning |
|------------------|---------|
| Empty circle | KeepAlive is available but not active on this tab |
| Circle with white lock | This tab is the master, Profile 1 is active |
| Circle with red lock | This tab is the master, Profile 2 is active |

---

## Profile Configuration

### Understanding the Two Profiles

The script includes two configurable profiles:

- **Profile 1** is designed for normal use (lower battery usage).
- **Profile 2** is designed for aggressive protection (higher battery usage).

You are encouraged to experiment and share your profile settings with the community.

### Where to Find the Configuration

The profile configuration is located near the top of the userscript:

1. Open Tampermonkey's dashboard
2. Find **"MIUI Browser Tab KeepAlive"** and click to edit
3. Locate the `PROFILE_1` and `PROFILE_2` objects near the top of the code
4. Modify values as needed
5. Save the script

### Parameter Reference

Each profile contains the following parameters:

#### Video KeepAlive

| Parameter | Type | Description |
|-----------|------|-------------|
| `VideoKeepAlive` | Boolean | Enable/disable Video KeepAlive (hidden video + MediaSession). |
| `VideoKeepAliveAllowInput` | Boolean | Allow pause/play from notification controls. `false` = ignores pause commands and resumes automatically. `true` = can be paused and resumed via notifications. |
| `canvasStreamFps` | Number | FPS for the canvas-based hidden video stream. Higher values create more activity but use more battery. Typical range: `0.1` to `2`. |
| `muted` | Boolean | Whether the hidden video is muted. For silent operation set `true`. |
| `volume` | Number | Video volume (0 to 1). Usually keep at `0`. |

#### Audio KeepAlive

| Parameter | Type | Description |
|-----------|------|-------------|
| `AudioKeepAlive` | Boolean | Enable/disable Audio KeepAlive (hidden audio + MediaSession). |
| `AudioKeepAliveAllowInput` | Boolean | Allow pause/play from notification controls. `false` = ignores pause commands and resumes automatically. `true` = can be paused and resumed via notifications. |
| `AudioFrequencyHz` | Number | Tone frequency in Hz. For quiet/less noticeable output, try high values like `18000`. |
| `AudioGain` | Number | Tone loudness multiplier. Use very small values like `0.000001` to keep it effectively silent. |
| `AudioResumeIntervalMs` | Number | Audio resume interval, if it somehow stops (`0 = off`). |

#### KeepAlive Priority / Fallback

If **both** `VideoKeepAlive` and `AudioKeepAlive` are enabled, this decides which mode is started first:

| Parameter | Type | Description |
|-----------|------|-------------|
| `KeepAlivePriority` | String | `'video'` or `'audio'`. Primary mode if both are enabled. |

#### MediaSession Refresh

MediaSession refresh periodically re-asserts the media notification. Some apps may stop playback when this is enabled.

| Parameter | Type | Description |
|-----------|------|-------------|
| `mediaSessionRefresh` | Boolean | Enable/disable MediaSession refresh (some music playing apps will stop playing!). |
| `mediaSessionRefreshIntervalMs` | Number | How often to re-assert. If set to `0` and `true`, it is asserted once at activation. |

#### Retry Watchdog

The retry watchdog restarts KeepAlive if the active mode stops.

| Parameter | Type | Description |
|-----------|------|-------------|
| `retryWatchdog` | Boolean | Restart KeepAlive if Audio/Video stops. |
| `retryDelayMinMs` | Number | Minimum delay between retries (ms). |
| `retryDelayMaxMs` | Number | Maximum delay with exponential backoff (ms). |

#### Web Lock

| Parameter | Type | Description |
|-----------|------|-------------|
| `webLock` | Boolean | Holds an exclusive Web Lock to make the tab look less idle (low-cost mechanism). |

### Tuning Strategy

A practical strategy to find your optimal settings:

1. **Start with defaults** and observe if Profile 1 survives your normal usage.
2. **If Profile 1 fails**, try Profile 2 (long press).
3. If you still see reloads:
   - Try **Audio KeepAlive** instead of Video KeepAlive (or vice versa)
   - Increase `canvasStreamFps`
   - Enable `retryWatchdog`
4. Adjust values to minimize battery usage once you have a stable setup.

---

## Limitations and Known Issues

**Runs only on YouTube and Vimeo**: The script is designed to run on supported media pages. You can add more `@match` patterns if you want it on other sites.

**Requires one YouTube or Vimeo tab open**: You need at least one supported tab available to run KeepAlive.

**Not a complete guarantee**: Extremely aggressive battery saver modes or critically low memory situations may still cause your browser to be killed.

**Visible media notification**: The **"Video KeepAlive"** / **"Audio KeepAlive"** entry in your media controls is intentional and necessary, but may interfair with other media playing.

**Some browsers may block YouTube userscripts**: If your browser prevents userscripts from running on YouTube, use Vimeo as an alternative.

**Loses effect while media is played in another app**: The workaround relies on the browser’s media notification to appear “active” to the OS. When another app takes over audio/video playback, this signal is replaced and the keep-alive can no longer be maintained. Short playback in another app may sometimes work by chance, but this cannot be relied on.

---

## Troubleshooting

### The badge does not appear on YouTube or Vimeo pages

- Verify Tampermonkey is installed and enabled
- Check the script is enabled in Tampermonkey's dashboard
- Refresh the page
- Ensure you are on `youtube.com`, `m.youtube.com`, or `vimeo.com`
- Some browsers may block userscripts on certain sites — try Vimeo if YouTube does not work

### The KeepAlive media notification does not appear

- Complete the **Initial Setup** (play and pause a video once)
- Check your browser's media/notification permissions (varies by browser/ROM)
- If Audio KeepAlive is enabled and your browser blocks autoplay, tap **"Start Audio KeepAlive"** when it appears

### Tabs still reload after switching apps

- Try Profile 2 (long press)
- Increase `canvasStreamFps`
- Enable `retryWatchdog`
- Try switching between Video KeepAlive and Audio KeepAlive
- Make sure your browser is excluded from battery optimization (MIUI/HyperOS settings vary by device)
- Follow the optimization steps on dontkillmyapp.com for your device/ROM

---

## Tested Devices

| Device | ROM | Browser | Status |
|--------|-----|---------|--------|
| Xiaomi MI 11 Ultra | HyperOS | Firefox Mobile | Working |

If you have tested on other devices or browsers, please open an issue or pull request to add your configuration.

---

## Community and Configuration Sharing

Finding the optimal profile settings for your device requires experimentation. Since every device, ROM version, and browser behaves differently, sharing your experiences helps other users.

When sharing your configuration, please include:
- Device model
- ROM version
- Browser
- Your `PROFILE_1` and `PROFILE_2` settings

**Reddit Discussion Thread:**
https://www.reddit.com/r/Xiaomi/comments/1qlm81b/fixno_rootadb_miuihyperos_keeps_killing_your/

**GitHub Repository:**
https://github.com/DJ-Flitzefinger/miui-browser-tab-keepalive

---

## License

GNU General Public License v3 (GPL-3.0-or-later)

---

## Support

Buy me a coffee if you found this script helpful!

https://paypal.me/DJFlitzefinger

miui-browser-tab-keepalive

Today's picks

Was this content helpful?

Recent Feedback

miui-browser-tab-keepalive

Today's picks

Was this content helpful?

Recent Feedback

Download README