Tuner v1: HLS pipeline with playback/ingest modes

FFmpeg -> MediaMTX -> HLS relay with runtime-configurable modes: - PLAYBACK_MODE: standard (mpegts), fmp4 (HEVC), llhls - INGEST_MODE: rtmp, rtsp - INGEST_AUDIO_MODE: aac, copy - Hourly playlist auto-refresh from upstream URL - Fullscreen video UI with collapsible sidebar, upstream-down banner - Same-origin HLS proxy for HTTPS deployments Tagged as the last HLS-based version before the mpegts.js (v2) rework.
2026-06-12 19:17:15 -07:00
parent a41c3ee56c
commit 88a189de34
20 changed files with 814 additions and 123 deletions
--- a/frontend/README.md
+++ b/frontend/README.md
@@ -0,0 +1,73 @@
+# React + TypeScript + Vite
+
+This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
+
+Currently, two official plugins are available:
+
+- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Babel](https://babeljs.io/) (or [oxc](https://oxc.rs) when used in [rolldown-vite](https://vite.dev/guide/rolldown)) for Fast Refresh
+- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/) for Fast Refresh
+
+## React Compiler
+
+The React Compiler is not enabled on this template because of its impact on dev & build performances. To add it, see [this documentation](https://react.dev/learn/react-compiler/installation).
+
+## Expanding the ESLint configuration
+
+If you are developing a production application, we recommend updating the configuration to enable type-aware lint rules:
+
+```js
+export default defineConfig([
+  globalIgnores(['dist']),
+  {
+    files: ['**/*.{ts,tsx}'],
+    extends: [
+      // Other configs...
+
+      // Remove tseslint.configs.recommended and replace with this
+      tseslint.configs.recommendedTypeChecked,
+      // Alternatively, use this for stricter rules
+      tseslint.configs.strictTypeChecked,
+      // Optionally, add this for stylistic rules
+      tseslint.configs.stylisticTypeChecked,
+
+      // Other configs...
+    ],
+    languageOptions: {
+      parserOptions: {
+        project: ['./tsconfig.node.json', './tsconfig.app.json'],
+        tsconfigRootDir: import.meta.dirname,
+      },
+      // other options...
+    },
+  },
+])
+```
+
+You can also install [eslint-plugin-react-x](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-x) and [eslint-plugin-react-dom](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-dom) for React-specific lint rules:
+
+```js
+// eslint.config.js
+import reactX from 'eslint-plugin-react-x'
+import reactDom from 'eslint-plugin-react-dom'
+
+export default defineConfig([
+  globalIgnores(['dist']),
+  {
+    files: ['**/*.{ts,tsx}'],
+    extends: [
+      // Other configs...
+      // Enable lint rules for React
+      reactX.configs['recommended-typescript'],
+      // Enable lint rules for React DOM
+      reactDom.configs.recommended,
+    ],
+    languageOptions: {
+      parserOptions: {
+        project: ['./tsconfig.node.json', './tsconfig.app.json'],
+        tsconfigRootDir: import.meta.dirname,
+      },
+      // other options...
+    },
+  },
+])
+```
--- a/frontend/src/App.css
+++ b/frontend/src/App.css
@@ -4,25 +4,44 @@
  box-sizing: border-box;
 }

-body {
-  background: #0a0a0a;
-  color: #e0e0e0;
-  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+html, body, #root {
+  height: 100%;
 }

+body {
+  background: #000;
+  color: #e0e0e0;
+  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+  overflow: hidden;
+}
+
+/* App shell: video fills everything, UI floats on top */
 .app {
-  max-width: 960px;
-  margin: 0 auto;
-  padding: 16px;
+  position: fixed;
+  inset: 0;
+  background: #000;
+  /* height reserved for the fixed bottom status bar */
+  --status-bar-height: 49px;
+}
+
+/* Fullscreen video stage: sits above the bottom status bar so the
+   native video controls (play button) are never hidden behind it */
+.stage {
+  position: absolute;
+  top: 0;
+  left: 0;
+  right: 0;
+  bottom: var(--status-bar-height);
+  z-index: 0;
 }

 /* Player */
 .player-container {
-  position: relative;
+  position: absolute;
+  inset: 0;
  width: 100%;
-  aspect-ratio: 16 / 9;
-  background: #111;
-  border-radius: 8px;
+  height: 100%;
+  background: #000;
  overflow: hidden;
 }

@@ -30,39 +49,116 @@ body {
  width: 100%;
  height: 100%;
  display: block;
+  object-fit: contain;
+  background: #000;
 }

-.player-video:not([src]),
-.player-video[src=""] {
-  display: none;
-}
-
-.player-video:not([src]) ~ .player-offline,
-.player-video[src=""] ~ .player-offline {
-  display: flex;
-}
-
+/* Offline overlay is controlled by React state, not CSS src tricks */
 .player-offline {
-  display: none;
+  display: flex;
  position: absolute;
  inset: 0;
  align-items: center;
  justify-content: center;
-  font-size: 1.25rem;
-  color: #666;
+  font-size: 1.5rem;
+  color: #555;
  letter-spacing: 0.05em;
 }

-/* StatusBar */
+/* Sidebar toggle button (far right, vertically centered) */
+.sidebar-toggle {
+  position: fixed;
+  top: 50%;
+  right: 0;
+  transform: translateY(-50%);
+  z-index: 30;
+  width: 32px;
+  height: 64px;
+  border: none;
+  border-radius: 8px 0 0 8px;
+  background: rgba(20, 20, 20, 0.7);
+  backdrop-filter: blur(8px);
+  color: #e0e0e0;
+  font-size: 1.4rem;
+  line-height: 1;
+  cursor: pointer;
+  /* hidden by default; shown on interaction */
+  opacity: 0;
+  pointer-events: none;
+  transition: right 0.25s ease, background 0.15s, opacity 0.3s ease;
+}
+
+.sidebar-toggle.visible {
+  opacity: 1;
+  pointer-events: auto;
+}
+
+.sidebar-toggle:hover {
+  background: rgba(40, 40, 40, 0.85);
+}
+
+.sidebar-toggle.open {
+  right: 340px;
+}
+
+/* Sidebar */
+.sidebar {
+  position: fixed;
+  top: 0;
+  right: 0;
+  bottom: 0;
+  width: 340px;
+  z-index: 20;
+  background: rgba(15, 15, 15, 0.82);
+  backdrop-filter: blur(12px);
+  border-left: 1px solid rgba(255, 255, 255, 0.08);
+  transition: transform 0.25s ease;
+  overflow: hidden;
+}
+
+.sidebar.collapsed {
+  transform: translateX(100%);
+}
+
+.sidebar.open {
+  transform: translateX(0);
+}
+
+.sidebar-inner {
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+  height: 100%;
+  padding: 16px;
+  /* leave room for the bottom status bar */
+  padding-bottom: 64px;
+  overflow-y: auto;
+}
+
+/* StatusBar (fixed to bottom) */
 .status-bar {
+  position: fixed;
+  left: 0;
+  right: 0;
+  bottom: 0;
+  z-index: 25;
+  height: var(--status-bar-height);
  display: flex;
  align-items: center;
  gap: 10px;
-  padding: 12px 16px;
-  margin-top: 8px;
-  background: #1a1a1a;
-  border-radius: 6px;
+  padding: 0 16px;
+  background: rgba(15, 15, 15, 0.85);
+  backdrop-filter: blur(8px);
+  border-top: 1px solid rgba(255, 255, 255, 0.08);
  font-size: 0.875rem;
+  white-space: nowrap;
+  overflow-x: auto;
+  overflow-y: hidden;
+  scrollbar-width: none;
+}
+
+.status-bar::-webkit-scrollbar {
+  display: none;
 }

 .status-dot {
@@ -114,6 +210,19 @@ body {
  animation: switching-blink 1s step-end infinite;
 }

+.upstream-down-banner {
+  color: #fecaca;
+  background: #7f1d1d;
+  border: 1px solid #ef4444;
+  border-radius: 4px;
+  padding: 3px 10px;
+  font-size: 0.8rem;
+  font-weight: 800;
+  letter-spacing: 0.03em;
+  text-transform: uppercase;
+  box-shadow: 0 0 12px rgba(239, 68, 68, 0.35);
+}
+
@keyframes channel-pulse {
  0%, 100% { opacity: 1; }
  50% { opacity: 0.5; }
@@ -167,19 +276,13 @@ body {
  color: #f87171;
 }

-/* Controls layout */
-.controls {
-  display: grid;
-  grid-template-columns: 240px 1fr;
-  gap: 12px;
-  margin-top: 12px;
-}
-
 /* AdminPanel */
 .admin-panel {
-  background: #1a1a1a;
+  background: rgba(26, 26, 26, 0.7);
+  border: 1px solid rgba(255, 255, 255, 0.06);
  border-radius: 6px;
  padding: 16px;
+  flex-shrink: 0;
 }

 .admin-title {
@@ -237,12 +340,14 @@ body {

 /* ChannelList */
 .channel-list {
-  background: #1a1a1a;
+  background: rgba(26, 26, 26, 0.7);
+  border: 1px solid rgba(255, 255, 255, 0.06);
  border-radius: 6px;
  padding: 16px;
  display: flex;
  flex-direction: column;
-  max-height: 500px;
+  flex: 1;
+  min-height: 0;
 }

 .channel-list-title {
@@ -256,6 +361,7 @@ body {

 .channel-filters {
  display: flex;
+  flex-direction: column;
  gap: 8px;
  margin-bottom: 12px;
 }
@@ -287,7 +393,7 @@ body {
  color: #e0e0e0;
  font-size: 0.875rem;
  outline: none;
-  min-width: 140px;
+  width: 100%;
 }

 .channel-items {
@@ -356,8 +462,11 @@ body {
  color: #666;
 }

-@media (max-width: 640px) {
-  .controls {
-    grid-template-columns: 1fr;
+@media (max-width: 480px) {
+  .sidebar {
+    width: 100%;
+  }
+  .sidebar-toggle.open {
+    right: calc(100% - 32px);
  }
 }
--- a/frontend/src/App.tsx
+++ b/frontend/src/App.tsx
@@ -1,5 +1,5 @@
-import { useState, useEffect, useCallback } from "react";
-import type { StreamStatus, Channel } from "./types";
+import { useState, useEffect, useCallback, useRef } from "react";
+import type { StreamStatus, Channel, PlaybackMode } from "./types";
 import * as api from "./api/client";
 import Player from "./components/Player";
 import StatusBar from "./components/StatusBar";
@@ -7,9 +7,32 @@ import AdminPanel from "./components/AdminPanel";
 import ChannelList from "./components/ChannelList";
 import "./App.css";

+// Detect touch-primary devices (phones/tablets have no hover pointer).
+const isTouchPrimary = () =>
+  window.matchMedia("(pointer: coarse)").matches || navigator.maxTouchPoints > 0;
+
+const HIDE_DELAY = 3000; // ms of inactivity before toggle hides again
+
 export default function App() {
  const [status, setStatus] = useState<StreamStatus | null>(null);
  const [channels, setChannels] = useState<Channel[]>([]);
+  const [sidebarOpen, setSidebarOpen] = useState(false);
+  const [playbackMode, setPlaybackMode] = useState<PlaybackMode>("standard");
+  const [toggleVisible, setToggleVisible] = useState(false);
+  const hideTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  useEffect(() => {
+    api
+      .getConfig()
+      .then((c) => {
+        if (c.playback_mode === "llhls" || c.playback_mode === "fmp4") {
+          setPlaybackMode(c.playback_mode);
+        } else {
+          setPlaybackMode("standard");
+        }
+      })
+      .catch(() => {});
+  }, []);

  const fetchStatus = useCallback(async () => {
    try {
@@ -32,11 +55,53 @@ export default function App() {
  useEffect(() => {
    fetchStatus();
    fetchChannels();
-    // Poll faster while transitioning so the UI updates promptly
-    const rate = status?.transitioning ? 1000 : 5000;
+    // Poll faster while live so passive viewers detect channel switches promptly.
+    // Transitioning gets the fastest rate so the UI clears quickly after FFmpeg starts.
+    const rate = status?.transitioning ? 1000 : status?.live ? 2000 : 5000;
    const interval = setInterval(fetchStatus, rate);
    return () => clearInterval(interval);
-  }, [fetchStatus, fetchChannels, status?.transitioning]);
+  }, [fetchStatus, fetchChannels, status?.live, status?.transitioning]);
+
+  useEffect(() => {
+    if (status?.playlist_version) {
+      fetchChannels();
+    }
+  }, [fetchChannels, status?.playlist_version]);
+
+  // Show the toggle button on interaction, then auto-hide after HIDE_DELAY.
+  // When the sidebar is open we keep it visible so the user can close it.
+  const showToggle = useCallback(() => {
+    setToggleVisible(true);
+    if (hideTimer.current) clearTimeout(hideTimer.current);
+    if (!sidebarOpen) {
+      hideTimer.current = setTimeout(() => setToggleVisible(false), HIDE_DELAY);
+    }
+  }, [sidebarOpen]);
+
+  // Keep toggle visible while sidebar is open; restart timer when it closes.
+  useEffect(() => {
+    if (sidebarOpen) {
+      if (hideTimer.current) clearTimeout(hideTimer.current);
+      setToggleVisible(true);
+    } else {
+      hideTimer.current = setTimeout(() => setToggleVisible(false), HIDE_DELAY);
+    }
+    return () => {
+      if (hideTimer.current) clearTimeout(hideTimer.current);
+    };
+  }, [sidebarOpen]);
+
+  // Wire up interaction listeners on the document.
+  useEffect(() => {
+    const touch = isTouchPrimary();
+    if (touch) {
+      document.addEventListener("touchstart", showToggle, { passive: true });
+      return () => document.removeEventListener("touchstart", showToggle);
+    } else {
+      document.addEventListener("mousemove", showToggle);
+      return () => document.removeEventListener("mousemove", showToggle);
+    }
+  }, [showToggle]);

  const handleSourceChanged = () => {
    fetchStatus();
@@ -52,20 +117,43 @@ export default function App() {

  return (
    <div className="app">
-      <Player live={status?.live ?? false} />
-      <StatusBar status={status} />
-      <div className="controls">
-        <AdminPanel
-          status={status}
-          onSourceChanged={handleSourceChanged}
-          onPlaylistReloaded={handlePlaylistReloaded}
-        />
-        <ChannelList
-          channels={channels}
-          activeChannel={status?.channel_name ?? ""}
-          onRefresh={handleChannelRefresh}
+      {/* Fullscreen video background */}
+      <div className="stage">
+        <Player
+          live={status?.live ?? false}
+          mode={playbackMode}
+          streamKey={`${status?.source ?? "offline"}:${status?.channel_name ?? ""}`}
        />
      </div>
+
+      {/* Collapsible right sidebar */}
+      <button
+        className={`sidebar-toggle ${sidebarOpen ? "open" : ""} ${toggleVisible ? "visible" : ""}`}
+        onClick={() => setSidebarOpen((v) => !v)}
+        aria-label={sidebarOpen ? "Collapse panel" : "Open panel"}
+        title={sidebarOpen ? "Collapse panel" : "Open panel"}
+      >
+        {sidebarOpen ? "›" : "‹"}
+      </button>
+
+      <aside className={`sidebar ${sidebarOpen ? "open" : "collapsed"}`}>
+        <div className="sidebar-inner">
+          <AdminPanel
+            status={status}
+            onSourceChanged={handleSourceChanged}
+            onPlaylistReloaded={handlePlaylistReloaded}
+          />
+          <ChannelList
+          channels={channels}
+          activeChannel={status?.channel_name ?? ""}
+          playlistVersion={status?.playlist_version ?? 0}
+          onRefresh={handleChannelRefresh}
+        />
+        </div>
+      </aside>
+
+      {/* Status banner fixed to the bottom */}
+      <StatusBar status={status} />
    </div>
  );
 }
--- a/frontend/src/api/client.ts
+++ b/frontend/src/api/client.ts
@@ -1,4 +1,4 @@
-import type { Channel, StreamStatus, SystemStatus } from "../types";
+import type { Channel, StreamStatus, SystemStatus, AppConfig } from "../types";

 async function fetchJSON<T>(url: string, init?: RequestInit): Promise<T> {
  const res = await fetch(url, init);
@@ -8,6 +8,10 @@ async function fetchJSON<T>(url: string, init?: RequestInit): Promise<T> {
  return res.json();
 }

+export function getConfig(): Promise<AppConfig> {
+  return fetchJSON<AppConfig>("/api/config");
+}
+
 async function fetchVoid(url: string, init?: RequestInit): Promise<void> {
  const res = await fetch(url, init);
  if (!res.ok) {
--- a/frontend/src/components/AdminPanel.tsx
+++ b/frontend/src/components/AdminPanel.tsx
@@ -46,7 +46,7 @@ export default function AdminPanel({ status, onSourceChanged, onPlaylistReloaded
        </button>
      </div>
      <button className="reload-btn" onClick={handleReload}>
-        Reload Playlist
+        Refresh Channels / Playlist
      </button>
    </div>
  );
--- a/frontend/src/components/ChannelList.tsx
+++ b/frontend/src/components/ChannelList.tsx
@@ -5,10 +5,11 @@ import * as api from "../api/client";
 interface Props {
  channels: Channel[];
  activeChannel: string;
+  playlistVersion: number;
  onRefresh: () => void;
 }

-export default function ChannelList({ channels, activeChannel, onRefresh }: Props) {
+export default function ChannelList({ channels, activeChannel, playlistVersion, onRefresh }: Props) {
  const [search, setSearch] = useState("");
  const [group, setGroup] = useState("");
  const [groups, setGroups] = useState<string[]>([]);
@@ -16,7 +17,7 @@ export default function ChannelList({ channels, activeChannel, onRefresh }: Prop

  useEffect(() => {
    api.getGroups().then((g) => setGroups(g ?? [])).catch(() => {});
-  }, []);
+  }, [playlistVersion]);

  useEffect(() => {
    const fetchFiltered = async () => {
--- a/frontend/src/components/Player.tsx
+++ b/frontend/src/components/Player.tsx
@@ -1,75 +1,137 @@
-import { useEffect, useRef } from "react";
+import { useEffect, useRef, useState } from "react";
 import Hls from "hls.js";
+import type { PlaybackMode } from "../types";

 interface Props {
  live: boolean;
+  mode: PlaybackMode;
+  streamKey: string;
 }

-export default function Player({ live }: Props) {
+export default function Player({ live, mode, streamKey }: Props) {
  const videoRef = useRef<HTMLVideoElement>(null);
  const hlsRef = useRef<Hls | null>(null);
+  const retryTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const [playing, setPlaying] = useState(false);

  useEffect(() => {
    const video = videoRef.current;
    if (!video) return;

-    // Tear down any existing instance when stream goes offline
+    const clearRetry = () => {
+      if (retryTimerRef.current) {
+        clearTimeout(retryTimerRef.current);
+        retryTimerRef.current = null;
+      }
+    };
+
+    // Tear down when stream goes offline
    if (!live) {
+      clearRetry();
      if (hlsRef.current) {
        hlsRef.current.destroy();
        hlsRef.current = null;
      }
      video.removeAttribute("src");
      video.load();
+      setPlaying(false);
      return;
    }

-    const src = `http://${window.location.hostname}:8888/live/stream/index.m3u8`;
+    const src = `${window.location.origin}/live/stream/index.m3u8?v=${encodeURIComponent(streamKey)}`;

    if (Hls.isSupported()) {
-      const hls = new Hls({
-        enableWorker: true,
-        lowLatencyMode: true,
-        liveSyncDurationCount: 3,
-        liveMaxLatencyDurationCount: 6,
-        liveBackBufferLength: 0,
-        maxBufferLength: 10,
-        maxMaxBufferLength: 30,
-      });
+      const hlsConfig =
+        mode === "llhls"
+          ? {
+              enableWorker: true,
+              lowLatencyMode: true,
+              liveSyncDurationCount: 3,
+              liveMaxLatencyDurationCount: 6,
+              liveBackBufferLength: 0,
+              maxBufferLength: 10,
+              maxMaxBufferLength: 30,
+            }
+          : {
+              enableWorker: true,
+              lowLatencyMode: false,
+              liveSyncDurationCount: 4,
+              liveMaxLatencyDurationCount: 10,
+              maxBufferLength: 30,
+              maxMaxBufferLength: 60,
+            };
+      const hls = new Hls(hlsConfig);
      hlsRef.current = hls;
      hls.loadSource(src);
      hls.attachMedia(video);
      hls.on(Hls.Events.MANIFEST_PARSED, () => {
        video.play().catch(() => {});
+        setPlaying(true);
      });
      hls.on(Hls.Events.ERROR, (_event, data) => {
        if (data.fatal) {
          if (data.type === Hls.ErrorTypes.NETWORK_ERROR) {
-            setTimeout(() => hls.loadSource(src), 5000);
+            setPlaying(false);
+            retryTimerRef.current = setTimeout(() => hls.loadSource(src), 5000);
          } else {
            hls.destroy();
+            setPlaying(false);
          }
        }
      });
    } else if (video.canPlayType("application/vnd.apple.mpegurl")) {
-      video.src = src;
-      video.addEventListener("loadedmetadata", () => {
+      // Native HLS (iOS Safari) — set src directly and retry on error.
+      const setupNative = () => {
+        video.src = src;
+        video.load();
        video.play().catch(() => {});
-      });
+      };
+
+      const onPlaying = () => {
+        clearRetry();
+        setPlaying(true);
+      };
+
+      const onError = () => {
+        setPlaying(false);
+        retryTimerRef.current = setTimeout(setupNative, 5000);
+      };
+
+      const onStalled = () => {
+        setPlaying(false);
+        retryTimerRef.current = setTimeout(setupNative, 5000);
+      };
+
+      video.addEventListener("playing", onPlaying);
+      video.addEventListener("error", onError);
+      video.addEventListener("stalled", onStalled);
+      setupNative();
+
+      return () => {
+        clearRetry();
+        video.removeEventListener("playing", onPlaying);
+        video.removeEventListener("error", onError);
+        video.removeEventListener("stalled", onStalled);
+        video.removeAttribute("src");
+        video.load();
+        setPlaying(false);
+      };
    }

    return () => {
+      clearRetry();
      if (hlsRef.current) {
        hlsRef.current.destroy();
        hlsRef.current = null;
      }
+      setPlaying(false);
    };
-  }, [live]);
+  }, [live, mode, streamKey]);

  return (
    <div className="player-container">
-      <video ref={videoRef} className="player-video" controls playsInline />
-      <div className="player-offline">Stream Offline</div>
+      <video ref={videoRef} className="player-video" controls playsInline autoPlay muted />
+      {!playing && <div className="player-offline">Stream Offline</div>}
    </div>
  );
 }
--- a/frontend/src/components/StatusBar.tsx
+++ b/frontend/src/components/StatusBar.tsx
@@ -53,6 +53,12 @@ export default function StatusBar({ status }: Props) {
          </span>
        </>
      )}
+      {status.upstream_down && (
+        <>
+          <span className="status-separator">|</span>
+          <span className="upstream-down-banner">Upstream down?</span>
+        </>
+      )}
      {h && h.speed && (
        <span className="status-health">
          <span className="status-separator">|</span>
--- a/frontend/src/types/index.ts
+++ b/frontend/src/types/index.ts
@@ -19,6 +19,8 @@ export interface StreamStatus {
  channel_name: string;
  live: boolean;
  transitioning: boolean;
+  upstream_down: boolean;
+  playlist_version: number;
  health?: StreamHealth;
 }

@@ -33,3 +35,9 @@ export interface SystemStatus {
  mediamtx: ProcessInfo;
  ffmpeg: ProcessInfo;
 }
+
+export type PlaybackMode = "llhls" | "fmp4" | "standard";
+
+export interface AppConfig {
+  playback_mode: PlaybackMode;
+}