@involvex/youtube-music-cli 0.0.14 → 0.0.16

package/CHANGELOG.md

@@ -1,3 +1,23 @@
+## [0.0.16](https://github.com/involvex/youtube-music-cli/compare/v0.0.15...v0.0.16) (2026-02-18)
+
+### Bug Fixes
+
+- correct shuffle hotkey and mpv error handling ([7a08643](https://github.com/involvex/youtube-music-cli/commit/7a0864395b48c8bc1b30d817edc5b2f7cb9c79c6))
+
+### Features
+
+- implement shuffle mode with Shift+S hotkey ([77be9ae](https://github.com/involvex/youtube-music-cli/commit/77be9ae53650dc3bf40a89427fbb1b6eef32683a))
+
+## [0.0.15](https://github.com/involvex/youtube-music-cli/compare/v0.0.14...v0.0.15) (2026-02-18)
+
+### Features
+
+- **ui:** remove escape key from quit keybinding ([df6e794](https://github.com/involvex/youtube-music-cli/commit/df6e794583aa96a1dd27b1ff208f3f1b69249829))
+
+### BREAKING CHANGES
+
+- **ui:** 'escape' no longer quits; use 'q' instead.
+
 ## [0.0.14](https://github.com/involvex/youtube-music-cli/compare/v0.0.13...v0.0.14) (2026-02-18)
 
 ### Features

package/dist/source/components/common/Help.js

@@ -6,5 +6,5 @@ import { useNavigation } from "../../hooks/useNavigation.js";
 export default function Help() {
     const { theme } = useTheme();
     const { dispatch: _dispatch } = useNavigation();
-    return (_jsxs(Box, { flexDirection: "column", gap: 1, padding: 1, children: [_jsx(Box, { borderStyle: "single", borderColor: theme.colors.secondary, paddingX: 1, children: _jsx(Text, { bold: true, color: theme.colors.primary, children: "Keyboard Shortcuts" }) }), _jsxs(Box, { flexDirection: "column", gap: 1, children: [_jsx(Text, { bold: true, color: theme.colors.secondary, children: "Global" }), _jsx(Box, { paddingX: 2, children: _jsxs(Text, { children: [_jsx(Text, { color: theme.colors.text, children: "q / Esc" }), " - Quit", _jsx(Text, { children: " | " }), _jsx(Text, { color: theme.colors.text, children: "?" }), " - Help", _jsx(Text, { children: " | " }), _jsx(Text, { color: theme.colors.text, children: "/" }), " - Search", _jsx(Text, { children: " | " }), _jsx(Text, { color: theme.colors.text, children: "Shift+P" }), " - Playlists", _jsx(Text, { children: " | " }), _jsx(Text, { color: theme.colors.text, children: "p" }), " - Plugins", _jsx(Text, { children: " | " }), _jsx(Text, { color: theme.colors.text, children: "g" }), " - Suggestions", _jsx(Text, { children: " | " }), _jsx(Text, { color: theme.colors.text, children: "," }), " - Settings"] }) }), _jsx(Text, { bold: true, color: theme.colors.secondary, children: "Player" }), _jsx(Box, { paddingX: 2, children: _jsxs(Text, { children: [_jsx(Text, { color: theme.colors.text, children: "Space" }), " - Play/Pause", _jsx(Text, { children: " | " }), _jsx(Text, { color: theme.colors.text, children: "n" }), " - Next", _jsx(Text, { children: " | " }), _jsx(Text, { color: theme.colors.text, children: "b" }), " - Previous", _jsx(Text, { children: " | " }), _jsx(Text, { color: theme.colors.text, children: "=" }), " - Volume Up", _jsx(Text, { children: " | " }), _jsx(Text, { color: theme.colors.text, children: "-" }), " - Volume Down", _jsx(Text, { children: " | " }), _jsx(Text, { color: theme.colors.text, children: "s" }), " - Toggle Shuffle", _jsx(Text, { children: " | " }), _jsx(Text, { color: theme.colors.text, children: "r" }), " - Toggle Repeat"] }) }), _jsx(Text, { bold: true, color: theme.colors.secondary, children: "Navigation" }), _jsx(Box, { paddingX: 2, children: _jsxs(Text, { children: [_jsx(Text, { color: theme.colors.text, children: "Up" }), " /", _jsx(Text, { children: " " }), _jsx(Text, { color: theme.colors.text, children: "k" }), " - Move Up", _jsx(Text, { children: " | " }), _jsx(Text, { color: theme.colors.text, children: "Down" }), " /", _jsx(Text, { children: " " }), _jsx(Text, { color: theme.colors.text, children: "j" }), " - Move Down", _jsx(Text, { children: " | " }), _jsx(Text, { color: theme.colors.text, children: "Enter" }), " - Select", _jsx(Text, { children: " | " }), _jsx(Text, { color: theme.colors.text, children: "Esc" }), " - Go Back"] }) }), _jsx(Text, { bold: true, color: theme.colors.secondary, children: "Search" }), _jsx(Box, { paddingX: 2, children: _jsxs(Text, { children: [_jsx(Text, { color: theme.colors.text, children: "Tab" }), " - Switch Search Type", _jsx(Text, { children: " | " }), _jsx(Text, { color: theme.colors.text, children: "m" }), " - Create Mix Playlist", _jsx(Text, { children: " | " }), _jsx(Text, { color: theme.colors.text, children: "Shift+D" }), " - Download selection", _jsx(Text, { children: " | " }), _jsx(Text, { color: theme.colors.text, children: "Esc" }), " - Clear Search", _jsx(Text, { children: " | " }), _jsx(Text, { color: theme.colors.text, children: "[ / ]" }), " - Results Limit"] }) }), _jsx(Text, { bold: true, color: theme.colors.secondary, children: "Playlist" }), _jsx(Box, { paddingX: 2, children: _jsxs(Text, { children: [_jsx(Text, { color: theme.colors.text, children: "a" }), " - Add to Playlist", _jsx(Text, { children: " | " }), _jsx(Text, { color: theme.colors.text, children: "d" }), " - Remove from Playlist", _jsx(Text, { children: " | " }), _jsx(Text, { color: theme.colors.text, children: "c" }), " - Create Playlist", _jsx(Text, { children: " | " }), _jsx(Text, { color: theme.colors.text, children: "Shift+D" }), " - Download Playlist", _jsx(Text, { children: " | " }), _jsx(Text, { color: theme.colors.text, children: "D" }), " - Delete Playlist"] }) }), _jsx(Text, { bold: true, color: theme.colors.secondary, children: "View" }), _jsx(Box, { paddingX: 2, children: _jsxs(Text, { children: [_jsx(Text, { color: theme.colors.text, children: "M" }), " - Toggle Mini Player", _jsx(Text, { children: " | " }), _jsx(Text, { color: theme.colors.text, children: "l" }), " - Lyrics", _jsx(Text, { children: " | " }), _jsx(Text, { color: theme.colors.text, children: "T" }), " - Trending", _jsx(Text, { children: " | " }), _jsx(Text, { color: theme.colors.text, children: "e" }), " - Explore"] }) }), _jsxs(Text, { color: theme.colors.dim, children: ["Press ", _jsx(Text, { color: theme.colors.text, children: "Esc" }), " or", ' ', _jsx(Text, { color: theme.colors.text, children: "?" }), " to close"] })] })] }));
+    return (_jsxs(Box, { flexDirection: "column", gap: 1, padding: 1, children: [_jsx(Box, { borderStyle: "single", borderColor: theme.colors.secondary, paddingX: 1, children: _jsx(Text, { bold: true, color: theme.colors.primary, children: "Keyboard Shortcuts" }) }), _jsxs(Box, { flexDirection: "column", gap: 1, children: [_jsx(Text, { bold: true, color: theme.colors.secondary, children: "Global" }), _jsx(Box, { paddingX: 2, children: _jsxs(Text, { children: [_jsx(Text, { color: theme.colors.text, children: "q" }), " - Quit", _jsx(Text, { children: " | " }), _jsx(Text, { color: theme.colors.text, children: "?" }), " - Help", _jsx(Text, { children: " | " }), _jsx(Text, { color: theme.colors.text, children: "/" }), " - Search", _jsx(Text, { children: " | " }), _jsx(Text, { color: theme.colors.text, children: "Shift+P" }), " - Playlists", _jsx(Text, { children: " | " }), _jsx(Text, { color: theme.colors.text, children: "p" }), " - Plugins", _jsx(Text, { children: " | " }), _jsx(Text, { color: theme.colors.text, children: "g" }), " - Suggestions", _jsx(Text, { children: " | " }), _jsx(Text, { color: theme.colors.text, children: "," }), " - Settings"] }) }), _jsx(Text, { bold: true, color: theme.colors.secondary, children: "Player" }), _jsx(Box, { paddingX: 2, children: _jsxs(Text, { children: [_jsx(Text, { color: theme.colors.text, children: "Space" }), " - Play/Pause", _jsx(Text, { children: " | " }), _jsx(Text, { color: theme.colors.text, children: "n" }), " - Next", _jsx(Text, { children: " | " }), _jsx(Text, { color: theme.colors.text, children: "b" }), " - Previous", _jsx(Text, { children: " | " }), _jsx(Text, { color: theme.colors.text, children: "=" }), " - Volume Up", _jsx(Text, { children: " | " }), _jsx(Text, { color: theme.colors.text, children: "-" }), " - Volume Down", _jsx(Text, { children: " | " }), _jsx(Text, { color: theme.colors.text, children: "Shift+S" }), " - Toggle Shuffle", _jsx(Text, { children: " | " }), _jsx(Text, { color: theme.colors.text, children: "r" }), " - Toggle Repeat"] }) }), _jsx(Text, { bold: true, color: theme.colors.secondary, children: "Navigation" }), _jsx(Box, { paddingX: 2, children: _jsxs(Text, { children: [_jsx(Text, { color: theme.colors.text, children: "Up" }), " /", _jsx(Text, { children: " " }), _jsx(Text, { color: theme.colors.text, children: "k" }), " - Move Up", _jsx(Text, { children: " | " }), _jsx(Text, { color: theme.colors.text, children: "Down" }), " /", _jsx(Text, { children: " " }), _jsx(Text, { color: theme.colors.text, children: "j" }), " - Move Down", _jsx(Text, { children: " | " }), _jsx(Text, { color: theme.colors.text, children: "Enter" }), " - Select", _jsx(Text, { children: " | " }), _jsx(Text, { color: theme.colors.text, children: "Esc" }), " - Go Back"] }) }), _jsx(Text, { bold: true, color: theme.colors.secondary, children: "Search" }), _jsx(Box, { paddingX: 2, children: _jsxs(Text, { children: [_jsx(Text, { color: theme.colors.text, children: "Tab" }), " - Switch Search Type", _jsx(Text, { children: " | " }), _jsx(Text, { color: theme.colors.text, children: "m" }), " - Create Mix Playlist", _jsx(Text, { children: " | " }), _jsx(Text, { color: theme.colors.text, children: "Shift+D" }), " - Download selection", _jsx(Text, { children: " | " }), _jsx(Text, { color: theme.colors.text, children: "Esc" }), " - Clear Search", _jsx(Text, { children: " | " }), _jsx(Text, { color: theme.colors.text, children: "[ / ]" }), " - Results Limit"] }) }), _jsx(Text, { bold: true, color: theme.colors.secondary, children: "Playlist" }), _jsx(Box, { paddingX: 2, children: _jsxs(Text, { children: [_jsx(Text, { color: theme.colors.text, children: "a" }), " - Add to Playlist", _jsx(Text, { children: " | " }), _jsx(Text, { color: theme.colors.text, children: "d" }), " - Remove from Playlist", _jsx(Text, { children: " | " }), _jsx(Text, { color: theme.colors.text, children: "c" }), " - Create Playlist", _jsx(Text, { children: " | " }), _jsx(Text, { color: theme.colors.text, children: "Shift+D" }), " - Download Playlist", _jsx(Text, { children: " | " }), _jsx(Text, { color: theme.colors.text, children: "D" }), " - Delete Playlist"] }) }), _jsx(Text, { bold: true, color: theme.colors.secondary, children: "View" }), _jsx(Box, { paddingX: 2, children: _jsxs(Text, { children: [_jsx(Text, { color: theme.colors.text, children: "M" }), " - Toggle Mini Player", _jsx(Text, { children: " | " }), _jsx(Text, { color: theme.colors.text, children: "l" }), " - Lyrics", _jsx(Text, { children: " | " }), _jsx(Text, { color: theme.colors.text, children: "T" }), " - Trending", _jsx(Text, { children: " | " }), _jsx(Text, { color: theme.colors.text, children: "e" }), " - Explore"] }) }), _jsxs(Text, { color: theme.colors.dim, children: ["Press ", _jsx(Text, { color: theme.colors.text, children: "Esc" }), " or", ' ', _jsx(Text, { color: theme.colors.text, children: "?" }), " to close"] })] })] }));
 }

package/dist/source/components/common/ShortcutsBar.js

@@ -25,5 +25,5 @@ export default function ShortcutsBar() {
     useKeyBinding(KEYBINDINGS.VOLUME_FINE_UP, volumeFineUp);
     useKeyBinding(KEYBINDINGS.VOLUME_FINE_DOWN, volumeFineDown);
     // Note: SETTINGS keybinding handled by MainLayout to avoid double-dispatch
-    return (_jsxs(Box, { borderStyle: "single", borderColor: theme.colors.dim, paddingX: 1, justifyContent: "space-between", children: [_jsxs(Text, { color: theme.colors.dim, children: ["Shortcuts: ", _jsx(Text, { color: theme.colors.text, children: "Space" }), " Play/Pause |", ' ', _jsx(Text, { color: theme.colors.text, children: "\u2192" }), " Next |", ' ', _jsx(Text, { color: theme.colors.text, children: "\u2190" }), " Prev |", ' ', _jsx(Text, { color: theme.colors.text, children: "Shift+P" }), " Playlists |", ' ', _jsx(Text, { color: theme.colors.text, children: "Shift+D" }), " Download |", ' ', _jsx(Text, { color: theme.colors.text, children: "m" }), " Mix |", ' ', _jsx(Text, { color: theme.colors.text, children: "M" }), " Mini |", ' ', _jsx(Text, { color: theme.colors.text, children: "/" }), " Search |", ' ', _jsx(Text, { color: theme.colors.text, children: "?" }), " Help |", ' ', _jsx(Text, { color: theme.colors.text, children: "q" }), " Quit"] }), _jsxs(Text, { color: theme.colors.text, children: [_jsx(Text, { color: theme.colors.dim, children: "[=/" }), "-", _jsx(Text, { color: theme.colors.dim, children: "]" }), " Vol:", ' ', _jsxs(Text, { color: theme.colors.primary, children: [playerState.volume, "%"] })] })] }));
+    return (_jsxs(Box, { borderStyle: "single", borderColor: theme.colors.dim, paddingX: 1, justifyContent: "space-between", children: [_jsxs(Text, { color: theme.colors.dim, children: ["Shortcuts: ", _jsx(Text, { color: theme.colors.text, children: "Space" }), " Play/Pause |", ' ', _jsx(Text, { color: theme.colors.text, children: "\u2192" }), " Next |", ' ', _jsx(Text, { color: theme.colors.text, children: "\u2190" }), " Prev |", ' ', _jsx(Text, { color: playerState.shuffle ? theme.colors.primary : theme.colors.text, children: "Shift+S" }), ' ', _jsxs(Text, { color: playerState.shuffle ? theme.colors.primary : theme.colors.dim, children: ["Shuffle", playerState.shuffle ? ':ON' : ''] }), ' ', "| ", _jsx(Text, { color: theme.colors.text, children: "Shift+P" }), " Playlists |", ' ', _jsx(Text, { color: theme.colors.text, children: "Shift+D" }), " Download |", ' ', _jsx(Text, { color: theme.colors.text, children: "m" }), " Mix |", ' ', _jsx(Text, { color: theme.colors.text, children: "M" }), " Mini |", ' ', _jsx(Text, { color: theme.colors.text, children: "/" }), " Search |", ' ', _jsx(Text, { color: theme.colors.text, children: "?" }), " Help |", ' ', _jsx(Text, { color: theme.colors.text, children: "q" }), " Quit"] }), _jsxs(Text, { color: theme.colors.text, children: [_jsx(Text, { color: theme.colors.dim, children: "[=/" }), "-", _jsx(Text, { color: theme.colors.dim, children: "]" }), " Vol:", ' ', _jsxs(Text, { color: theme.colors.primary, children: [playerState.volume, "%"] })] })] }));
 }

package/dist/source/components/player/NowPlaying.js

@@ -40,5 +40,5 @@ export default function NowPlaying() {
     const percentage = duration > 0 ? Math.min(100, Math.floor((progress / duration) * 100)) : 0;
     const barWidth = Math.max(10, columns - 8);
     const filledWidth = duration > 0 ? Math.floor((progress / duration) * barWidth) : 0;
-    return (_jsxs(Box, { flexDirection: "column", borderStyle: "round", borderColor: theme.colors.primary, paddingX: 1, children: [_jsxs(Box, { children: [_jsx(Text, { bold: true, color: theme.colors.primary, children: track.title }), _jsx(Text, { color: theme.colors.dim, children: " \u2022 " }), _jsx(Text, { color: theme.colors.secondary, children: artists })] }), track.album && _jsx(Text, { color: theme.colors.dim, children: track.album.name }), _jsxs(Box, { children: [_jsx(Text, { color: theme.colors.primary, children: '█'.repeat(Math.min(filledWidth, barWidth)) }), _jsx(Text, { color: theme.colors.dim, children: '░'.repeat(Math.max(0, barWidth - filledWidth)) })] }), _jsxs(Box, { children: [_jsx(Text, { color: theme.colors.text, children: formatTime(progress) }), _jsxs(Text, { color: theme.colors.dim, children: [" / ", formatTime(duration), " "] }), _jsxs(Text, { color: theme.colors.dim, children: ["[", percentage, "%]"] }), playerState.isLoading && (_jsx(Text, { color: theme.colors.accent, children: " Loading..." })), !playerState.isPlaying && progress > 0 && (_jsx(Text, { color: theme.colors.dim, children: " \u23F8" })), sleepRemaining !== null && (_jsxs(Text, { color: theme.colors.warning, children: [' ', "\u23FE ", formatTime(sleepRemaining)] }))] }), playerState.error && (_jsx(Text, { color: theme.colors.error, children: playerState.error }))] }));
+    return (_jsxs(Box, { flexDirection: "column", borderStyle: "round", borderColor: theme.colors.primary, paddingX: 1, children: [_jsxs(Box, { children: [_jsx(Text, { bold: true, color: theme.colors.primary, children: track.title }), _jsx(Text, { color: theme.colors.dim, children: " \u2022 " }), _jsx(Text, { color: theme.colors.secondary, children: artists })] }), track.album && _jsx(Text, { color: theme.colors.dim, children: track.album.name }), _jsxs(Box, { children: [_jsx(Text, { color: theme.colors.primary, children: '█'.repeat(Math.min(filledWidth, barWidth)) }), _jsx(Text, { color: theme.colors.dim, children: '░'.repeat(Math.max(0, barWidth - filledWidth)) })] }), _jsxs(Box, { children: [_jsx(Text, { color: theme.colors.text, children: formatTime(progress) }), _jsxs(Text, { color: theme.colors.dim, children: [" / ", formatTime(duration), " "] }), _jsxs(Text, { color: theme.colors.dim, children: ["[", percentage, "%]"] }), playerState.isLoading && (_jsx(Text, { color: theme.colors.accent, children: " Loading..." })), !playerState.isPlaying && progress > 0 && (_jsx(Text, { color: theme.colors.dim, children: " \u23F8" })), playerState.shuffle && _jsx(Text, { color: theme.colors.primary, children: " \uD83D\uDD00" }), sleepRemaining !== null && (_jsxs(Text, { color: theme.colors.warning, children: [' ', "\u23FE ", formatTime(sleepRemaining)] }))] }), playerState.error && (_jsx(Text, { color: theme.colors.error, children: playerState.error }))] }));
 }

package/dist/source/components/player/PlayerControls.js

@@ -17,7 +17,7 @@ export default function PlayerControls() {
         };
     }, [instanceId]);
     const { theme } = useTheme();
-    const { state: playerState, pause, resume, next, previous, volumeUp, volumeDown, speedUp, speedDown, } = usePlayer();
+    const { state: playerState, pause, resume, next, previous, volumeUp, volumeDown, speedUp, speedDown, toggleShuffle, } = usePlayer();
     // DEBUG: Log when callbacks change (detect instability)
     useEffect(() => {
         // Temporarily output to stderr to debug without triggering Ink re-render
@@ -39,5 +39,6 @@ export default function PlayerControls() {
     useKeyBinding(KEYBINDINGS.VOLUME_DOWN, volumeDown);
     useKeyBinding(KEYBINDINGS.SPEED_UP, speedUp);
     useKeyBinding(KEYBINDINGS.SPEED_DOWN, speedDown);
-    return (_jsxs(Box, { flexDirection: "row", justifyContent: "space-between", paddingX: 2, borderStyle: "classic", borderColor: theme.colors.dim, children: [_jsxs(Text, { color: theme.colors.text, children: ["[", _jsx(Text, { color: theme.colors.dim, children: "\u2190 / b" }), "] Prev"] }), _jsx(Text, { color: theme.colors.primary, children: playerState.isPlaying ? (_jsxs(Text, { children: ["[", _jsx(Text, { color: theme.colors.dim, children: "Space" }), "] Pause"] })) : (_jsxs(Text, { children: ["[", _jsx(Text, { color: theme.colors.dim, children: "Space" }), "] Play"] })) }), _jsxs(Text, { color: theme.colors.text, children: ["[", _jsx(Text, { color: theme.colors.dim, children: "\u2192 / n" }), "] Next"] }), _jsxs(Text, { color: theme.colors.text, children: ["[", _jsx(Text, { color: theme.colors.dim, children: "+/-" }), "] Vol: ", playerState.volume, "%"] }), (playerState.speed ?? 1.0) !== 1.0 && (_jsxs(Text, { color: theme.colors.accent, children: ["[", _jsx(Text, { color: theme.colors.dim, children: "<>" }), "]", ' ', (playerState.speed ?? 1.0).toFixed(2), "x"] }))] }));
+    useKeyBinding(KEYBINDINGS.SHUFFLE, toggleShuffle);
+    return (_jsxs(Box, { flexDirection: "row", justifyContent: "space-between", paddingX: 2, borderStyle: "classic", borderColor: theme.colors.dim, children: [_jsxs(Text, { color: theme.colors.text, children: ["[", _jsx(Text, { color: theme.colors.dim, children: "\u2190 / b" }), "] Prev"] }), _jsx(Text, { color: theme.colors.primary, children: playerState.isPlaying ? (_jsxs(Text, { children: ["[", _jsx(Text, { color: theme.colors.dim, children: "Space" }), "] Pause"] })) : (_jsxs(Text, { children: ["[", _jsx(Text, { color: theme.colors.dim, children: "Space" }), "] Play"] })) }), _jsxs(Text, { color: theme.colors.text, children: ["[", _jsx(Text, { color: theme.colors.dim, children: "\u2192 / n" }), "] Next"] }), _jsxs(Text, { color: theme.colors.text, children: ["[", _jsx(Text, { color: theme.colors.dim, children: "+/-" }), "] Vol: ", playerState.volume, "%"] }), _jsxs(Text, { color: playerState.shuffle ? theme.colors.primary : theme.colors.dim, children: ["[", _jsx(Text, { color: theme.colors.dim, children: "Shift+S" }), "]", ' ', playerState.shuffle ? '🔀 ON' : '🔀 OFF'] }), (playerState.speed ?? 1.0) !== 1.0 && (_jsxs(Text, { color: theme.colors.accent, children: ["[", _jsx(Text, { color: theme.colors.dim, children: "<>" }), "]", ' ', (playerState.speed ?? 1.0).toFixed(2), "x"] }))] }));
 }

package/dist/source/hooks/useKeyboard.js

@@ -75,11 +75,14 @@ export function KeyboardManager() {
                         const hasMeta = parts.includes('meta') || parts.includes('alt');
                         const hasShift = parts.includes('shift');
                         const mainKey = parts[parts.length - 1];
+                        const uppercaseShiftInput = input.length === 1 &&
+                            input === input.toUpperCase() &&
+                            input.toLowerCase() === mainKey;
                         if (hasCtrl && !key.ctrl)
                             return false;
                         if (hasMeta && !key.meta)
                             return false;
-                        if (hasShift && !key.shift)
+                        if (hasShift && !key.shift && !uppercaseShiftInput)
                             return false;
                         if (!hasShift && key.shift)
                             return false;

package/dist/source/services/player/player.service.d.ts

@@ -33,6 +33,7 @@ declare class PlayerService {
      * Generate IPC socket path based on platform, unique per play session
      */
     private getIpcPath;
+    private getMpvCommand;
     /**
      * Connect to mpv IPC socket
      */

package/dist/source/services/player/player.service.js

@@ -44,6 +44,13 @@ class PlayerService {
             return `/tmp/mpvsocket-${process.pid}-${this.playSessionId}`;
         }
     }
+    getMpvCommand() {
+        const configuredPath = process.env['MPV_PATH']?.trim();
+        if (configuredPath) {
+            return configuredPath;
+        }
+        return process.platform === 'win32' ? 'mpv.exe' : 'mpv';
+    }
     /**
      * Connect to mpv IPC socket
      */
@@ -228,7 +235,7 @@ class PlayerService {
                 mpvArgs.push(playUrl);
                 // Capture process in local var so stale exit handlers from a killed
                 // process don't overwrite state belonging to a newly-spawned process.
-                const spawnedProcess = spawn('mpv', mpvArgs);
+                const spawnedProcess = spawn(this.getMpvCommand(), mpvArgs);
                 this.mpvProcess = spawnedProcess;
                 if (!spawnedProcess.stdout || !spawnedProcess.stderr) {
                     throw new Error('Failed to create mpv process streams');
@@ -288,6 +295,10 @@ class PlayerService {
                         this.isPlaying = false;
                         this.mpvProcess = null;
                     }
+                    if ('code' in error && error.code === 'ENOENT') {
+                        reject(new Error("mpv executable not found. Install mpv and ensure it's in PATH (or set MPV_PATH)."));
+                        return;
+                    }
                     reject(error);
                 });
                 logger.info('PlayerService', 'mpv process started successfully');

package/dist/source/stores/player.store.d.ts

@@ -1,5 +1,6 @@
 import { type ReactNode } from 'react';
 import type { PlayerState, PlayerAction } from '../types/player.types.ts';
+export declare function playerReducer(state: PlayerState, action: PlayerAction): PlayerState;
 import type { Track } from '../types/youtube-music.types.ts';
 type PlayerContextValue = {
     state: PlayerState;

package/dist/source/stores/player.store.js

@@ -24,7 +24,7 @@ const initialState = {
 };
 // Get player service instance
 const playerService = getPlayerService();
-function playerReducer(state, action) {
+export function playerReducer(state, action) {
     switch (action.category) {
         case 'PLAY':
             return {
@@ -45,7 +45,23 @@ function playerReducer(state, action) {
                 progress: 0,
                 currentTrack: null,
             };
-        case 'NEXT':
+        case 'NEXT': {
+            if (state.queue.length === 0)
+                return state;
+            // Shuffle mode: pick a random track excluding the current position
+            if (state.shuffle && state.queue.length > 1) {
+                let randomIndex;
+                do {
+                    randomIndex = Math.floor(Math.random() * state.queue.length);
+                } while (randomIndex === state.queuePosition);
+                return {
+                    ...state,
+                    queuePosition: randomIndex,
+                    currentTrack: state.queue[randomIndex] ?? null,
+                    progress: 0,
+                };
+            }
+            // Sequential mode
             const nextPosition = state.queuePosition + 1;
             if (nextPosition >= state.queue.length) {
                 if (state.repeat === 'all') {
@@ -64,6 +80,7 @@ function playerReducer(state, action) {
                 currentTrack: state.queue[nextPosition] ?? null,
                 progress: 0,
             };
+        }
         case 'PREVIOUS':
             const prevPosition = state.queuePosition - 1;
             if (prevPosition < 0) {

package/dist/source/utils/constants.d.ts

@@ -27,7 +27,7 @@ export declare const SEARCH_TYPE: {
     readonly PLAYLISTS: "playlists";
 };
 export declare const KEYBINDINGS: {
-    readonly QUIT: readonly ["q", "escape"];
+    readonly QUIT: readonly ["q"];
     readonly HELP: readonly ["?"];
     readonly SEARCH: readonly ["/"];
     readonly PLAYLISTS: readonly ["shift+p"];
@@ -41,7 +41,7 @@ export declare const KEYBINDINGS: {
     readonly VOLUME_DOWN: readonly ["-"];
     readonly VOLUME_FINE_UP: readonly ["shift+="];
     readonly VOLUME_FINE_DOWN: readonly ["shift+-"];
-    readonly SHUFFLE: readonly ["s"];
+    readonly SHUFFLE: readonly ["shift+s"];
     readonly REPEAT: readonly ["r"];
     readonly SEEK_FORWARD: readonly ["shift+right"];
     readonly SEEK_BACKWARD: readonly ["shift+left"];

package/dist/source/utils/constants.js

@@ -35,7 +35,7 @@ export const SEARCH_TYPE = {
 // Keybindings
 export const KEYBINDINGS = {
     // Global
-    QUIT: ['q', 'escape'],
+    QUIT: ['q'],
     HELP: ['?'],
     SEARCH: ['/'],
     PLAYLISTS: ['shift+p'],
@@ -50,7 +50,7 @@ export const KEYBINDINGS = {
     VOLUME_DOWN: ['-'], // Only '-' without shift
     VOLUME_FINE_UP: ['shift+='], // Fine-grained +1 step
     VOLUME_FINE_DOWN: ['shift+-'], // Fine-grained -1 step
-    SHUFFLE: ['s'],
+    SHUFFLE: ['shift+s'],
     REPEAT: ['r'],
     SEEK_FORWARD: ['shift+right'],
     SEEK_BACKWARD: ['shift+left'],

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@involvex/youtube-music-cli",
-	"version": "0.0.14",
+	"version": "0.0.16",
 	"description": "- A Commandline music player for youtube-music",
 	"repository": {
 		"type": "git",
@@ -78,6 +78,7 @@
 	"devDependencies": {
 		"@eslint/js": "^10.0.1",
 		"@sindresorhus/tsconfig": "^8.1.0",
+		"@types/node": "^25.2.3",
 		"@types/node-notifier": "^8.0.5",
 		"@types/react": "^19.2.14",
 		"@vdemedes/prettier-config": "^2.0.1",

package/readme.md

@@ -163,15 +163,15 @@ youtube-music-cli play dQw4w9WgXcQ --shuffle
 
 ### Global
 
-| Key         | Action          |
-| ----------- | --------------- |
-| `?`         | Show help       |
-| `/`         | Search          |
-| `p`         | Plugins manager |
-| `g`         | Suggestions     |
-| `,`         | Settings        |
-| `q` / `Esc` | Quit / Go back  |
-| `Ctrl+L`    | Refresh screen  |
+| Key   | Action          |
+| ----- | --------------- |
+| `?`   | Show help       |
+| `/`   | Search          |
+| `p`   | Plugins manager |
+| `g`   | Suggestions     |
+| `,`   | Settings        |
+| `Esc` | Go back         |
+| `q`   | Quit            |
 
 ### Playback
 
@@ -309,7 +309,7 @@ mpv --version
 
 ### TUI rendering issues
 
-Press `Ctrl+L` to refresh the screen, or try a different terminal emulator.
+If rendering looks wrong, try resizing your terminal window or restarting the app.
 
 ### Plugin not loading
 
@@ -377,4 +377,4 @@ Made with ❤️ for music lovers
 
 **[🪙 Paypal](https://paypal.me/involvex)**
 
-**⌨️ [Github Sponsors](https://github.com/sponsors/involvex)**
+**[⌨️ Github Sponsors](https://github.com/sponsors/involvex)**