klaudio 0.5.3 → 0.6.0

package/README.md

@@ -10,7 +10,7 @@ npx klaudio
 
 The interactive installer walks you through:
 
-1. **Choose scope** — install globally (`~/.claude`) or per-project (`.claude/`)
+1. **Choose scope** — install globally (`~/.claude`) or per-project (`.claude/`), or launch the **Music Player**
 2. **Pick a source** — use a built-in preset, scan your Steam & Epic Games library for sounds, or provide custom files
 3. **Preview & assign** — listen to sounds and assign them to events (tab to switch between events)
 4. **Install** — writes Claude Code hooks to your `settings.json`
@@ -36,6 +36,17 @@ Scans your local Steam and Epic Games libraries for audio files:
 
 Point to your own `.wav`/`.mp3` files.
 
+## Music Player
+
+Play longer game tracks (90s–4min) as background music while you code:
+
+- **Shuffle all** — scans all cached game audio, filters by duration, picks random tracks continuously
+- **Play songs from game** — pick a specific cached game and play its music
+- Controls: `n` next, `space` pause/resume, `esc` back
+- Background scanning — starts playing as soon as the first track is found, keeps indexing
+
+Requires previously extracted game audio (use "Scan local games" first).
+
 ## Features
 
 - **Auto-preview** — sounds play automatically as you browse the list (toggle with `p`)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "klaudio",
-  "version": "0.5.3",
+  "version": "0.6.0",
   "description": "Add sound effects to your coding sessions — play sounds when tasks complete, notifications arrive, and more",
   "type": "module",
   "bin": {

package/src/cache.js

@@ -153,6 +153,33 @@ function gameCacheDir(gameName) {
   return join(CACHE_DIR, gameName.replace(/[^a-zA-Z0-9_-]/g, "_"));
 }
 
+/**
+ * List all cached games with their files.
+ * Returns array of { gameName, files[] }.
+ */
+export async function listCachedGames() {
+  const games = [];
+  try {
+    const entries = await readdir(CACHE_DIR, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      try {
+        const manifest = JSON.parse(
+          await readFile(join(CACHE_DIR, entry.name, "manifest.json"), "utf-8")
+        );
+        if (manifest.files?.length > 0) {
+          // Verify at least one file still exists
+          try {
+            await stat(join(CACHE_DIR, entry.name, manifest.files[0].name));
+            games.push({ gameName: manifest.gameName, files: manifest.files });
+          } catch { /* files cleaned up, skip */ }
+        }
+      } catch { /* no manifest, skip */ }
+    }
+  } catch { /* cache dir doesn't exist */ }
+  return games;
+}
+
 /**
  * Check if we have a cached extraction for a game.
  * Returns the manifest if cached, null otherwise.

package/src/cli.js

@@ -1,4 +1,4 @@
-import React, { useState, useEffect, useCallback, useRef } from "react";
+import React, { useState, useEffect, useCallback, useRef, useMemo } from "react";
 import { render, Box, Text, useInput, useApp } from "ink";
 import Spinner from "ink-spinner";
 import { PRESETS, EVENTS } from "./presets.js";
@@ -8,7 +8,7 @@ import { install, uninstall, getExistingSounds } from "./installer.js";
 import { getVgmstreamPath, findPackedAudioFiles, extractToWav } from "./extractor.js";
 import { extractUnityResource } from "./unity.js";
 import { extractBunFile, isBunFile } from "./scumm.js";
-import { getCachedExtraction, cacheExtraction, categorizeLooseFiles, getCategories, sortFilesByPriority } from "./cache.js";
+import { getCachedExtraction, cacheExtraction, categorizeLooseFiles, getCategories, sortFilesByPriority, listCachedGames } from "./cache.js";
 import { basename, dirname } from "node:path";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
@@ -90,6 +90,9 @@ const SCREEN = {
   CONFIRM: 7,
   INSTALLING: 8,
   DONE: 9,
+  MUSIC_MODE: 10,
+  MUSIC_GAME_PICK: 11,
+  MUSIC_PLAYING: 12,
 };
 
 const isUninstallMode = process.argv.includes("--uninstall") || process.argv.includes("--remove");
@@ -112,15 +115,38 @@ const NavHint = ({ back = true, extra = "" }) =>
   );
 
 // ── Screen: Scope ───────────────────────────────────────────────
-const ScopeScreen = ({ onNext }) => {
+const ScopeScreen = ({ onNext, onMusic }) => {
   const items = [
-    { label: "Global — Claude Code + VS Code Copilot (all projects)", value: "global" },
-    { label: "This project — Claude Code + Copilot (incl. GitHub agent)", value: "project" },
+    { label: "Global — Claude Code + Copilot (all projects)", value: "global" },
+    { label: "This project — Claude Code + Copilot (this project only)", value: "project" },
+    // index 2 = music
+    { label: "🎵 Play game music while you code", value: "_music" },
   ];
+  const [sel, setSel] = useState(0);
+  const GAP_AT = 2; // visual gap before this index
+
+  useInput((input, key) => {
+    if (input === "k" || key.upArrow) {
+      setSel((i) => Math.max(0, i - 1));
+    } else if (input === "j" || key.downArrow) {
+      setSel((i) => Math.min(items.length - 1, i + 1));
+    } else if (key.return) {
+      const v = items[sel].value;
+      if (v === "_music") onMusic();
+      else onNext(v);
+    }
+  });
+
   return h(Box, { flexDirection: "column" },
     h(Text, { bold: true }, "  Where should sounds be installed?"),
-    h(Box, { marginLeft: 2 },
-      h(SelectInput, { indicatorComponent: Indicator, itemComponent: Item, items, onSelect: (item) => onNext(item.value) }),
+    h(Box, { flexDirection: "column", marginLeft: 2 },
+      ...items.map((item, i) => h(React.Fragment, { key: item.value },
+        i === GAP_AT ? h(Text, { dimColor: true }, "\n  ...or") : null,
+        h(Box, null,
+          h(Indicator, { isSelected: i === sel }),
+          h(Item, { isSelected: i === sel, label: item.label }),
+        ),
+      )),
     ),
   );
 };
@@ -450,13 +476,13 @@ const GameSoundsScreen = ({ game, sounds, onSelectSound, onDone, onBack }) => {
   const meaningfulCats = categories.filter((c) => c !== "all" && (counts[c] || 0) >= 2);
   const showCategoryPicker = meaningfulCats.length >= 2;
 
-  // Sort files: voice first, then by priority
-  const sortedFiles = hasCategories ? sortFilesByPriority(game.files) : game.files;
+  // Sort files: voice first, then by priority (memoized for stable references)
+  const sortedFiles = useMemo(() => hasCategories ? sortFilesByPriority(game.files) : game.files, [game.files, hasCategories]);
 
-  // Filter files by category (no hard cap — SelectInput handles visible window)
-  const categoryFiles = activeCategory && activeCategory !== "all"
+  // Filter files by category (memoized to prevent infinite re-render loops)
+  const categoryFiles = useMemo(() => activeCategory && activeCategory !== "all"
     ? sortedFiles.filter((f) => f.category === activeCategory)
-    : sortedFiles;
+    : sortedFiles, [sortedFiles, activeCategory]);
 
   // Stop current playback helper
   const stopPlayback = useCallback(() => {
@@ -803,6 +829,268 @@ const GameSoundsScreen = ({ game, sounds, onSelectSound, onDone, onBack }) => {
   );
 };
 
+// ── Helpers for Music Player ─────────────────────────────────────
+const formatTime = (secs) => {
+  const m = Math.floor(secs / 60);
+  const s = Math.floor(secs % 60);
+  return `${m}:${s.toString().padStart(2, "0")}`;
+};
+
+// ── Screen: Music Mode ──────────────────────────────────────────
+const MusicModeScreen = ({ onRandom, onPickGame, onBack }) => {
+  useInput((_, key) => { if (key.escape) onBack(); });
+
+  const items = [
+    { label: "🎲 Shuffle all  — play random songs from all cached games", value: "random" },
+    { label: "🎮 Play songs from game  — choose a game", value: "game" },
+  ];
+
+  return h(Box, { flexDirection: "column" },
+    h(Text, { bold: true, marginLeft: 2 }, "  🎵 Music Player"),
+    h(Text, { dimColor: true, marginLeft: 2 }, "  Play longer game tracks as background music"),
+    h(Box, { marginTop: 1, marginLeft: 2 },
+      h(SelectInput, { indicatorComponent: Indicator, itemComponent: Item, items,
+        onSelect: (item) => {
+          if (item.value === "random") onRandom();
+          else onPickGame();
+        },
+      }),
+    ),
+    h(NavHint, { back: true }),
+  );
+};
+
+// ── Screen: Music Game Pick ─────────────────────────────────────
+const MusicGamePickScreen = ({ onNext, onBack }) => {
+  const [games, setGames] = useState([]);
+  const [loading, setLoading] = useState(true);
+
+  useInput((_, key) => { if (key.escape) onBack(); });
+
+  useEffect(() => {
+    let cancelled = false;
+    listCachedGames().then((cached) => {
+      if (!cancelled) {
+        setGames(cached);
+        setLoading(false);
+      }
+    });
+    return () => { cancelled = true; };
+  }, []);
+
+  if (loading) {
+    return h(Box, { flexDirection: "column" },
+      h(Box, { marginLeft: 2 },
+        h(Text, { color: ACCENT }, h(Spinner, { type: "dots" })),
+        h(Text, null, " Scanning cached games..."),
+      ),
+    );
+  }
+
+  if (games.length === 0) {
+    return h(Box, { flexDirection: "column" },
+      h(Text, { color: "yellow", marginLeft: 2 }, "  No cached games found."),
+      h(Text, { dimColor: true, marginLeft: 2 }, "  Use \"Scan local games\" first to extract game audio."),
+      h(NavHint, { back: true }),
+    );
+  }
+
+  const items = games.map((g) => ({
+    label: `${g.gameName}  (${g.files.length} files)`,
+    value: g.gameName,
+  }));
+
+  return h(Box, { flexDirection: "column" },
+    h(Text, { bold: true, marginLeft: 2 }, "  Pick a game:"),
+    h(Box, { marginLeft: 2 },
+      h(SelectInput, { indicatorComponent: Indicator, itemComponent: Item, items, limit: 15,
+        onSelect: (item) => {
+          const game = games.find((g) => g.gameName === item.value);
+          onNext(game);
+        },
+      }),
+    ),
+    h(NavHint, { back: true }),
+  );
+};
+
+// ── Screen: Music Playing ───────────────────────────────────────
+const MusicPlayingScreen = ({ files, gameName, shuffle: initialShuffle, onBack }) => {
+  const [track, setTrack] = useState(null);       // current track { path, name, displayName, duration }
+  const [loading, setLoading] = useState(true);
+  const [scanProgress, setScanProgress] = useState({ done: 0, total: files.length, found: 0 });
+  const [scanDone, setScanDone] = useState(false);
+  const [playing, setPlaying] = useState(false);
+  const [paused, setPaused] = useState(false);
+  const [elapsed, setElapsed] = useState(0);
+  const [poolSize, setPoolSize] = useState(0);
+  const cancelRef = useRef(null);
+  const pauseRef = useRef(null);
+  const resumeRef = useRef(null);
+  const versionRef = useRef(0);
+  const poolRef = useRef([]);       // ever-growing pool of qualifying tracks
+  const lastPlayedRef = useRef(-1); // index of last played track in pool
+
+  // Pick a random track from the pool (different from last played)
+  const pickFromPool = useCallback(() => {
+    const pool = poolRef.current;
+    if (pool.length === 0) return null;
+    if (pool.length === 1) return pool[0];
+    let idx;
+    do { idx = Math.floor(Math.random() * pool.length); } while (idx === lastPlayedRef.current && pool.length > 1);
+    lastPlayedRef.current = idx;
+    return pool[idx];
+  }, []);
+
+  // Scan files for duration (90s-4min), pick first random once found, keep scanning in background
+  const startedRef = useRef(false);
+  useEffect(() => {
+    let cancelled = false;
+    (async () => {
+      const BATCH = 20;
+      for (let i = 0; i < files.length; i += BATCH) {
+        if (cancelled) return;
+        const batch = files.slice(i, i + BATCH);
+        const results = await Promise.all(batch.map(async (f) => {
+          const dur = await getWavDuration(f.path);
+          return { ...f, duration: dur };
+        }));
+        for (const r of results) {
+          if (r.duration != null && r.duration >= 90 && r.duration <= 240) {
+            poolRef.current.push(r);
+          }
+        }
+        const found = poolRef.current.length;
+        setScanProgress({ done: Math.min(i + BATCH, files.length), total: files.length, found });
+        setPoolSize(found);
+        // Start playing the first time we find a qualifying track
+        if (found >= 1 && !startedRef.current && !cancelled) {
+          startedRef.current = true;
+          setTrack(pickFromPool());
+          setLoading(false);
+        }
+      }
+      if (!cancelled) {
+        setScanDone(true);
+        setPoolSize(poolRef.current.length);
+        if (!startedRef.current) {
+          startedRef.current = true;
+          if (poolRef.current.length > 0) {
+            setTrack(pickFromPool());
+          }
+          setLoading(false);
+        }
+      }
+    })();
+    return () => { cancelled = true; };
+  }, []);
+
+  // Play current track
+  useEffect(() => {
+    if (!track) return;
+
+    const myVersion = ++versionRef.current;
+    const { promise, cancel, pause, resume } = playSoundWithCancel(track.path, { maxSeconds: 0 });
+    cancelRef.current = cancel;
+    pauseRef.current = pause;
+    resumeRef.current = resume;
+    setPlaying(true);
+    setPaused(false);
+    setElapsed(0);
+
+    promise.then(() => {
+      if (versionRef.current === myVersion) {
+        // Track ended naturally — pick next random from pool
+        const next = pickFromPool();
+        if (next) setTrack(next);
+      }
+    }).catch(() => {});
+
+    return () => cancel();
+  }, [track]);
+
+  // Elapsed timer
+  useEffect(() => {
+    if (!playing || paused) return;
+    const interval = setInterval(() => setElapsed((e) => e + 1), 1000);
+    return () => clearInterval(interval);
+  }, [playing, paused]);
+
+  // Controls
+  useInput((input, key) => {
+    if (key.escape) {
+      if (cancelRef.current) cancelRef.current();
+      onBack();
+    } else if (input === "n") {
+      versionRef.current++;
+      if (cancelRef.current) cancelRef.current();
+      const next = pickFromPool();
+      if (next) setTrack(next);
+    } else if (input === " ") {
+      if (paused) {
+        if (resumeRef.current) resumeRef.current();
+        setPaused(false);
+      } else {
+        if (pauseRef.current) pauseRef.current();
+        setPaused(true);
+      }
+    }
+  });
+
+  // Loading state
+  if (loading) {
+    return h(Box, { flexDirection: "column" },
+      h(Box, { marginLeft: 2, flexDirection: "column", borderStyle: "round", borderColor: ACCENT, paddingX: 2 },
+        h(Text, { bold: true, color: ACCENT }, `🎵 ${gameName || "Music Player"}`),
+        h(Box, { marginTop: 1 },
+          h(Text, { color: ACCENT }, h(Spinner, { type: "dots" })),
+          h(Text, null, ` Scanning for music tracks... ${scanProgress.found} found (${scanProgress.done}/${scanProgress.total})`),
+        ),
+      ),
+      h(NavHint, { back: true }),
+    );
+  }
+
+  if (!track) {
+    return h(Box, { flexDirection: "column" },
+      h(Text, { color: "yellow", marginLeft: 2 }, "  No tracks between 90s–4min found."),
+      h(Text, { dimColor: true, marginLeft: 2 }, "  Try a different game or source."),
+      h(NavHint, { back: true }),
+    );
+  }
+
+  const trackName = track.displayName || track.name || basename(track.path);
+
+  return h(Box, { flexDirection: "column" },
+    h(Box, { marginLeft: 2, flexDirection: "column", borderStyle: "round", borderColor: paused ? "yellow" : "green", paddingX: 2 },
+      h(Text, { bold: true, color: paused ? "yellow" : "green" }, `🎵 ${gameName || "Music Player"}`),
+      h(Box, { marginTop: 1 },
+        h(Text, { color: paused ? "yellow" : "green", bold: true },
+          paused ? "⏸ " : "▶ ",
+        ),
+        h(Text, { bold: true }, trackName),
+      ),
+      track.gameName
+        ? h(Text, { dimColor: true }, `  ${track.gameName}`)
+        : null,
+      h(Text, { dimColor: true },
+        `  ${formatTime(elapsed)} / ${formatTime(track.duration || 0)}`,
+      ),
+    ),
+    h(Box, { marginTop: 1, marginLeft: 4 },
+      scanDone
+        ? h(Text, { dimColor: true }, `${poolSize} music tracks indexed`)
+        : h(Box, null,
+            h(Text, { color: ACCENT }, h(Spinner, { type: "dots" })),
+            h(Text, { dimColor: true }, ` ${poolSize} music tracks indexed (${scanProgress.done}/${scanProgress.total} scanned)`),
+          ),
+    ),
+    h(Box, { marginTop: 1, marginLeft: 4 },
+      h(Text, { dimColor: true }, "n next  space pause  esc back"),
+    ),
+  );
+};
+
 // ── Screen: Extracting ──────────────────────────────────────────
 const ExtractingScreen = ({ game, onDone, onBack }) => {
   const [status, setStatus] = useState("Checking cache...");
@@ -973,7 +1261,7 @@ const ConfirmScreen = ({ scope, sounds, onConfirm, onBack }) => {
   return h(Box, { flexDirection: "column" },
     h(Text, { bold: true, marginLeft: 2 }, "  Ready to install:"),
     h(Box, { marginTop: 1, flexDirection: "column" },
-      h(Text, { marginLeft: 4 }, `Scope: ${scope === "global" ? "Global (Claude Code + VS Code Copilot)" : "This project (Claude Code + Copilot + GitHub agent)"}`),
+      h(Text, { marginLeft: 4 }, `Scope: ${scope === "global" ? "Global (Claude Code + Copilot)" : "This project (Claude Code + Copilot)"}`),
       ...soundEntries.map(([eid, path]) =>
         h(Text, { key: eid, marginLeft: 4 },
           `${EVENTS[eid].name} → ${basename(path)}`
@@ -1101,6 +1389,9 @@ const InstallApp = () => {
   const [sounds, setSounds] = useState({});
   const [selectedGame, setSelectedGame] = useState(null);
   const [installResult, setInstallResult] = useState(null);
+  const [musicFiles, setMusicFiles] = useState([]);
+  const [musicGameName, setMusicGameName] = useState(null);
+  const [musicShuffle, setMusicShuffle] = useState(false);
 
   const initSoundsFromPreset = useCallback((pid) => {
     const preset = PRESETS[pid];
@@ -1118,12 +1409,15 @@ const InstallApp = () => {
             });
             setScreen(SCREEN.PRESET);
           },
+          onMusic: () => setScreen(SCREEN.MUSIC_MODE),
         });
 
       case SCREEN.PRESET:
         return h(PresetScreen, {
           onNext: (id) => {
-            if (id === "_scan") {
+            if (id === "_music") {
+              setScreen(SCREEN.MUSIC_MODE);
+            } else if (id === "_scan") {
               setScreen(SCREEN.GAME_PICK);
             } else if (id === "_custom") {
               const firstPreset = Object.keys(PRESETS)[0];
@@ -1232,6 +1526,40 @@ const InstallApp = () => {
       case SCREEN.DONE:
         return h(DoneScreen, { result: installResult });
 
+      case SCREEN.MUSIC_MODE:
+        return h(MusicModeScreen, {
+          onRandom: () => {
+            listCachedGames().then((games) => {
+              const allFiles = games.flatMap((g) => g.files.map((f) => ({ ...f, gameName: g.gameName })));
+              setMusicFiles(allFiles);
+              setMusicGameName("All Games");
+              setMusicShuffle(true);
+              setScreen(SCREEN.MUSIC_PLAYING);
+            });
+          },
+          onPickGame: () => setScreen(SCREEN.MUSIC_GAME_PICK),
+          onBack: () => setScreen(SCREEN.SCOPE),
+        });
+
+      case SCREEN.MUSIC_GAME_PICK:
+        return h(MusicGamePickScreen, {
+          onNext: (game) => {
+            setMusicFiles(game.files);
+            setMusicGameName(game.gameName);
+            setMusicShuffle(false);
+            setScreen(SCREEN.MUSIC_PLAYING);
+          },
+          onBack: () => setScreen(SCREEN.MUSIC_MODE),
+        });
+
+      case SCREEN.MUSIC_PLAYING:
+        return h(MusicPlayingScreen, {
+          files: musicFiles,
+          gameName: musicGameName,
+          shuffle: musicShuffle,
+          onBack: () => setScreen(SCREEN.MUSIC_MODE),
+        });
+
       default:
         return h(Text, { color: "red" }, "Unknown screen");
     }

package/src/player.js

@@ -14,7 +14,7 @@ const MEDIA_PLAYER_FORMATS = new Set([".wav", ".mp3", ".wma", ".aac"]);
 /**
  * Determine the best playback strategy for a file on the current OS.
  */
-function getPlaybackCommand(absPath, { withFade = false } = {}) {
+function getPlaybackCommand(absPath, { withFade = false, maxSeconds = MAX_PLAY_SECONDS } = {}) {
   const os = platform();
   const ext = extname(absPath).toLowerCase();
 
@@ -22,14 +22,14 @@ function getPlaybackCommand(absPath, { withFade = false } = {}) {
   const ffplayArgs = ["-nodisp", "-autoexit", "-loglevel", "quiet"];
   if (withFade) {
     // silenceremove strips leading silence (below -50dB threshold)
-    // afade fades out over last FADE_SECONDS before the MAX_PLAY_SECONDS cut
-    const fadeStart = MAX_PLAY_SECONDS - FADE_SECONDS;
+    // afade fades out over last FADE_SECONDS before the maxSeconds cut
+    const fadeStart = maxSeconds - FADE_SECONDS;
     const filters = [
       "silenceremove=start_periods=1:start_silence=0.1:start_threshold=-50dB",
       `afade=t=out:st=${fadeStart}:d=${FADE_SECONDS}`,
     ];
     ffplayArgs.push("-af", filters.join(","));
-    ffplayArgs.push("-t", String(MAX_PLAY_SECONDS));
+    ffplayArgs.push("-t", String(maxSeconds));
   }
   ffplayArgs.push(absPath);
 
@@ -197,9 +197,10 @@ export function playSound(filePath) {
  * Returns { promise, cancel } — call cancel() to stop playback immediately.
  * Playback is clamped to MAX_PLAY_SECONDS.
  */
-export function playSoundWithCancel(filePath) {
+export function playSoundWithCancel(filePath, { maxSeconds = MAX_PLAY_SECONDS } = {}) {
+  const uncapped = !maxSeconds;
   const absPath = resolve(filePath);
-  const strategy = getPlaybackCommand(absPath, { withFade: true });
+  const strategy = getPlaybackCommand(absPath, { withFade: !uncapped, maxSeconds });
   let childProcess = null;
   let timer = null;
   let cancelled = false;
@@ -234,48 +235,66 @@ export function playSoundWithCancel(filePath) {
     }
 
     function startExec(cmd, args) {
-      childProcess = execFile(cmd, args, { windowsHide: true, timeout: (MAX_PLAY_SECONDS + 2) * 1000 }, (err) => {
+      const execTimeout = uncapped ? 0 : (maxSeconds + 2) * 1000;
+      childProcess = execFile(cmd, args, { windowsHide: true, timeout: execTimeout }, (err) => {
         if (err && strategy.fallback && !cancelled) {
           if (strategy.fallback === "powershell") {
             childProcess = execFile(
               "powershell.exe",
-              ["-NoProfile", "-Command", buildPsCommand(absPath, MAX_PLAY_SECONDS)],
-              { windowsHide: true, timeout: (MAX_PLAY_SECONDS + 2) * 1000 },
+              ["-NoProfile", "-Command", buildPsCommand(absPath, uncapped ? 0 : maxSeconds)],
+              { windowsHide: true, timeout: execTimeout },
               (psErr) => onDone(psErr)
             );
           } else if (strategy.fallback === "afplay") {
             // macOS: ffplay not available, fall back to afplay (no fade)
-            childProcess = execFile("afplay", [absPath], { timeout: (MAX_PLAY_SECONDS + 2) * 1000 }, (afErr) => onDone(afErr));
+            childProcess = execFile("afplay", [absPath], { timeout: execTimeout }, (afErr) => onDone(afErr));
           }
         } else {
           onDone(err);
         }
       });
 
-      // Set a hard timeout to kill after MAX_PLAY_SECONDS
-      timer = setTimeout(() => {
-        killChild();
-        resolvePromise();
-      }, MAX_PLAY_SECONDS * 1000);
+      // Set a hard timeout to kill after maxSeconds (skip if uncapped)
+      if (!uncapped) {
+        timer = setTimeout(() => {
+          killChild();
+          resolvePromise();
+        }, maxSeconds * 1000);
+      }
     }
 
     if (strategy.type === "exec") {
       startExec(strategy.cmd, strategy.args);
     } else if (strategy.type === "powershell") {
+      const execTimeout = uncapped ? 0 : (maxSeconds + 2) * 1000;
       childProcess = execFile(
         "powershell.exe",
-        ["-NoProfile", "-Command", buildPsCommand(absPath, MAX_PLAY_SECONDS)],
-        { windowsHide: true, timeout: (MAX_PLAY_SECONDS + 2) * 1000 },
+        ["-NoProfile", "-Command", buildPsCommand(absPath, uncapped ? 0 : maxSeconds)],
+        { windowsHide: true, timeout: execTimeout },
         (err) => onDone(err)
       );
-      timer = setTimeout(() => {
-        killChild();
-        resolvePromise();
-      }, MAX_PLAY_SECONDS * 1000);
+      if (!uncapped) {
+        timer = setTimeout(() => {
+          killChild();
+          resolvePromise();
+        }, maxSeconds * 1000);
+      }
     }
   });
 
-  return { promise, cancel };
+  const pause = () => {
+    if (childProcess && !childProcess.killed && platform() !== "win32") {
+      try { process.kill(childProcess.pid, "SIGSTOP"); } catch { /* ignore */ }
+    }
+  };
+
+  const resume = () => {
+    if (childProcess && !childProcess.killed && platform() !== "win32") {
+      try { process.kill(childProcess.pid, "SIGCONT"); } catch { /* ignore */ }
+    }
+  };
+
+  return { promise, cancel, pause, resume };
 }
 
 /**