DEV Community: hammi

My 1.17 MB player's catalog grid: the channelId trap, overlapping pages, and a cursor echo

hammi — Sat, 07 Nov 2026 22:35:40 +0000

My 1.17 MB player's catalog grid: the channelId trap, overlapping pages, and a cursor echo

Disclosure: I built RKMovies, a 1.17 MB Android 4K media player (plus a Windows build). This is a dev diary about the listing layer. Get the Android APK.

The player is a thin WebView over a catalog API. There is no backend of ours for listings, the app calls the upstream /api/filter through its proxy. Getting the grid right taught me three things about that API.

1. channelId is not optional. The routes map to channels: /movies is channelId: 1, /tv-series is 2, /animated-series is 1006 with genre=Anime pinned. Omit the param and the upstream silently defaults the channel, so you get movies and TV mixed together with no error anywhere. Tile links carry tabId=2 / tabId=5 instead of a channel, so the client derives it (tabId=2 becomes channelId=1, tabId=5 becomes 2). One more quirk: the Movies lane never sends year at all, because the upstream year feeds are junk-heavy.

2. Pages overlap, and the real cursor hides one level down. The proxy consumes several upstream pages per client page (30 cards each) because it filters out junk re-uploads server side. It hands back an upstream cursor, pager.upNext, which the client has to echo as up= on every request with page > 1. Skip that and infinite scroll re-serves the same raw pages. And upstream pages overlap by a card or two, so before appending anything we dedupe by detailPath:

const have = new Set(STATE.items.map(x => x.detailPath));
const fresh = items.filter(x => x.detailPath && !have.has(x.detailPath));
STATE.items = STATE.items.concat(fresh);
STATE.upCursor = d.data.pager?.upNext || null;

3. Infinite scroll is just an IntersectionObserver with a loading guard. A sentinel div, rootMargin: '300px' so pages load before you hit the bottom, and a _scrollLoading flag flipped while a fetch is in flight so the observer cannot fire twice.

The filter bar is a custom dropdown component: button plus menu plus a hidden native <select> for semantics, closed on outside click or Escape. The whole listing layer is about 280 lines in parts/app-listing.js with zero dependencies, which is a big part of why the APK stays at 1.17 MB.

If you are building against someone else's undocumented JSON API: send the params they imply but never document, expect overlapping pages, and echo back cursors you do not understand. The real pagination contract usually hides one level down.

Try the player: a sub-2 MB webview player for old phones, install it on Android, or run it on your laptop.

How my 1.17 MB PWA updates itself without an app store (7-endpoint config fan-out + a strict service worker)

hammi — Sat, 07 Nov 2026 01:53:35 +0000

I build RKMovies, a small 4K media player that ships as a 1.17 MB Android APK and as a PWA on our own site. No Play Store means no update channel. So when we want to change a notice, a download link, or bump the version prompt, the app has to fetch config at runtime.

Here is what we landed on in updater.js and sw.js.

The config fan-out

fetchConfig() fires 7 GET requests concurrently: raw.githubusercontent.com, cdn.jsdelivr.net, our own domain, a Cloudflare Pages mirror, rentry, paste.ee, and a local /config.json. Every request gets an AbortController with a 4-second timeout and cache: "no-store". A response only counts if it parses as JSON and has at least one of platforms, version, or notice.

The point of 7 endpoints is that any single host can be blocked, slow, or wrong. If our domain is unreachable from some ISP, jsdelivr still answers. If GitHub raw is slow, the Pages mirror answers. We then compare all valid configs, take the highest latest_version, and prefer the platform-specific version (android vs desktop) over the top-level one. The winner gets written to localStorage, and if all 7 fail we boot from that cache instead of nothing.

The service worker side

sw.js precaches an 8-file shell (index, styles, app.js, adgate.js, updater.js, the ArtPlayer vendor bundle, the manifest) under a versioned cache name like rkmovies-shell-v43, then skipWaiting() + clients.claim() so the new shell takes over on next load.

Fetch handling is network-first for same-origin static files, with one hard rule: code assets (app.js, style.css, vendor/, parts/) are only ever answered from an exact cache match. A new ?v= must never be served an old build, so a missed exact match returns a hard 503 instead of stale JS. Only non-code assets fall back to the cached shell with ignoreSearch.

What this buys

A 1.17 MB APK that can change its own download links, notices, and update prompts without a store release. The whole updater is one dependency-free file, and the config fetch is a plain GET of a static JSON file. No device ID, no analytics, no fingerprint. Update checks that don't track you are possible; we just had to make the "phone home" a dumb static file read.

Play with it: the tiny native player I build, sideload the Android APK, or grab the Windows setup exe.

Disclosure: I'm the developer of RKMovies. Size numbers come from the landing page's comparison table, not from marketing.

SRT is not WebVTT: shipping a subtitle converter in a 1.17 MB player

hammi — Fri, 06 Nov 2026 22:48:02 +0000

SRT is not WebVTT: shipping a subtitle converter in a 1.17 MB player

I'm the developer of RKMovies, an ultra-lightweight 4K media player client for Android and Windows (1.17 MB APK, 29.5 MB PC installer). This is a dev diary about the part nobody blogs about: subtitles.

The upstream sources serve a mix of .srt and .vtt files. SRT uses comma decimal separators in timestamps (00:00:01,500 --> 00:00:03,200), WebVTT requires dots. The player library only speaks VTT, so every caption track goes through a converter before it reaches the renderer.

captionVtt() fetches the track text. If it already starts with WEBVTT, it passes the header through but still cleans each cue line. Otherwise it parses SRT blocks: split on blank lines, drop the numeric index line, keep the block only if the timing line contains -->, convert commas to dots, and prefix the output with WEBVTT.

The cleaning half is cleanSubtitleText(). It strips SSA/ASS override tags like {\an8}, removes HTML-ish markup (<i>, <font color=...>, <v Speaker>), decodes entities (&,  , '), and turns <br> into real newlines. Most "broken subtitle" reports we got early on were just leftover markup tags rendering as literal text on screen.

For local files (.srt, .vtt, .ass uploads), fileToVtt() runs the same SRT parser over the file contents, so a downloaded subtitle file works with zero server round-trips.

On the render side I hook subtitleBeforeUpdate plus a MutationObserver on the .art-subtitle-line elements to re-clean whatever the library injects into the DOM. Font size, bottom offset and color are driven through CSS variables (--art-subtitle-font-size, --art-subtitle-bottom, --art-subtitle-color) that get recomputed on resize and orientation change, because subtitles on a 6-inch phone held at arm's length need to be bigger than on a TV.

Total cost: about 80 lines of JavaScript. Which is the point. In a player this small, features don't cost APK size, dependencies do. Subtitles in Hindi, Tamil, Telugu and English ship in the box, and the desktop app for the TV runs the same pipeline.

If you want to poke at it: the Android APK is 1.17 MB with MediaCodec hardware decode, and there is no account and no telemetry.

Dead stream mid-episode? My 1.17 MB player just falls down the quality list

hammi — Fri, 06 Nov 2026 20:07:26 +0000

Disclosure: I built RKMovies, a small 4K media player client for Android and Windows. This is a dev diary about one of its error paths. The landing page is RKMovies, with the 1.17 MB Android APK and the PC build.

Stream URLs die. A CDN edge returns 410 Gone, a signed URL expires an hour in, a proxy node has a bad day. In a 1.17 MB APK you do not get to ship ffmpeg. You get the system's MediaCodec through the WebView's video element, and its error event. So the player treats error as a signal, not a failure.

The handler is small (public/parts/app-player.js):

art.on("error", () => {
  if (art.seeking || (art.video && art.video.seeking)) return;
  const v = art.video;
  if (v && v.error && v.error.code === 1) return; // MEDIA_ERR_ABORTED is a normal seek abort
  const curTime = (v && typeof v.currentTime === "number") ? v.currentTime : (art.currentTime || 0);
  const i = list.indexOf(STATE.selRes);
  if (i > -1 && i < list.length - 1) {
    toast("Stream failed - trying another quality");
    STATE.selRes = list[i + 1];
    const updatedRec = Object.assign({}, rec || {}, { pos: curTime, watched: false });
    renderPlayer(shell, s, updatedRec);
  } else {
    toast("This source failed to play.");
  }
});

The first guard matters most. MEDIA_ERR_ABORTED (code 1) is filtered out because every seek fires an aborted load on the old source. Without that check the player would "recover" from every scrub the user does.

Position is preserved. curTime gets written into the watch record, and renderPlayer re-seeks on ready when pos is past 10 seconds. The user loses about a second of buffer, nothing else.

The stream list is sorted by resolution descending, so list[i + 1] is the next lower quality. Falling down the ladder beats dying: a 1080p stream with a hiccup still plays, while nothing at all does not. If the error fires on the last entry in the list, the UI just says the source failed.

One level up, the play call itself gets a silent retry (public/app.js): two attempts with a 2.6 second pause between them, because the proxy already retries internally and this only covers a full 502 burst. If both attempts fail, the UI shows "Stream not available for this title" and adds "(limited region)" when the API flags it.

The honest trade-off: on very old phones, software decode of a high bitrate fallback can still stutter. Hardware decode is what makes the fallback actually smooth, which is also why the APK stays at 1.17 MB. No bundled codec libraries, system codecs only (MediaCodec on Android, NVDEC/QuickSync in the Windows build).

If you want to poke at the error path yourself, grab the APK or the Windows installer.

The 12-second 'up next' countdown in my 1.17 MB player: auto-advance without the annoyance

hammi — Fri, 06 Nov 2026 18:43:30 +0000

i'm the dev behind RKMovies, a 1.17 MB Android media player with a Windows build. this is how the auto-next-episode thing works.

most players either jump to the next episode instantly or leave you to dig through menus. i wanted something in between: a small overlay on the video that counts down "up next S1E12 in 12s", with a button if you're impatient.

how it works:

progressTick() runs on every timeupdate. at 92% of the episode it marks the ep watched and saves progress. every 15 seconds of playback it saves position too, so a crash never costs more than that.
when playback ends, onEpisodeEnd() fires once (a flag guards the double-fire, since both ArtPlayer's video:ended and the raw video element emit it). if auto-next is off in settings, that's the end of it.
otherwise showNextOverlay() paints the countdown inside the player host. a 1s ticker counts down from 12; at zero, autoNext() takes over.
autoNext() picks the next ep in the current season, or rolls over to ep 1 of the next season, then calls watchEp(). movies (single season, se=0) never auto-advance, and if you've left the detail page it bails.

the edge cases that actually bit me: the overlay has to live inside the re-parented fullscreen node or it vanishes in fullscreen. a scrubbing guard skips progress ticks while you drag the seek bar. and if you seek back below the end after the countdown started, the timer cancels and the ep can re-arm it when it really ends.

try it out: this 1.17 MB player, the tiny Android build, and the Windows app for the TV setup.

how i got real picture-in-picture in a 1.17 mb webview player without shipping a native lib

hammi — Fri, 06 Nov 2026 04:08:28 +0000

i'm the developer of rkmovies, a 4k media player that runs as a web app inside a thin android webview shell. the whole apk is 1.17 mb because it bundles zero native media libraries. playback uses the system's mediacodec decoders through artplayer.

one feature people asked for constantly: picture-in-picture. you open whatsapp mid-episode and the video keeps playing in a floating window.

in a webview you can't call an android api directly. you only get what the browser engine exposes. so the pip toggle in the settings menu is a four-layer fallback chain:

if document.pictureInPictureElement is set, the video is already in pip. call exitPictureInPicture() to toggle off.
otherwise try art.video.requestPictureInPicture(). that's the w3c api, and chrome supports it from android 8. inside a webview it gives you the real system pip window with the app icon, not a canvas hack.
if that's missing (older webview, weird oem rom), fall back to webkitSetPresentationMode("picture-in-picture"), the safari-style api some chromium builds still expose.
if all three are absent, flip art.pip. that's artplayer's own software pip, which re-parents the video element into a small overlay. it works everywhere but it's not a real system window, so no controls outside the app.

every step is wrapped in try/catch because webview implementations throw different errors instead of returning undefined. i learned that the hard way on a budget micromax device.

the whole chain costs zero bytes of apk size because it only calls apis the platform already has. that's the general pattern in this app: features don't cost size, dependencies do.

if you want to poke at it, this little player lives at this little player, grab it on android at grab it on Android, or take the pc installer from the PC installer

artplayer v5 re-parented my fullscreen node and moved my controls on phones

hammi — Wed, 04 Nov 2026 22:15:47 +0000

Disclosure: I'm the developer of RKMovies, an ultra-lightweight 4K media player client for Android and Windows (a player this small).

Upgrading ArtPlayer from v4 to v5 looked like a one-line change. It was not. v5 restructured the player DOM: the control bar is now split into a top strip (.art-mobile-top) and a bottom strip (.art-bottom), and fullscreen no longer keeps the player node where you put it. fullscreenWeb re-parents template.$player into <body>.

The first bug was invisible. Our gesture HUD and overlays lived next to the player node, so in fullscreen-web they just vanished while the video kept playing. The fix was a playerHost() helper that resolves the node ArtPlayer actually fullscreens (art.template.$player, falling back to .artplayer-app .art-video-player) and mounts every overlay inside it. Native fullscreen and web fullscreen now behave the same.

Second surprise: on phones the library renders its own top bar, which collided with our HUD. So under @media(max-width:767px) we hide .art-control-cc, .art-control-pip and .art-mobile-top, pin .art-bottom to bottom: 0, and re-anchor the settings panel above the control bar with calc(var(--art-control-height, 44px) + 6px). The settings max height is per-device too: art.cssVar("--art-settings-max-height", isMobileDevice() ? "150px" : "260px").

Third: v5 takes type as a plain string now ("m3u8" / "mp4") instead of a custom type function, so source detection collapsed to one ternary: (format === "HLS" || /\.m3u8/.test(url)) ? "m3u8" : "mp4". Touch-only controls are gated on device class as well: fastForward: isMobileDevice(), flip: !isMobileDevice().

All of this ships inside the sub-megabyte android apk. The DOM gymnastics cost zero bytes because we borrow the system codecs and the player library instead of bundling our own. There's also a tv-friendly windows build.

Lesson: when a player library changes its DOM, read its template source, not just the changelog. The fullscreen re-parenting was only documented in a source comment, and it cost us a day of "why did my overlays disappear" bug reports.

Parsing SRT subtitles in the browser: the 30-line converter that makes every WebVTT player happy

hammi — Wed, 04 Nov 2026 21:13:18 +0000

Parsing SRT subtitles in the browser: the 30-line converter that makes every WebVTT player happy

Disclosure: I'm building RKMovies — an ultra-lightweight 4K media player client (0.91 MB APK, hardware-accelerated decoding, zero telemetry). Site: https://rkmovies.dpdns.org · Android APK: https://rkmovies.dpdns.org/apk · Windows app: https://rkmovies.dpdns.org/desktop

Every video player on Android that is worth using speaks WebVTT. Almost every subtitle file floating around the internet is SRT. They look identical at a glance, but the parsers do not forgive the differences.

The gap is small and annoying:

SRT uses a comma in timestamps (00:00:01,500), WebVTT demands a dot (00:00:01.500)
SRT cues start with an optional numeric index line, WebVTT does not have one
SRT files often ship with a BOM and CRLF line endings

So instead of pulling in a subtitle library (remember: the whole APK is 0.91 MB, every dependency is a size audit), I wrote a tiny converter that runs in the browser when a local subtitle file is loaded:

async function fileToVtt(file) {
  let t = await file.text();
  t = t.replace(/\r/g, "").replace(/^/, "");
  if (/^\s*WEBVTT/.test(t)) return t;
  const out = [];
  for (const b of t.split(/\n{2,}/)) {
    const lines = b.split("\n").filter(l => l.trim() !== "");
    if (/^\d+$/.test(lines[0]?.trim())) lines.shift();
    const tl = lines.shift();
    if (!tl || tl.indexOf("-->") < 0) continue;
    out.push(tl.replace(/,/g, ".") + "\n" + lines.join("\n"));
  }
  return out.length ? "WEBVTT\n\n" + out.join("\n\n") + "\n" : "";
}

The whole thing is ~20 lines. It reuses the same cleanup pass we already run for inline captions (stripping tags like <i> and positioning junk), then hands the result to the player as a Blob URL. From the user's side: pick an .srt file, it just works.

Two edge cases that actually bit me in testing:

Some SRT files use LF only, some CRLF, some have a BOM. Normalizing all three up front saves a "why are my subtitles empty" bug report.
Multi-line cues must stay multi-line. If you flatten them, dialogue and sound effects merge into one unreadable line.

If you are shipping a small player and want subtitles without a dependency, this is the whole trick. WebVTT is forgiving once the commas become dots.

RKMovies runs this on Android (0.91 MB APK with hardware decoding and multi-audio support: https://rkmovies.dpdns.org/apk) and on Windows (https://rkmovies.dpdns.org/desktop). No account, no telemetry.

our windows build ships no browser: how a ~31 mb launcher gets free nvdec/quicksync 4k decode

hammi — Wed, 04 Nov 2026 20:04:07 +0000

Disclosure: I'm the developer of RKMovies, an ultra-lightweight 4K media player client for Android and Windows (the landing page).

Every Electron app bundles its own Chromium, which is why "desktop video player" installers weigh 150-300 MB. We went the other way.

Our Windows installer (~31 MB) is a PyInstaller bundle of the FastAPI backend plus a launcher. On startup it finds the real Chrome or Edge through the registry (App Paths\chrome.exe / msedge.exe), then spawns it with:

--app=http://127.0.0.1:<port>
--user-data-dir=%APPDATA%\RKMovies\profile

Result: a chromeless window that looks native, our own taskbar icon (SetCurrentProcessExplicitAppUserModelID), an isolated profile, and zero bundled browser engine.

The payoff is decode. Chrome and Edge on Windows already drive NVDEC (NVIDIA), QuickSync (Intel) and DXVA (AMD) for H.264 / HEVC / AV1. Since the video element lives in that borrowed browser, 4K hardware decode is simply there. We ship no decoder of our own. A 10-year-old laptop plays 4K HEVC smoothly because the GPU work happens inside Chrome, not inside our 31 MB exe.

Fallback chain when neither browser exists: pywebview, then the system default browser. The Android side is the mirror image: MediaCodec through ArtPlayer, no engine bundled either, which is how the 0.9 MB APK stays under a megabyte.

Trade-offs we accepted: desktop mode depends on a system browser being installed, and the "app" is really a local server plus a window. In exchange the installer stays ~31 MB and every update is a small download instead of a full Chromium re-bundle. Grab the Windows exe here if you want to see.

If you're building a small desktop tool: don't bundle a browser unless you have to. The system one is already there, already GPU-accelerated, and already updated.

Shipping multi-audio dubs in a 0.91 MB player without adding a single dependency

hammi — Wed, 04 Nov 2026 18:51:22 +0000

I'm building RKMovies, a tiny 4K player (0.91 MB APK on Android, a native Windows build, hardware decode, no account, no tracking). Indian titles usually ship with several audio dubs — Hindi, Tamil, Telugu, English — and users expect to switch between them mid-playback without losing their position. Here's how that fits inside a sub-megabyte APK.

The whole feature is three pieces, all inside the player module:

Filter the dub list. Upstream play payloads mix real audio dubs with subtitle-language variants ("Arabic sub"). Anything ending in sub is not an audio option, so it gets filtered out before the picker renders.
Probe before you promise. When the audio panel opens, the app background-probes the other dubs and hides any that have no stream for the current episode. No dead buttons.
Swap in place. Switching audio does not reload the page. It fetches the dub's play data (cached), picks the best non-VIP stream, and hands it to the player's existing quality switch at the same timestamp, so playback continues from the exact position. Subtitles reset and refetch, because they belong to the dub's resource, not the video.

async function switchDubStream(d) {
  let data = dubPlayCache[d.detailPath];
  if (!data) {
    const res = await API(`play?subjectId=${d.subjectId}&se=${se}&ep=${ep}&detailPath=${d.detailPath}`);
    data = res?.data;
    dubPlayCache[d.detailPath] = data;
  }
  const list = data.streams?.length ? data.streams : (data.hls || []);
  const pool = list.filter(x => !x.vipLocked && x.url)
                   .sort((a, b) => (parseInt(b.resolutions) || 0) - (parseInt(a.resolutions) || 0));
  smoothSwitchQuality(pool[0], true); // same position, no navigation
  loadSubtitles();                    // subs belong to the dub, not the video
}

The size cost is basically zero: no HLS demuxer, no extra library. The player already has a quality switcher, so a dub switch is just "pick a different stream URL and send it down the same path". The picker UI is a plain DOM list, not a component framework.

Lesson: features don't cost APK size, dependencies do. Reuse the machinery you already have.

Try it: media player for low-end Android, native Windows app.

My auto-hide controls kept flickering in ArtPlayer v5: the dual-timer fight and the 1.5s immunity fix

hammi — Tue, 03 Nov 2026 21:54:18 +0000

I'm building RKMovies (a tiny 4K player for old phones) — 0.91 MB APK, hardware decode, no accounts, no tracking. The player UI runs on ArtPlayer v5, and I replaced its default controls with my own auto-hide layer. That layer flickered for weeks. Here's why.

ArtPlayer hides its controls on its own timer. Every timeupdate it checks controls.timer; if the controls have been idle for a few seconds it hides them and hides the cursor.

I wanted different rules: never hide while the settings panel is open, while paused, or while the user is scrubbing, plus a minimum visible time of 1s. So I added my own hideTimer (3.5s) with those guards.

Two timers, two sources of truth. ArtPlayer's internal check and my setTimeout disagreed about when to hide, so the controls flickered: my layer showed them, the library's next timeupdate hid them, mine showed them again.

The fix wasn't a second timer fighting the first. It was a 1.5s immunity lock. Every time my layer shows the controls it sets wakeLockUntil = Date.now() + 1500, and hideControls() refuses to run inside that window unless forced (video ended). Then, on every video:timeupdate, if we're inside the immunity window I poke the library's own timer: art.controls.timer = Date.now(). The library thinks the user just interacted and leaves the controls alone. One timer owns hiding; the other just gets told to stay quiet.

const HIDE_TIMEOUT_MS = 3500;
let wakeLockUntil = 0;

function showControls() {
  wakeLockUntil = Date.now() + 1500; // immunity lock
  art.controls.timer = Date.now();
  scheduleHide();
}

function hideControls(force = false) {
  if (!force && Date.now() < wakeLockUntil) return;
  if (!force && Date.now() - lastShowTime < 1000) return;
  if (!force && isMenuOpen()) return;   // settings / context menu
  if (!force && art.video.paused) return;
  if (!force && isScrubbing()) return;
  // ...actually hide
}

art.on('video:timeupdate', () => {
  if (Date.now() < wakeLockUntil && art.controls) {
    art.controls.timer = Date.now(); // keep the library's idle check happy
  }
});

Guards that matter in practice: the settings panel (art-setting-show class or clientHeight), the context menu, paused state, and the .art-scrubbing class on the player element. Miss one and the controls vanish mid-drag, which feels broken.

I also overrode art.controls.toggle to route through my show/hide instead of the default flip, so taps behave the same everywhere.

Lesson: when you wrap a player library's internals, don't run a parallel timer. Patch the value the library reads (controls.timer) and keep a single owner for the hide decision. The code lives in setupControlsAutoHide() in the app's player module.

If you want to try it: gesture-controlled video player for Android, the Windows edition for PC.

I fake screen brightness with a CSS filter, and only use the real API when the shell allows it

hammi — Tue, 03 Nov 2026 20:05:48 +0000

I'm the developer of RKMovies, a 0.91 MB media player for Android and Windows. One of the small features people ask about is the brightness gesture: swipe up on the right half of the player and the screen dims.

Here's the thing though. There is no one brightness API that works everywhere my app runs. So I built a two-layer one.

Layer 1: the native path, when it exists

On Android the WebView shell exposes a JS bridge. If window.AndroidBridge.setBrightness exists, I call it and I'm done. That changes the actual system brightness, which is what you want most of the time.

On the Windows build there's a local backend, so I debounce and fire GET /api/system/brightness?val=... instead. 50 ms debounce, because the gesture fires dozens of times per second and I don't want to flood the IPC.

Layer 2: the CSS filter fallback

WebViews and browser contexts can't touch system brightness. So every time the gesture moves, I also set a filter directly on the <video> element:

function applyPlayerBrightness(art, val) {
  const clamped = Math.max(0.1, Math.min(1.5, Math.round(val * 100) / 100));
  art._brightness = clamped;
  if (art.video) {
    art.video.style.filter = "brightness(" + (0.4 + clamped * 0.7) + ")";
  }
  setSystemBrightness(Math.min(1.0, clamped)); // native layer, clamped to 0..1
  // ...HUD update
}

Note the math: user-facing range is 10% to 150%, but the filter maps it to 0.4x to 1.45x. I never go below 0.4. A pure black screen feels broken, not dim, and people think the app crashed. 0.4 is the floor where the picture is still readable.

The filter only darkens/brightens the video itself, not the player UI. That's actually a feature: the controls stay readable while the movie dims, which is exactly what you want at 2am under a blanket.

Why not just use the native API everywhere

Because "everywhere" is a lie. Android WebView: no. Windows WebView2: no (hence the local backend). Plain browser PWA: no. If I depended on the native path alone, the gesture would silently do nothing on two of my three platforms.

The filter runs on the compositor, so it costs basically nothing on the CPU. On a low-battery video player that's the whole point. I'd rather spend zero battery on brightness and keep the decoder on the GPU.

The edge case nobody warns you about

CSS filter on a hardware-decoded video can force a software compositing path on some old GPUs, which tanks battery. I tested on a 2GB Redmi and a Moto G4 and the filter stayed on the compositor, but if you ship this, test on your lowest-end device. If it falls off the fast path, drop the filter layer and keep only the native API.

The desktop edition uses the same two-layer code, just with the local /api/system/brightness endpoint as layer 1 instead of the Android bridge.

If you're building a player and want gesture brightness without a native app, this split is the cheapest version that actually works everywhere. Ship the filter first, add the native path when the shell gives you one.