feat: Make TV display timing durations configurable via environment variables

- 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

Author: johnpc

DOCKER.md

@@ -67,6 +67,8 @@ 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      |
@@ -77,6 +79,40 @@ This document provides instructions for building and running the Karaoke For Jel
 | `NEXT_PUBLIC_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 |
+| ------------------------------------- | ---------------------------------- | ------- | -------- |
+| `NEXT_PUBLIC_RATING_ANIMATION_DURATION` | Rating screen display duration     | `15000` | No       |
+| `NEXT_PUBLIC_NEXT_SONG_DURATION`        | Next song splash screen duration   | `15000` | No       |
+| `NEXT_PUBLIC_CONTROLS_AUTO_HIDE_DELAY`  | Auto-hide TV controls after inactivity | `10000` | No   |
+| `NEXT_PUBLIC_AUTOPLAY_DELAY`            | Initial autoplay delay             | `500`   | No       |
+| `NEXT_PUBLIC_QUEUE_AUTOPLAY_DELAY`      | Queue autoplay delay               | `1000`  | No       |
+| `NEXT_PUBLIC_TIME_UPDATE_INTERVAL`      | Time update sync interval          | `2000`  | No       |
+
+#### Timing Configuration Examples
+
+**Fast-Paced Party Setup:**
+```bash
+NEXT_PUBLIC_RATING_ANIMATION_DURATION=8000   # 8 seconds
+NEXT_PUBLIC_NEXT_SONG_DURATION=5000          # 5 seconds  
+NEXT_PUBLIC_CONTROLS_AUTO_HIDE_DELAY=5000    # 5 seconds
+```
+
+**Relaxed Home Setup:**
+```bash
+NEXT_PUBLIC_RATING_ANIMATION_DURATION=20000  # 20 seconds
+NEXT_PUBLIC_NEXT_SONG_DURATION=10000         # 10 seconds
+NEXT_PUBLIC_CONTROLS_AUTO_HIDE_DELAY=15000   # 15 seconds
+```
+
+**Commercial Venue Setup:**
+```bash
+NEXT_PUBLIC_RATING_ANIMATION_DURATION=12000  # 12 seconds
+NEXT_PUBLIC_NEXT_SONG_DURATION=8000          # 8 seconds
+NEXT_PUBLIC_TIME_UPDATE_INTERVAL=1000        # 1 second (tighter sync)
+```
+
 ### Volume Mounts
 
 - **Lyrics Directory**: Mount your lyrics folder to `/app/lyrics` (read-only)

docker-compose.yml

@@ -11,8 +11,20 @@ services:
       - JELLYFIN_USERNAME=${JELLYFIN_USERNAME}
       - LYRICS_PATH=/app/lyrics
       - JELLYFIN_MEDIA_PATH=/app/media
+      
+      # Application Configuration
       - NEXT_PUBLIC_APP_URL=${NEXT_PUBLIC_APP_URL:-http://localhost:3000}
       - SESSION_SECRET=${SESSION_SECRET:-default_session_secret_change_in_production}
+      
+      # TV Display Timing Configuration (in milliseconds)
+      - NEXT_PUBLIC_RATING_ANIMATION_DURATION=${NEXT_PUBLIC_RATING_ANIMATION_DURATION:-15000}
+      - NEXT_PUBLIC_NEXT_SONG_DURATION=${NEXT_PUBLIC_NEXT_SONG_DURATION:-15000}
+      - NEXT_PUBLIC_CONTROLS_AUTO_HIDE_DELAY=${NEXT_PUBLIC_CONTROLS_AUTO_HIDE_DELAY:-10000}
+      - NEXT_PUBLIC_AUTOPLAY_DELAY=${NEXT_PUBLIC_AUTOPLAY_DELAY:-500}
+      - NEXT_PUBLIC_QUEUE_AUTOPLAY_DELAY=${NEXT_PUBLIC_QUEUE_AUTOPLAY_DELAY:-1000}
+      - NEXT_PUBLIC_TIME_UPDATE_INTERVAL=${NEXT_PUBLIC_TIME_UPDATE_INTERVAL:-2000}
+      
+      # System Configuration
       - NODE_ENV=production
       - PORT=3000
       - HOSTNAME=0.0.0.0

src/app/tv/page.tsx

@@ -128,7 +128,7 @@ export default function TVDisplay() {
     setTimeout(() => {
       console.log("🎵 Emitting start-next-song to server");
       startNextSong();
-    }, 500);
+    }, parseInt(process.env.NEXT_PUBLIC_AUTOPLAY_DELAY || "500"));
   };
 
   useEffect(() => {
@@ -164,7 +164,7 @@ export default function TVDisplay() {
           userId: "tv-display-autoplay",
           timestamp: new Date(),
         });
-      }, 500);
+      }, parseInt(process.env.NEXT_PUBLIC_AUTOPLAY_DELAY || "500"));
 
       return () => clearTimeout(autoPlayTimer);
     }
@@ -201,7 +201,7 @@ export default function TVDisplay() {
             userId: "tv-display-queue-autoplay",
             timestamp: new Date(),
           });
-        }, 1000);
+        }, parseInt(process.env.NEXT_PUBLIC_QUEUE_AUTOPLAY_DELAY || "1000"));
 
         return () => clearTimeout(queueAutoPlayTimer);
       }
@@ -270,7 +270,7 @@ export default function TVDisplay() {
       const timer = setTimeout(() => {
         setShowHostControls(false);
         setShowQueuePreview(false);
-      }, 10000);
+      }, parseInt(process.env.NEXT_PUBLIC_CONTROLS_AUTO_HIDE_DELAY || "10000"));
 
       return () => clearTimeout(timer);
     }
@@ -300,7 +300,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 = parseInt(process.env.NEXT_PUBLIC_TIME_UPDATE_INTERVAL || "2000");
+    if (!lastUpdateRef.current || now - lastUpdateRef.current > updateInterval) {
       playbackControl({
         action: "time-update",
         value: currentTime,
@@ -372,13 +373,13 @@ export default function TVDisplay() {
           song={transitionState.completedSong}
           rating={transitionState.rating}
           onComplete={handleRatingComplete}
-          duration={15000}
+          duration={parseInt(process.env.NEXT_PUBLIC_RATING_ANIMATION_DURATION || "15000")}
         />
       ) : transitionState.displayState === "next-up" && transitionState.nextSong ? (
         <NextSongSplash
           nextSong={transitionState.nextSong}
           onComplete={handleNextSongComplete}
-          duration={15000}
+          duration={parseInt(process.env.NEXT_PUBLIC_NEXT_SONG_DURATION || "15000")}
         />
       ) : (
         <WaitingScreen