A tiny screen dimmer and warm (red) filter for Android TV boxes, projectors and TVs that can be controlled live from ADB or Home Assistant, as well as with the TV remote.
It draws a click-through overlay above everything, video included, like the usual blue-light filter apps. The difference is that changes apply instantly, with no flash to full brightness. Other filter apps usually have to be restarted to pick up new values from automation tools.
- Live control from
adb shell/ Home Assistant: warm filter, brightness, colour temperature - Phone remote: scan a QR code on the TV and control it from any phone browser (Android or iPhone), no app to install; the page works offline, on the local network only
- Phone app mode: on a phone or tablet the app itself is the remote page, for the phone's own filter and for every TV you saved
- Daily or weekly schedule: a timeline of time slots (movie night, early to bed…) that the TV applies by itself, even with the phone off; shown as a bar at the bottom of the TV screen, where the remote moves the slot edges (left/right pick an edge, OK grabs it, left/right move it by 10 minutes, OK saves, Back undoes)
- Remote-friendly settings screen: only D-pad and OK are needed, with a visible focus highlight for the many TV-box themes that show none; a collapsed Advanced section switches the schedule on/off, sets its gradual change and holds the audio settings (volume, equalizer, bass, surround, loudness)
- Restores the last setting at boot, early: the boot receiver has a high priority, because on some boxes
BOOT_COMPLETEDreaches apps one at a time and can take over a minute - Small: ~350 KB APK (most of it fonts and artwork), plain Java, no tracking; no internet connections: the network is used only by the optional LAN remote (port 8765, pairing key, off unless enabled) and, in phone app mode, to reach your paired TVs
- Android 8.0+ (API 26), phones work too
The TV screen at 1080p: controls, test image and phone remote on one screen, the schedule below; the focused row lights up gold.
Effect on a test pattern, simulated with the same colour and blending formula the app uses
(real screen captures do not include overlays on many TV boxes).
New in 1.7: the "Arcade" look, gold and oxblood red on wine black with Bungee, Chivo and Silkscreen; sliders coloured by their setting; the TV screen fits on one page, with Advanced opening across the bottom; a new icon (a tiny saucer painting the moon red with its laser) and new artwork.
New in 1.6: no blue anywhere in the interface (warm blacks, red and amber), a new phone app (welcome screen, Home, Devices, Scenes, Settings) and dayrhythm 0.3.0.
New in 1.5: the app is now called MidnightBeam (new package id dev.midnightbeam, so the previous
RedMoonBeam app has to be uninstalled and this one installed; settings are not carried over), with new artwork.
The old name was too close to the existing Red Moon app.
-
Download
midnightbeam.apkfrom the latest release. -
Install and allow drawing over other apps:
adb install midnightbeam.apk adb shell appops set dev.midnightbeam SYSTEM_ALERT_WINDOW allowWithout ADB: install the APK with a file manager, then enable Settings → Apps → Special app access → Display over other apps → MidnightBeam.
-
Open MidnightBeam from the app list once and set it up.
Versions up to 1.12.0 targeted Android 9, so Google Play Protect could show an "unsafe app" / "built for an older version of Android" warning on Android 12 and later. From 1.12.1 the app targets Android 15 and the warning should not appear.
At start the app checks the GitHub releases and, when a newer version is out, asks whether to install it (Android
still shows its own confirmation). Don't ask again + Update installs future updates without our question; Don't ask
again + Not now turns the check off. In the settings (TV screen and phone app) Check for updates at start turns it
on or off and Beta updates chooses the channel (on by default when the installed version is a beta). Turning beta off
on a beta stays on it until a newer stable is out, because Android cannot downgrade. Never active on F-Droid installs.
F-Droid builds (SIGN=0 or FDROID=1) leave the updater and its permission out.
Open the app from the launcher:
| Key | Action |
|---|---|
| Up / Down | move between the switch and the sliders |
| Left / Right | change the focused value (applied immediately) |
| OK | switch the filter on / off |
- In the app on the TV, turn on Phone remote and press Pair a phone: a big QR code opens in the middle of the screen, with a 4-digit code under it (Android app opens the QR code of the app download the same way).
- Scan it with the phone camera. The page opens in the browser; Add to Home screen makes it an app icon.
- Move the sliders or pick a preset: the TV follows instantly.
- Schedule (built with dayrhythm): pick a day preset, tap a time slot to choose its setting (a profile or a custom one), rename or remove it, add slots, drag the edges between slots to set the times. Every change is saved to the TV automatically; there is no Apply button. The TV switches slot by itself; a manual change lasts until the next slot. Save this day keeps a named day on the TV, available to every paired phone.
- Transition (Off, 15, 30 or 60 minutes): values glide gradually into the next slot.
- Weekly mode: switch from Same every day to Per weekday to give each weekday its own slots (with a copy-to-other-days shortcut).
- Add to Home screen: the page has a button that installs it as an app icon (on iPhone: Share, then Add to Home Screen).
On a phone or tablet, the launcher opens the app's own screen (app/assets/app.html in a WebView, served by the
app on 127.0.0.1:8765 only). The first time it asks whether to use the filter on this device or to
connect a TV or projector. Then:
- Home: the selected device with its power button, a test image under the filter (white page with text, blue sky, colour patches with a skin tone, grey ramp; for a TV it shows the same overlay the TV draws, hold it to see it without), scenes, the warm filter / brightness / colour temperature sliders and the schedule (with dayrhythm).
- Devices: this phone and every saved TV, with their state and a power button each; tap one to control it, the ⋯ button renames or removes it, or Apply to… copies its filter settings and schedule (with saved days) to the devices you choose. Sync all devices sends every change to all saved TVs at once (this phone excluded). The app forwards the requests to the TV with its saved pairing key (the page never sees the keys).
- Scenes: the built-in settings plus your own (saved on the phone).
- Settings: language, the Display over other apps permission, the optional accessibility mode.
Pairing a TV: scan its QR code. The code is still the plain http://IP:8765/#k=KEY link, so without the app
it just opens the browser remote. With the app installed the link opens the app (on older Android you may
need to allow it in Settings → Apps → MidnightBeam → Open by default) and saves the TV; the link can also be
pasted in Devices → Add device, or typed there as the TV's address plus the 4-digit code from the Pair a phone
popup. The browser remote has an Open in the app button that does the same
(midnightbeam://add?host=…&port=…&k=…&name=…) or, if the app is not installed, opens the download page.
Finding the TVs (like the WLED app): a TV with Phone remote on announces itself on the local network with
mDNS / DNS-SD (_midnightbeam._tcp, with its name, its type and a random id; never the pairing code). While the
phone app is open it listens for them: TVs not saved yet appear in Add device → Found on your network (tap one and
type the 4-digit code from its Pair a phone popup), and a saved TV that got a new address (DHCP after a reboot) is followed at once.
Where mDNS is blocked, the app falls back to looking for the TV's port on the phone's /24 network with the saved code.
The TV screen and the browser remote keep their own layout.
The page is in English, or Italian on Italian phones (switchable with EN | IT); the TV app follows the device language.
The QR code carries a random pairing key: requests without it are refused. New code in the TV's pairing popup
disconnects every paired phone. The 4-digit code is traded for the key (POST /api/pair {"pin":"1234"}) only
while the popup is open on the TV; 5 wrong codes lock that phone out until the popup opens again, and 20 wrong codes
in total change the code and close pairing. Settings changed from a phone show up live on the TV screen, and the
phone page follows changes made on the TV within a few seconds. The remote works only while the phone is on the same network as the TV.
HTTP API (port 8765, header X-Key: <pairing key>), handy for scripts:
curl -H "X-Key: $KEY" http://TV-IP:8765/api/info # {"name":..,"model":..}
curl -H "X-Key: $KEY" http://TV-IP:8765/api/state
curl -H "X-Key: $KEY" -H "Content-Type: application/json" -d '{"red":60,"bright":40}' http://TV-IP:8765/api/set
curl -H "X-Key: $KEY" http://TV-IP:8765/api/schedule
curl -H "X-Key: $KEY" http://TV-IP:8765/api/daysGET /api/audio returns {"supported":bool,"enabled":bool,"eq":{"bands":[{"freq":Hz,"level":mB}],"min":mB,"max":mB,"presets":[..]},"bass":{"strength":0-1000},"virt":{"strength":0-1000},"loud":{"gain":0-1500}}, where an effect the device cannot provide is null. POST /api/audio takes any subset of {"enabled":bool,"bands":[mB,..],"preset":index,"bass":n,"virt":n,"loud":n,"reset":true} and answers with the new state. The effects are applied to the whole audio output (global audio session), so this only works on devices whose audio driver supports global effects, mostly TVs and projectors; elsewhere supported is false. While enabled, the service keeps running and restores the settings after a reboot.
Android pauses the global effects while the playing app enables an effect of its own (many video players use a loudness boost). Players that announce their audio session get the effects on that session; for the others, allow the app once to read which sessions are playing, and the effects follow them:
adb shell pm grant dev.midnightbeam android.permission.DUMPChanging an audio setting from the phone shows a short on-screen display on the TV (e.g. "Volume 45%").
Start it with 15, 30, 60 or 90 minutes from the TV screen (Advanced), the phone app or the web remote; POST /api/sleep takes {"minutes":n} to start, {"cancel":true}, and the settings {"fade":1-30,"power":"none|box|tv|both"}. In the last minutes (10 by default, all of it if the countdown is shorter) the filter fades towards the darkest and reddest and the media volume steps down to 0 (not on devices with fixed volume). At the end playback is paused and the chosen power action runs: box sends KEYCODE_SLEEP through root or local ADB (or locks the screen with the accessibility service), tv sends KEYCODE_TV_POWER (HDMI-CEC) and needs root or local ADB, both does TV then box. Whether the TV follows the box depends on the box's HDMI-CEC setting. On a Fire TV Stick (Fire OS 7) box works through the accessibility service, while tv and both do nothing: Fire OS ignores KEYCODE_TV_POWER and sends no CEC standby when the stick sleeps. Afterwards the volume and the filter come back as they were (so with none, a player that ignores the pause plays on at its old volume). The state (GET /api/state) carries sleepEnd, sleepLeft (seconds), sleepFade, sleepPower and sleepWebhook.
Optionally a webhook ({"webhook":"https://..."}, set from the phone app or the web remote, empty = off) is called with a POST ({"event":"sleep_end","device":"<name>"}) when the timer ends, before the power action (which waits for it at most 5 s): for example a Home Assistant automation with a webhook trigger, http://homeassistant.local:8123/api/webhook/<id>, that turns off the TV.
A schedule slot with the model Sleep does the same: the countdown starts by itself in the fade window before the slot and ends at the slot's time.
Android 12 blocks touches through an overlay of another app unless the overlay is at most 80% opaque (the system limit, InputManager.getMaximumObscuringOpacityForTouch()). MidnightBeam therefore caps the filter at that opacity, so the phone stays usable; /api/state and dumpsys report clamped when the requested darkness was limited.
For full darkness, covering the status and navigation bars, you can optionally enable MidnightBeam in Settings > Accessibility. The service only lends its window to draw the dimming overlay: it requests no access to window content, does not read the screen or your input, and sends nothing anywhere. Without it, everything works as described above.
On TVs the accessibility mode also matters on any Android version: the screensaver (Daydream) is drawn above normal overlays, so without it the screensaver shows unfiltered. The TV screen keeps a hint with an Enable button until the service runs. The button turns it on by itself if the app was allowed once with
adb shell pm grant dev.midnightbeam android.permission.WRITE_SECURE_SETTINGSotherwise it opens the Accessibility settings.
# warm filter 0-100, brightness 5-100 (100 = no dimming), colour temperature 1000-6500 K
adb shell am start-foreground-service -n dev.midnightbeam/.DimService --ei red 60 --ei bright 40 --ei temp 1100
# change a single value, the others are kept
adb shell am start-foreground-service -n dev.midnightbeam/.DimService --ei bright 70
# off
adb shell am start-foreground-service -n dev.midnightbeam/.DimService --ez off true
# phone remote on / off
adb shell am start-foreground-service -n dev.midnightbeam/.DimService --ez remote true
# current state
adb shell dumpsys activity service dev.midnightbeam/.DimServiceLower colour temperature means redder: 1000-1200 K is a deep red, 1800 K orange, 3000 K+ yellowish.
The service can only be controlled by the app itself and from adb shell / root. It is protected by the
DUMP permission, so other apps cannot change it.
The homeassistant/ folder has a ready-made example:
midnightbeam.yaml: package with sliders, presets and state sensors, using the built-in Android Debug Bridge integration (androidtv.adb_command)dashboard.yaml: example dashboardstatus.sh: optional script that prints the state as JSON for the sensors
Replace media_player.my_tv with your own entity and copy status.sh to the device:
adb push homeassistant/status.sh /data/local/tmp/midnightbeam-status.shOn devices that offer a privileged shell, the filter can be applied as a SurfaceFlinger colour matrix instead of an overlay: blacks stay black, contrast is kept, and the blue channel really reaches zero. It is off by default; the switch appears in Advanced on the TV and in the paired phone remote when one of these is available. The TV app executes the privileged command locally:
suthat the app itself can execute (Magisk or KernelSU): the system asks the owner once;- the device's own ADB on
127.0.0.1, used only when it needs no authorisation (ro.adb.secure=0, common on cheap TV boxes and projectors).
The first activation from the phone has a 15-second trial; the TV app reverts it unless you keep it. Nothing else is changed: no files are written, the matrix lives in memory, it is reset when the filter is turned off or the app stops, and a restart always clears it. If the app crashes the tint can stay on screen until the filter is turned off or the device reboots. On devices with neither source the switch is not shown and the normal overlay is used.
For reference, the commands it sends:
# red 1, green 0.6, blue 0 (16 floats, row-major 4x4), then back to normal
adb shell service call SurfaceFlinger 1015 i32 1 f 1 f 0 f 0 f 0 f 0 f 0.6 f 0 f 0 f 0 f 0 f 0 f 0 f 0 f 0 f 0 f 1
adb shell service call SurfaceFlinger 1015 i32 0DEV=1 ./build.sh builds a debuggable APK with a debug channel: the full app state (filter, overlay colour, schedule,
remote server, permissions, device, updater) plus the last 100 events, as JSON. Release builds answer nothing.
adb shell dumpsys activity service dev.midnightbeam/.DimService debug
curl -H "X-Key: <pairing key>" http://<tv-ip>:8765/api/debugNo Gradle. A JDK 17 and the Android SDK with build-tools and platform 35 are required:
BUILD_TOOLS=$ANDROID_HOME/build-tools/35.0.1 ANDROID_JAR=$ANDROID_HOME/platforms/android-35/android.jar ./build.shThe first build creates a local debug.keystore to sign the APK.
The schedule editor library is the git submodule vendor/dayrhythm: run git submodule update --init
(or clone with --recurse-submodules) before building. build.sh copies its plain ES module sources
(src/, nothing minified) into the APK as assets/dayrhythm/, and the phone page imports them as modules.
The phone remote page is web/remote.html, styled with Tailwind CSS compiled at development time
(web/build-css.sh, needs Node; sources: web/input.css, web/tailwind.config.js and the classes used in web/remote.html;
it also copies the page into app/assets/). The generated app/assets/remote.css is committed, so building the APK
does not need Node and the page has no CDN dependency. APKs signed with different keys cannot
update each other, so uninstall the release build before installing your own.
- It is an overlay: it darkens and tints the picture but cannot lower the real backlight or LED power.
- The colour comes from Tanner Helland's black-body approximation (source).
-
Bungee, Chivo and Silkscreen, SIL Open Font License 1.1 (
app/assets/fonts, subset to Latin; the license texts are next to them) -
QR Code generator library by Project Nayuki, MIT License (
app/src/io/nayuki/qrcodegen, unmodified) -
Tailwind CSS, MIT License (compiled into
app/assets/remote.css) -
dayrhythm, MIT License (git submodule
vendor/dayrhythm, v0.8.0, used unminified from itssrc/; the schedule editor of the phone page) -
Lucide line icons, ISC License (inside
vendor/dayrhythm/icons; the schedule's setting icons)
The look of the app (the Arcade theme, the phone page and the TV screen) was designed with the wonderful Hallmark.
Hallmark license (MIT)
MIT License
Copyright (c) 2026 Hallmark contributors
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
Lucide license (ISC)
ISC License
Copyright (c) 2026 Lucide Icons and Contributors
Permission to use, copy, modify, and/or distribute this software for any
purpose with or without fee is hereby granted, provided that the above
copyright notice and this permission notice appear in all copies.
THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
---
The following Lucide icons are derived from the Feather project:
airplay, alert-circle, alert-octagon, alert-triangle, aperture, arrow-down-circle, arrow-down-left, arrow-down-right, arrow-down, arrow-left-circle, arrow-left, arrow-right-circle, arrow-right, arrow-up-circle, arrow-up-left, arrow-up-right, arrow-up, at-sign, calendar, cast, check, chevron-down, chevron-left, chevron-right, chevron-up, chevrons-down, chevrons-left, chevrons-right, chevrons-up, circle, clipboard, clock, code, columns, command, compass, corner-down-left, corner-down-right, corner-left-down, corner-left-up, corner-right-down, corner-right-up, corner-up-left, corner-up-right, crosshair, database, divide-circle, divide-square, dollar-sign, download, external-link, feather, frown, hash, headphones, help-circle, info, italic, key, layout, life-buoy, link-2, link, loader, lock, log-in, log-out, maximize, meh, minimize, minimize-2, minus-circle, minus-square, minus, monitor, moon, more-horizontal, more-vertical, move, music, navigation-2, navigation, octagon, pause-circle, percent, plus-circle, plus-square, plus, power, radio, rss, search, server, share, shopping-bag, sidebar, smartphone, smile, square, table-2, tablet, target, terminal, trash-2, trash, triangle, tv, type, upload, x-circle, x-octagon, x-square, x, zoom-in, zoom-out
The MIT License (MIT) (for the icons listed above)
Copyright (c) 2013-present Cole Bemis
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
MidnightBeam collects no data and works on your local network, apart from the optional update check to GitHub: see PRIVACY.md.
If MidnightBeam is useful to you, you can support its development here: https://linktr.ee/made_in_Taly
