Skip to content

Open-source music player for YouTube Music's catalog, with genres, full albums and playlists. Windows, macOS, Linux, Android, iPhone and Docker. No account needed.

TypeScript

tv: precise spatial navigation (document-space geometry, rail scrolling, band preference, repeat throttle) and a friendlier 10-foot UI (animated focus ring, bigger type and targets)

vaha40afcf293cc0
diff --git a/web/src/tv/tv.css b/web/src/tv/tv.css
index 5b42c43..5316516 100644
--- a/web/src/tv/tv.css
+++ b/web/src/tv/tv.css
@@ -1,47 +1,75 @@
/* Android TV (10-foot) tweaks. Loaded only when html[data-tv="1"] is set. */
html[data-tv="1"] {
- --tv-ring: #c6f26a;
- font-size: 125%; /* everything a touch bigger for a 3 m viewing distance */
+ --tv-ring: #b6f36a;
+ --tv-ring-soft: rgba(182, 243, 106, 0.35);
+ font-size: 130%;
+ scroll-behavior: smooth;
}
html[data-tv="1"] body {
- overflow: hidden; /* no page scrolling: navigation moves focus */
+ overflow: hidden;
cursor: none;
+ -webkit-font-smoothing: antialiased;
}
-/* One clear focus ring on whatever the D-pad is standing on. */
+/* One clear, animated focus ring for the whole app. */
html[data-tv="1"] :focus {
- outline: 4px solid var(--tv-ring) !important;
- outline-offset: 3px !important;
- border-radius: 12px;
- z-index: 2;
+ outline: 3px solid var(--tv-ring) !important;
+ outline-offset: 2px !important;
+ border-radius: 14px;
+ box-shadow: 0 0 0 6px var(--tv-ring-soft), 0 18px 40px rgba(0, 0, 0, 0.45) !important;
+ transform: scale(1.035);
+ transition: transform 130ms ease-out, box-shadow 130ms ease-out, outline-color 130ms ease-out;
+ z-index: 3;
}
-html[data-tv="1"] :focus:not(:focus-visible) {
- outline: 4px solid var(--tv-ring) !important;
+html[data-tv="1"] :focus img,
+html[data-tv="1"] :focus svg {
+ transition: transform 130ms ease-out;
}
-/* Kill mouse-only affordances. */
html[data-tv="1"] *:hover {
transform: none !important;
}
html[data-tv="1"] ::-webkit-scrollbar {
- width: 6px;
- height: 6px;
+ width: 0;
+ height: 0;
}
-/* Bigger hit targets for lists and tiles. */
html[data-tv="1"] button,
html[data-tv="1"] [role="button"],
html[data-tv="1"] a[href] {
- min-width: 44px;
- min-height: 44px;
+ min-width: 48px;
+ min-height: 48px;
}
-/* Give rows more air so focus rings do not overlap. */
html[data-tv="1"] ul,
html[data-tv="1"] ol {
- row-gap: 6px;
+ row-gap: 10px;
+}
+
+html[data-tv="1"] li {
+ padding-block: 2px;
+}
+
+html[data-tv="1"] h1,
+html[data-tv="1"] h2 {
+ letter-spacing: -0.01em;
+}
+
+html[data-tv="1"] small {
+ color: color-mix(in oklab, currentColor 78%, white);
+}
+
+html[data-tv="1"] aside,
+html[data-tv="1"] nav {
+ min-width: 76px;
+}
+
+html[data-tv="1"] input[type="search"],
+html[data-tv="1"] input[type="text"] {
+ font-size: 1.05em;
+ padding-block: 0.6em;
}
diff --git a/web/src/tv/tvMode.ts b/web/src/tv/tvMode.ts
index c80bdbf..850b429 100644
--- a/web/src/tv/tvMode.ts
+++ b/web/src/tv/tvMode.ts
@@ -1,8 +1,12 @@
/**
* Android TV mode: 10-foot UI plus D-pad spatial navigation.
*
- * Enabled by VITE_TV=1 at build time (see tools/build-apk-tv.sh) or by opening the app with ?tv=1,
+ * Enabled by VITE_TV=1 at build time (tools/build-apk-tv.sh) or by opening the app with ?tv=1,
* so the normal desktop/mobile builds are untouched.
+ *
+ * Rules: geometry in document space (rails stay navigable when an item is scrolled out), candidates
+ * overlapping the current element on the other axis win, the nearest scrollable ancestor is scrolled
+ * just enough to reveal the target, and key auto-repeat is throttled so a held arrow moves one step.
*/
const FOCUSABLE = [
@@ -17,6 +21,9 @@ const FOCUSABLE = [
"[data-tv-focusable]",
].join(",");
+const REPEAT_MS = 90;
+let lastMove = 0;
+
export function isTvMode(): boolean {
if (typeof window === "undefined") return false;
if (new URLSearchParams(window.location.search).has("tv")) return true;
@@ -24,58 +31,108 @@ export function isTvMode(): boolean {
return document.documentElement.dataset.tv === "1";
}
-const rectOf = (el: HTMLElement) => el.getBoundingClientRect();
+function shown(el: HTMLElement): boolean {
+ const style = getComputedStyle(el);
+ if (style.display === "none" || style.visibility === "hidden" || style.opacity === "0") return false;
+ const r = el.getBoundingClientRect();
+ return r.width >= 4 && r.height >= 4;
+}
-function visible(el: HTMLElement): boolean {
- if (el === document.body) return false;
- const r = rectOf(el);
- if (r.width < 4 || r.height < 4) return false;
- if (r.bottom < -40 || r.top > window.innerHeight + 40) return false;
- const style = window.getComputedStyle(el);
- if (style.visibility === "hidden" || style.opacity === "0") return false;
- return true;
+function focusables(): HTMLElement[] {
+ return Array.from(document.querySelectorAll<HTMLElement>(FOCUSABLE)).filter(shown);
}
-function candidates(): HTMLElement[] {
- return Array.from(document.querySelectorAll<HTMLElement>(FOCUSABLE)).filter(visible);
+function box(el: HTMLElement) {
+ const r = el.getBoundingClientRect();
+ return {
+ left: r.left + window.scrollX,
+ top: r.top + window.scrollY,
+ width: r.width,
+ height: r.height,
+ cx: r.left + window.scrollX + r.width / 2,
+ cy: r.top + window.scrollY + r.height / 2,
+ };
+}
+
+function scrollableAncestor(el: HTMLElement): HTMLElement | null {
+ let node = el.parentElement;
+ while (node && node !== document.body) {
+ const s = getComputedStyle(node);
+ const canY = /(auto|scroll|overlay)/.test(s.overflowY) && node.scrollHeight > node.clientHeight + 4;
+ const canX = /(auto|scroll|overlay)/.test(s.overflowX) && node.scrollWidth > node.clientWidth + 4;
+ if (canX || canY) return node;
+ node = node.parentElement;
+ }
+ return null;
}
-function center(el: HTMLElement) {
- const r = rectOf(el);
- return { x: r.left + r.width / 2, y: r.top + r.height / 2 };
+function reveal(el: HTMLElement) {
+ const scroller = scrollableAncestor(el);
+ if (!scroller) {
+ el.scrollIntoView({ block: "nearest", inline: "nearest", behavior: "smooth" });
+ return;
+ }
+ const s = scroller.getBoundingClientRect();
+ const r = el.getBoundingClientRect();
+ const margin = 24;
+ let dx = 0;
+ let dy = 0;
+ if (r.left < s.left + margin) dx = r.left - s.left - margin;
+ else if (r.right > s.right - margin) dx = r.right - s.right + margin;
+ if (r.top < s.top + margin) dy = r.top - s.top - margin;
+ else if (r.bottom > s.bottom - margin) dy = r.bottom - s.bottom + margin;
+ if (dx || dy) scroller.scrollBy({ left: dx, top: dy, behavior: "smooth" });
}
function move(direction: "left" | "right" | "up" | "down"): boolean {
const current = document.activeElement instanceof HTMLElement ? document.activeElement : null;
- const from = current && visible(current) ? center(current) : { x: window.innerWidth / 2, y: window.innerHeight / 2 };
+ const from = current && shown(current) ? box(current) : null;
+ const horizontal = direction === "left" || direction === "right";
let best: HTMLElement | null = null;
let bestScore = Number.POSITIVE_INFINITY;
- for (const el of candidates()) {
+ for (const el of focusables()) {
if (el === current) continue;
- const to = center(el);
- const dx = to.x - from.x;
- const dy = to.y - from.y;
- const primary =
- direction === "left" ? -dx : direction === "right" ? dx : direction === "up" ? -dy : dy;
- if (primary < 6) continue; // not in that direction
- const secondary = direction === "left" || direction === "right" ? Math.abs(dy) : Math.abs(dx);
- const score = primary + secondary * 2.2; // stay in the same row/column when possible
+ const to = box(el);
+ const primary = !from
+ ? (horizontal ? to.cx : to.cy)
+ : horizontal
+ ? direction === "right"
+ ? to.left - (from.left + from.width)
+ : from.left - (to.left + to.width)
+ : direction === "down"
+ ? to.top - (from.top + from.height)
+ : from.top - (to.top + to.height);
+ if (primary < -2) continue;
+
+ let perp = 0;
+ let overlap = 0;
+ if (from) {
+ const a1 = horizontal ? from.top : from.left;
+ const a2 = horizontal ? from.top + from.height : from.left + from.width;
+ const b1 = horizontal ? to.top : to.left;
+ const b2 = horizontal ? to.top + to.height : to.left + to.width;
+ overlap = Math.max(0, Math.min(a2, b2) - Math.max(a1, b1));
+ perp = Math.abs((horizontal ? to.cy : to.cx) - (horizontal ? from.cy : from.cx));
+ }
+
+ const score = Math.max(primary, 0) + (overlap > 0 ? perp * 0.35 : perp * 2.6 + 400);
if (score < bestScore) {
bestScore = score;
best = el;
}
}
+
if (!best) return false;
best.focus({ preventScroll: true });
- best.scrollIntoView({ block: "nearest", inline: "nearest", behavior: "smooth" });
+ reveal(best);
return true;
}
function activate(): boolean {
const el = document.activeElement;
if (!(el instanceof HTMLElement) || el === document.body) return false;
- if (el instanceof HTMLInputElement && /^(text|search)$/.test(el.type)) return false;
+ if (el instanceof HTMLInputElement && /^(text|search|email|password)$/.test(el.type)) return false;
el.click();
return true;
}
@@ -102,27 +159,27 @@ export function installTvMode() {
if (key === "ArrowLeft" || key === "ArrowRight" || key === "ArrowUp" || key === "ArrowDown") {
if (typing) return;
+ const now = performance.now();
+ if (event.repeat && now - lastMove < REPEAT_MS) {
+ handled();
+ return;
+ }
+ lastMove = now;
if (move(key.replace("Arrow", "").toLowerCase() as "left" | "right" | "up" | "down")) handled();
return;
}
+
if ((key === "Enter" || key === " ") && !typing) {
- // Buttons already activate themselves on Enter/Space.
if (document.activeElement instanceof HTMLButtonElement) return;
if (activate()) handled();
- return;
- }
- if (key === "Escape" || key === "BrowserBack") {
- // Let the app's own handlers/dialogs deal with Escape first.
}
},
{ capture: true },
);
- // First focus so the remote is immediately useful.
const focusFirst = () => {
- const first = candidates()[0];
- if (first && document.activeElement === document.body) first.focus({ preventScroll: true });
+ const els = focusables();
+ if (document.activeElement === document.body && els.length) els[0].focus({ preventScroll: true });
};
- window.setTimeout(focusFirst, 400);
- document.addEventListener("route-change", focusFirst as EventListener);
+ window.setTimeout(focusFirst, 350);
}