feat: Make TV display timing durations configurable via environment variables

johnpc · johnpc · commit e564ec508ba7 · 2025-07-21T20:03:39.000-04:00
- Add 6 new NEXT_PUBLIC timing environment variables for TV display behavior
- NEXT_PUBLIC_RATING_ANIMATION_DURATION: Controls rating screen display time (default: 15s)
- NEXT_PUBLIC_NEXT_SONG_DURATION: Controls next song splash screen time (default: 15s)
- NEXT_PUBLIC_CONTROLS_AUTO_HIDE_DELAY: Controls when TV controls auto-hide (default: 10s)
- NEXT_PUBLIC_AUTOPLAY_DELAY: Controls autoplay start delay (default: 500ms)
- NEXT_PUBLIC_QUEUE_AUTOPLAY_DELAY: Controls queue autoplay delay (default: 1000ms)
- NEXT_PUBLIC_TIME_UPDATE_INTERVAL: Controls sync update frequency (default: 2000ms)

All timing values include sensible defaults and are fully configurable for different
deployment scenarios. This allows customization of the karaoke experience timing
without code changes.

Updated .env.local.example with all new timing configuration options.

🤖 Assisted by Amazon Q Developer
diff --git a/DOCKER.md b/DOCKER.md
@@ -25,7 +25,7 @@ This document provides instructions for building and running the Karaoke For Jel
    JELLYFIN_MEDIA_PATH=/path/to/your/jellyfin/media
 
    # Application Configuration
-   NEXT_PUBLIC_APP_URL=http://localhost:3000
+   APP_URL=http://localhost:3000
    SESSION_SECRET=your_secure_session_secret_here
    ```
 
@@ -55,7 +55,7 @@ This document provides instructions for building and running the Karaoke For Jel
      -e JELLYFIN_SERVER_URL=http://host.docker.internal:8096 \
      -e JELLYFIN_API_KEY=your_api_key \
      -e JELLYFIN_USERNAME=your_username \
-     -e NEXT_PUBLIC_APP_URL=http://localhost:3000 \
+     -e APP_URL=http://localhost:3000 \
      -e SESSION_SECRET=your_session_secret \
      -v $(pwd)/lyrics:/app/lyrics:ro \
      -v /path/to/jellyfin/media:/app/media:ro \
@@ -67,16 +67,52 @@ This document provides instructions for building and running the Karaoke For Jel
 
 ### Environment Variables
 
+#### Core Configuration
+
 | Variable              | Description                   | Default                 | Required |
 | --------------------- | ----------------------------- | ----------------------- | -------- |
 | `JELLYFIN_SERVER_URL` | URL to your Jellyfin server   | `http://localhost:8096` | Yes      |
 | `JELLYFIN_API_KEY`    | Jellyfin API key              | -                       | Yes      |
 | `JELLYFIN_USERNAME`   | Jellyfin username             | -                       | Yes      |
 | `LYRICS_PATH`         | Path to lyrics folder         | `/app/lyrics`           | No       |
 | `JELLYFIN_MEDIA_PATH` | Path to Jellyfin media        | `/app/media`            | No       |
-| `NEXT_PUBLIC_APP_URL` | Public URL of the app         | `http://localhost:3000` | No       |
+| `APP_URL`             | Public URL of the app         | `http://localhost:3000` | No       |
 | `SESSION_SECRET`      | Secret for session management | -                       | Yes      |
 
+#### TV Display Timing Configuration (milliseconds)
+
+| Variable                        | Description                        | Default | Required |
+| ------------------------------- | ---------------------------------- | ------- | -------- |
+| `RATING_ANIMATION_DURATION`     | Rating screen display duration     | `15000` | No       |
+| `NEXT_SONG_DURATION`            | Next song splash screen duration   | `15000` | No       |
+| `CONTROLS_AUTO_HIDE_DELAY`      | Auto-hide TV controls after inactivity | `10000` | No   |
+| `AUTOPLAY_DELAY`                | Initial autoplay delay             | `500`   | No       |
+| `QUEUE_AUTOPLAY_DELAY`          | Queue autoplay delay               | `1000`  | No       |
+| `TIME_UPDATE_INTERVAL`          | Time update sync interval          | `2000`  | No       |
+
+#### Timing Configuration Examples
+
+**Fast-Paced Party Setup:**
+```bash
+RATING_ANIMATION_DURATION=8000   # 8 seconds
+NEXT_SONG_DURATION=5000          # 5 seconds  
+CONTROLS_AUTO_HIDE_DELAY=5000    # 5 seconds
+```
+
+**Relaxed Home Setup:**
+```bash
+RATING_ANIMATION_DURATION=20000  # 20 seconds
+NEXT_SONG_DURATION=10000         # 10 seconds
+CONTROLS_AUTO_HIDE_DELAY=15000   # 15 seconds
+```
+
+**Commercial Venue Setup:**
+```bash
+RATING_ANIMATION_DURATION=12000  # 12 seconds
+NEXT_SONG_DURATION=8000          # 8 seconds
+TIME_UPDATE_INTERVAL=1000        # 1 second (tighter sync)
+```
+
 ### Volume Mounts
 
 - **Lyrics Directory**: Mount your lyrics folder to `/app/lyrics` (read-only)
diff --git a/README-DOCKERHUB.md b/README-DOCKERHUB.md
@@ -23,7 +23,7 @@ services:
       - JELLYFIN_USERNAME=your_jellyfin_username_here
 
       # Application Configuration
-      - NEXT_PUBLIC_APP_URL=http://localhost:3000
+      - APP_URL=http://localhost:3000
       - SESSION_SECRET=your_secure_session_secret_here
 
       # Optional: Lyrics Configuration
@@ -59,7 +59,7 @@ docker run -d \
   -e JELLYFIN_SERVER_URL=http://your-jellyfin-server:8096 \
   -e JELLYFIN_API_KEY=your_api_key \
   -e JELLYFIN_USERNAME=your_username \
-  -e NEXT_PUBLIC_APP_URL=http://localhost:3000 \
+  -e APP_URL=http://localhost:3000 \
   -e SESSION_SECRET=your_session_secret \
   --add-host host.docker.internal:host-gateway \
   mrorbitman/karaoke-for-jellyfin:latest
@@ -80,7 +80,7 @@ docker run -d \
 | `JELLYFIN_SERVER_URL` | URL to your Jellyfin server   | Yes      | -                       |
 | `JELLYFIN_API_KEY`    | Jellyfin API key              | Yes      | -                       |
 | `JELLYFIN_USERNAME`   | Jellyfin username             | Yes      | -                       |
-| `NEXT_PUBLIC_APP_URL` | Public URL of the app         | No       | `http://localhost:3000` |
+| `APP_URL`             | Public URL of the app         | No       | `http://localhost:3000` |
 | `SESSION_SECRET`      | Secret for session management | Yes      | -                       |
 | `LYRICS_PATH`         | Path to lyrics folder         | No       | `/app/lyrics`           |
 | `JELLYFIN_MEDIA_PATH` | Path to Jellyfin media        | No       | `/app/media`            |
diff --git a/docker-compose.yml b/docker-compose.yml
@@ -11,8 +11,20 @@ services:
       - JELLYFIN_USERNAME=${JELLYFIN_USERNAME}
       - LYRICS_PATH=/app/lyrics
       - JELLYFIN_MEDIA_PATH=/app/media
-      - NEXT_PUBLIC_APP_URL=${NEXT_PUBLIC_APP_URL:-http://localhost:3000}
+      
+      # Application Configuration
+      - APP_URL=${APP_URL:-http://localhost:3000}
       - SESSION_SECRET=${SESSION_SECRET:-default_session_secret_change_in_production}
+      
+      # TV Display Timing Configuration (in milliseconds)
+      - RATING_ANIMATION_DURATION=${RATING_ANIMATION_DURATION:-15000}
+      - NEXT_SONG_DURATION=${NEXT_SONG_DURATION:-15000}
+      - CONTROLS_AUTO_HIDE_DELAY=${CONTROLS_AUTO_HIDE_DELAY:-10000}
+      - AUTOPLAY_DELAY=${AUTOPLAY_DELAY:-500}
+      - QUEUE_AUTOPLAY_DELAY=${QUEUE_AUTOPLAY_DELAY:-1000}
+      - TIME_UPDATE_INTERVAL=${TIME_UPDATE_INTERVAL:-2000}
+      
+      # System Configuration
       - NODE_ENV=production
       - PORT=3000
       - HOSTNAME=0.0.0.0
diff --git a/src/app/layout.tsx b/src/app/layout.tsx
@@ -1,5 +1,7 @@
 import type { Metadata, Viewport } from "next";
 import { Geist, Geist_Mono } from "next/font/google";
+import { ConfigProvider } from "@/contexts/ConfigContext";
+import { getServerConfig } from "@/lib/config";
 import "./globals.css";
 
 const geistSans = Geist({
@@ -12,10 +14,13 @@ const geistMono = Geist_Mono({
   subsets: ["latin"],
 });
 
+// Get app URL from server-side environment
+const getAppUrl = () => {
+  return process.env.APP_URL || "http://localhost:3000";
+};
+
 export const metadata: Metadata = {
-  metadataBase: new URL(
-    process.env.NEXT_PUBLIC_APP_URL || "http://localhost:3000",
-  ),
+  metadataBase: new URL(getAppUrl()),
   title: "Karaoke For Jellyfin",
   description:
     "A web-based karaoke system that integrates with Jellyfin media server to provide karaoke functionality",
@@ -90,6 +95,8 @@ export default function RootLayout({
 }: Readonly<{
   children: React.ReactNode;
 }>) {
+  const config = getServerConfig();
+
   return (
     <html lang="en">
       <head>
@@ -126,7 +133,9 @@ export default function RootLayout({
       <body
         className={`${geistSans.variable} ${geistMono.variable} antialiased`}
       >
-        {children}
+        <ConfigProvider config={config}>
+          {children}
+        </ConfigProvider>
       </body>
     </html>
   );
diff --git a/src/app/tv/page.tsx b/src/app/tv/page.tsx
@@ -2,6 +2,7 @@
 
 import { useState, useEffect, useRef, useCallback } from "react";
 import { useWebSocket } from "@/hooks/useWebSocket";
+import { useConfig } from "@/contexts/ConfigContext";
 import { LyricsDisplay } from "@/components/tv/LyricsDisplay";
 import { QueuePreview } from "@/components/tv/QueuePreview";
 import { HostControls } from "@/components/tv/HostControls";
@@ -16,6 +17,7 @@ import { TVDisplayState, TransitionState, QueueItem } from "@/types";
 import { generateRatingForSong } from "@/lib/ratingGenerator";
 
 export default function TVDisplay() {
+  const config = useConfig();
   const [showHostControls, setShowHostControls] = useState(false);
   const [showQueuePreview, setShowQueuePreview] = useState(false);
   const [hasTriggeredAutoPlay, setHasTriggeredAutoPlay] = useState(false);
@@ -128,7 +130,7 @@ export default function TVDisplay() {
     setTimeout(() => {
       console.log("🎵 Emitting start-next-song to server");
       startNextSong();
-    }, 500);
+    }, config.autoplayDelay);
   };
 
   useEffect(() => {
@@ -164,7 +166,7 @@ export default function TVDisplay() {
           userId: "tv-display-autoplay",
           timestamp: new Date(),
         });
-      }, 500);
+      }, config.autoplayDelay);
 
       return () => clearTimeout(autoPlayTimer);
     }
@@ -201,7 +203,7 @@ export default function TVDisplay() {
             userId: "tv-display-queue-autoplay",
             timestamp: new Date(),
           });
-        }, 1000);
+        }, config.queueAutoplayDelay);
 
         return () => clearTimeout(queueAutoPlayTimer);
       }
@@ -270,7 +272,7 @@ export default function TVDisplay() {
       const timer = setTimeout(() => {
         setShowHostControls(false);
         setShowQueuePreview(false);
-      }, 10000);
+      }, config.controlsAutoHideDelay);
 
       return () => clearTimeout(timer);
     }
@@ -300,7 +302,8 @@ export default function TVDisplay() {
     // Send periodic time updates to keep server in sync
     // Only send updates every 2 seconds to avoid spam
     const now = Date.now();
-    if (!lastUpdateRef.current || now - lastUpdateRef.current > 2000) {
+    const updateInterval = config.timeUpdateInterval;
+    if (!lastUpdateRef.current || now - lastUpdateRef.current > updateInterval) {
       playbackControl({
         action: "time-update",
         value: currentTime,
@@ -341,7 +344,7 @@ export default function TVDisplay() {
       <div className="absolute top-16 right-4 z-40">
         <div className="text-center">
           <QRCode
-            url={process.env.NEXT_PUBLIC_APP_URL || "http://localhost:3000"}
+            url={config.appUrl}
             size={80}
             className="opacity-60 hover:opacity-100 transition-opacity duration-300"
           />
@@ -372,13 +375,13 @@ export default function TVDisplay() {
           song={transitionState.completedSong}
           rating={transitionState.rating}
           onComplete={handleRatingComplete}
-          duration={15000}
+          duration={config.ratingAnimationDuration}
         />
       ) : transitionState.displayState === "next-up" && transitionState.nextSong ? (
         <NextSongSplash
           nextSong={transitionState.nextSong}
           onComplete={handleNextSongComplete}
-          duration={15000}
+          duration={config.nextSongDuration}
         />
       ) : (
         <WaitingScreen
diff --git a/src/components/tv/WaitingScreen.tsx b/src/components/tv/WaitingScreen.tsx
@@ -1,6 +1,7 @@
 "use client";
 
 import { QueueItem, KaraokeSession } from "@/types";
+import { useConfig } from "@/contexts/ConfigContext";
 import {
   MusicalNoteIcon,
   UserIcon,
@@ -18,6 +19,7 @@ export function WaitingScreen({
   session,
   isConnected,
 }: WaitingScreenProps) {
+  const config = useConfig();
   const nextSongs = queue
     .filter((item) => item.status === "pending")
     .slice(0, 3);
@@ -83,7 +85,7 @@ export function WaitingScreen({
               <div className="text-lg text-gray-400 mb-2">
                 Visit{" "}
                 <span className="text-purple-400 font-mono">
-                  {process.env.NEXT_PUBLIC_APP_URL || "http://localhost:3000"}
+                  {config.appUrl}
                 </span>{" "}
                 on your mobile device
               </div>
diff --git a/src/contexts/ConfigContext.tsx b/src/contexts/ConfigContext.tsx
@@ -0,0 +1,27 @@
+"use client";
+
+import { createContext, useContext, ReactNode } from "react";
+import { AppConfig } from "@/lib/config";
+
+const ConfigContext = createContext<AppConfig | null>(null);
+
+interface ConfigProviderProps {
+  children: ReactNode;
+  config: AppConfig;
+}
+
+export function ConfigProvider({ children, config }: ConfigProviderProps) {
+  return (
+    <ConfigContext.Provider value={config}>
+      {children}
+    </ConfigContext.Provider>
+  );
+}
+
+export function useConfig(): AppConfig {
+  const config = useContext(ConfigContext);
+  if (!config) {
+    throw new Error("useConfig must be used within a ConfigProvider");
+  }
+  return config;
+}
diff --git a/src/lib/config.ts b/src/lib/config.ts
@@ -0,0 +1,22 @@
+// Server-side configuration
+export interface AppConfig {
+  appUrl: string;
+  autoplayDelay: number;
+  queueAutoplayDelay: number;
+  controlsAutoHideDelay: number;
+  timeUpdateInterval: number;
+  ratingAnimationDuration: number;
+  nextSongDuration: number;
+}
+
+export function getServerConfig(): AppConfig {
+  return {
+    appUrl: process.env.APP_URL || "http://localhost:3000",
+    autoplayDelay: parseInt(process.env.AUTOPLAY_DELAY || "500"),
+    queueAutoplayDelay: parseInt(process.env.QUEUE_AUTOPLAY_DELAY || "1000"),
+    controlsAutoHideDelay: parseInt(process.env.CONTROLS_AUTO_HIDE_DELAY || "10000"),
+    timeUpdateInterval: parseInt(process.env.TIME_UPDATE_INTERVAL || "2000"),
+    ratingAnimationDuration: parseInt(process.env.RATING_ANIMATION_DURATION || "15000"),
+    nextSongDuration: parseInt(process.env.NEXT_SONG_DURATION || "15000"),
+  };
+}
