@involvex/youtube-music-cli 0.0.26 → 0.0.28

package/CHANGELOG.md

@@ -1,3 +1,11 @@
+## [0.0.28](https://github.com/involvex/youtube-music-cli/compare/v0.0.27...v0.0.28) (2026-02-22)
+
+### Bug Fixes
+
+- standardize quote style in snyk_rules.instructions.md ([5906fed](https://github.com/involvex/youtube-music-cli/commit/5906fed587be5f9cd6629281428ef304d8b32749))
+
+## [0.0.27](https://github.com/involvex/youtube-music-cli/compare/v0.0.26...v0.0.27) (2026-02-20)
+
 ## [0.0.26](https://github.com/involvex/youtube-music-cli/compare/v0.0.25...v0.0.26) (2026-02-20)
 
 ## [0.0.25](https://github.com/involvex/youtube-music-cli/compare/v0.0.24...v0.0.25) (2026-02-20)

package/dist/source/cli.js

@@ -11,7 +11,10 @@ import { getWebServerManager } from "./services/web/web-server-manager.js";
 import { getWebStreamingService } from "./services/web/web-streaming.service.js";
 import { getVersionCheckService } from "./services/version-check/version-check.service.js";
 import { getConfigService } from "./services/config/config.service.js";
+import { getPlayerService } from "./services/player/player.service.js";
 import { APP_VERSION } from "./utils/constants.js";
+import { ensurePlaybackDependencies } from "./services/player/dependency-check.service.js";
+import { getMusicService } from "./services/youtube-music/api.js";
 const cli = meow(`
 	Usage
 	  $ youtube-music-cli
@@ -117,6 +120,64 @@ if (cli.flags.help) {
 // Handle plugin commands
 const command = cli.input[0];
 const args = cli.input.slice(1);
+const isInteractiveTerminal = Boolean(process.stdin.isTTY && process.stdout.isTTY);
+function requiresImmediatePlayback(flags) {
+    return Boolean(flags.playTrack || flags.searchQuery || flags.playPlaylist);
+}
+function shouldCheckPlaybackDependencies(commandName, flags) {
+    if (flags.webOnly) {
+        return false;
+    }
+    if (requiresImmediatePlayback(flags)) {
+        return true;
+    }
+    return (commandName === undefined ||
+        commandName === 'suggestions' ||
+        Boolean(flags.web));
+}
+async function runDirectPlaybackCommand(flags) {
+    const musicService = getMusicService();
+    const playerService = getPlayerService();
+    const config = getConfigService();
+    const playbackOptions = {
+        volume: flags.volume ?? config.get('volume'),
+        audioNormalization: config.get('audioNormalization'),
+    };
+    let track;
+    if (flags.playTrack) {
+        track = await musicService.getTrack(flags.playTrack);
+        if (!track) {
+            throw new Error(`Track not found: ${flags.playTrack}`);
+        }
+    }
+    else if (flags.searchQuery) {
+        const response = await musicService.search(flags.searchQuery, {
+            type: 'songs',
+            limit: 1,
+        });
+        const firstSong = response.results.find(result => result.type === 'song');
+        if (!firstSong) {
+            throw new Error(`No playable tracks found for: "${flags.searchQuery}"`);
+        }
+        track = firstSong.data;
+    }
+    else if (flags.playPlaylist) {
+        const playlist = await musicService.getPlaylist(flags.playPlaylist);
+        track = playlist.tracks[0];
+        if (!track) {
+            throw new Error(`No playable tracks found in playlist: ${flags.playPlaylist}`);
+        }
+    }
+    if (!track) {
+        throw new Error('No track resolved for playback command.');
+    }
+    const artists = track.artists.length > 0
+        ? track.artists.map(artist => artist.name).join(', ')
+        : 'Unknown Artist';
+    console.log(`Playing: ${track.title} — ${artists}`);
+    const youtubeUrl = `https://www.youtube.com/watch?v=${track.videoId}`;
+    await playerService.play(youtubeUrl, playbackOptions);
+}
 if (command === 'plugins') {
     const subCommand = args[0];
     const pluginArg = args[1];
@@ -274,6 +335,28 @@ else {
     else if (command === 'back') {
         cli.flags.action = 'previous';
     }
+    const flags = cli.flags;
+    const shouldRunDirectPlayback = requiresImmediatePlayback(flags) &&
+        (flags.headless || !isInteractiveTerminal);
+    if (shouldRunDirectPlayback) {
+        void (async () => {
+            const dependencyCheck = await ensurePlaybackDependencies({
+                interactive: isInteractiveTerminal,
+            });
+            if (!dependencyCheck.ready) {
+                process.exit(1);
+                return;
+            }
+            try {
+                await runDirectPlaybackCommand(flags);
+                process.exit(0);
+            }
+            catch (error) {
+                console.error(`✗ Playback failed: ${error instanceof Error ? error.message : String(error)}`);
+                process.exit(1);
+            }
+        })();
+    }
     else if (command === 'import') {
         // Handle import commands
         void (async () => {
@@ -317,6 +400,15 @@ else {
         void (async () => {
             const webManager = getWebServerManager();
             try {
+                if (shouldCheckPlaybackDependencies(command, flags)) {
+                    const dependencyCheck = await ensurePlaybackDependencies({
+                        interactive: isInteractiveTerminal,
+                    });
+                    if (!dependencyCheck.ready && requiresImmediatePlayback(flags)) {
+                        process.exit(1);
+                        return;
+                    }
+                }
                 await webManager.start({
                     enabled: true,
                     host: cli.flags.webHost ?? 'localhost',
@@ -343,7 +435,7 @@ else {
                 }
                 else {
                     // Also render the CLI UI
-                    render(_jsx(App, { flags: cli.flags }));
+                    render(_jsx(App, { flags: flags }));
                 }
             }
             catch (error) {
@@ -353,9 +445,18 @@ else {
         })();
     }
     else {
-        // Check for updates before rendering the app (skip in web-only mode)
-        if (!cli.flags.webOnly) {
-            void (async () => {
+        void (async () => {
+            if (shouldCheckPlaybackDependencies(command, flags)) {
+                const dependencyCheck = await ensurePlaybackDependencies({
+                    interactive: isInteractiveTerminal,
+                });
+                if (!dependencyCheck.ready && requiresImmediatePlayback(flags)) {
+                    process.exit(1);
+                    return;
+                }
+            }
+            // Check for updates before rendering the app (skip in web-only mode)
+            if (!cli.flags.webOnly) {
                 const versionCheck = getVersionCheckService();
                 const config = getConfigService();
                 const lastCheck = config.getLastVersionCheck();
@@ -369,9 +470,9 @@ else {
                         console.log('');
                     }
                 }
-            })();
-        }
-        // Render the app
-        render(_jsx(App, { flags: cli.flags }));
+            }
+            // Render the app
+            render(_jsx(App, { flags: flags }));
+        })();
     }
 }

package/dist/source/components/layouts/SearchLayout.js

@@ -1,4 +1,4 @@
-import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 // Search view layout
 import { useNavigation } from "../../hooks/useNavigation.js";
 import { useYouTubeMusic } from "../../hooks/useYouTubeMusic.js";
@@ -10,15 +10,18 @@ import SearchBar from "../search/SearchBar.js";
 import { useKeyBinding } from "../../hooks/useKeyboard.js";
 import { KEYBINDINGS, VIEW } from "../../utils/constants.js";
 import { Box, Text } from 'ink';
+import { usePlayer } from "../../hooks/usePlayer.js";
 function SearchLayout() {
     const { theme } = useTheme();
     const { state: navState, dispatch } = useNavigation();
+    const { state: playerState } = usePlayer();
     const { isLoading, error, search } = useYouTubeMusic();
     const [results, setResults] = useState([]);
     const [isTyping, setIsTyping] = useState(true);
     const [isSearching, setIsSearching] = useState(false);
     const [actionMessage, setActionMessage] = useState(null);
     const actionTimeoutRef = useRef(null);
+    const lastAutoSearchedQueryRef = useRef(null);
     // Handle search action
     const performSearch = useCallback(async (query) => {
         if (!query || isSearching)
@@ -56,12 +59,18 @@ function SearchLayout() {
     useKeyBinding(['h'], goToHistory);
     // Initial search if query is in state (usually from CLI flags)
     useEffect(() => {
-        if (navState.searchQuery && !navState.hasSearched) {
-            void performSearch(navState.searchQuery);
+        const query = navState.searchQuery.trim();
+        if (!query || navState.hasSearched) {
+            return;
         }
-        // We only want this to run once on mount or when searchQuery changes initially
-        // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, []);
+        if (lastAutoSearchedQueryRef.current === query) {
+            return;
+        }
+        lastAutoSearchedQueryRef.current = query;
+        queueMicrotask(() => {
+            void performSearch(query);
+        });
+    }, [navState.searchQuery, navState.hasSearched, performSearch]);
     // Handle going back
     const goBack = useCallback(() => {
         if (!isTyping) {
@@ -106,9 +115,11 @@ function SearchLayout() {
             setResults([]);
             dispatch({ category: 'SET_HAS_SEARCHED', hasSearched: false });
             dispatch({ category: 'SET_SEARCH_QUERY', query: '' });
+            lastAutoSearchedQueryRef.current = null;
         };
     }, [dispatch]);
-    return (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Text, { color: theme.colors.dim, children: ["Limit: ", navState.searchLimit, " (Use [ or ] to adjust)"] }), _jsx(SearchBar, { isActive: isTyping && !isSearching, onInput: input => {
+    return (_jsxs(Box, { flexDirection: "column", children: [playerState.currentTrack && (_jsxs(Box, { children: [_jsx(Text, { color: theme.colors.dim, children: playerState.isPlaying ? '▶ ' : '⏸ ' }), _jsx(Text, { color: theme.colors.primary, bold: true, children: playerState.currentTrack.title }), playerState.currentTrack.artists &&
+                        playerState.currentTrack.artists.length > 0 && (_jsxs(Text, { color: theme.colors.secondary, children: [' • ', playerState.currentTrack.artists.map(a => a.name).join(', ')] }))] })), _jsxs(Text, { color: theme.colors.dim, children: ["Limit: ", navState.searchLimit, " (Use [ or ] to adjust)"] }), _jsx(SearchBar, { isActive: isTyping && !isSearching, onInput: input => {
                     void performSearch(input);
                 } }), (isLoading || isSearching) && (_jsx(Text, { color: theme.colors.accent, children: "Searching..." })), error && _jsx(Text, { color: theme.colors.error, children: error }), !isLoading && navState.hasSearched && (_jsx(SearchResults, { results: results, selectedIndex: navState.selectedResult, isActive: !isTyping, onMixCreated: handleMixCreated, onDownloadStatus: handleDownloadStatus })), !isLoading && navState.hasSearched && results.length === 0 && !error && (_jsx(Text, { color: theme.colors.dim, children: "No results found" })), actionMessage && (_jsx(Text, { color: theme.colors.accent, children: actionMessage })), _jsx(Text, { color: theme.colors.dim, children: isTyping
                     ? 'Type to search, Enter to start, Esc to clear'

package/dist/source/hooks/useKeyboard.d.ts

@@ -1,6 +1,7 @@
 /**
  * Hook to bind keyboard shortcuts.
  * This uses a centralized manager to avoid multiple useInput calls and memory leaks.
+ * Uses a ref-based approach to always call the latest handler without stale closures.
  */
 export declare function useKeyBinding(keys: readonly string[], handler: () => void): void;
 /**

package/dist/source/hooks/useKeyboard.js

@@ -1,5 +1,5 @@
 // Keyboard input handling hook
-import { useCallback, useEffect } from 'react';
+import { useEffect, useRef } from 'react';
 import { useInput } from 'ink';
 import { logger } from "../services/logger/logger.service.js";
 import { useKeyboardBlockContext } from "./useKeyboardBlocker.js";
@@ -8,16 +8,18 @@ const registry = new Set();
 /**
  * Hook to bind keyboard shortcuts.
  * This uses a centralized manager to avoid multiple useInput calls and memory leaks.
+ * Uses a ref-based approach to always call the latest handler without stale closures.
  */
 export function useKeyBinding(keys, handler) {
-    const memoizedHandler = useCallback(handler, [handler]);
+    const handlerRef = useRef(handler);
+    handlerRef.current = handler;
     useEffect(() => {
-        const entry = { keys, handler: memoizedHandler };
+        const entry = { keys, handler: () => handlerRef.current() };
         registry.add(entry);
         return () => {
             registry.delete(entry);
         };
-    }, [keys, memoizedHandler]);
+    }, [keys]); // keys is the only dep; handlerRef is a stable ref
 }
 /**
  * Global Keyboard Manager Component
@@ -84,7 +86,15 @@ export function KeyboardManager() {
                             return false;
                         if (hasShift && !key.shift && !uppercaseShiftInput)
                             return false;
-                        if (!hasShift && key.shift)
+                        // Block lowercase-only bindings when shift is active or the input is
+                        // an uppercase letter (which implies Shift was held).
+                        // Example: the 'p' (Plugins) binding must not fire when the user
+                        // presses Shift+P, which should only trigger 'shift+p' (Playlists).
+                        // Note: `input !== input.toLowerCase()` is true only for uppercase
+                        // alphabetical characters, avoiding false positives on symbols/digits.
+                        if (!hasShift &&
+                            (key.shift ||
+                                (input.length === 1 && input !== input.toLowerCase())))
                             return false;
                         // Check the actual key
                         if (mainKey === 'up' && key.upArrow)

package/dist/source/hooks/usePlayer.js

@@ -5,22 +5,30 @@ import { getConfigService } from "../services/config/config.service.js";
 export function usePlayer() {
     const { state, dispatch, ...playerStore } = usePlayerStore();
     const play = useCallback((track, options) => {
-        // Clear queue if requested (e.g., playing from search results)
         if (options?.clearQueue) {
+            // When clearing the queue, always dispatch fresh play commands rather
+            // than relying on the stale queue state captured in this closure.
+            // This fixes a bug where a track already in the queue wouldn't replay
+            // after clearQueue because SET_QUEUE_POSITION would be dispatched
+            // against the (now-empty) queue.
             dispatch({ category: 'CLEAR_QUEUE' });
-        }
-        // Add to queue if not already there
-        const isInQueue = state.queue.some(t => t.videoId === track.videoId);
-        if (!isInQueue) {
             dispatch({ category: 'ADD_TO_QUEUE', track });
-        }
-        // Find position and play
-        const position = state.queue.findIndex(t => t.videoId === track.videoId);
-        if (position >= 0) {
-            dispatch({ category: 'SET_QUEUE_POSITION', position });
+            dispatch({ category: 'PLAY', track });
         }
         else {
-            dispatch({ category: 'PLAY', track });
+            // Add to queue if not already there
+            const isInQueue = state.queue.some(t => t.videoId === track.videoId);
+            if (!isInQueue) {
+                dispatch({ category: 'ADD_TO_QUEUE', track });
+            }
+            // Find position and play
+            const position = state.queue.findIndex(t => t.videoId === track.videoId);
+            if (position >= 0) {
+                dispatch({ category: 'SET_QUEUE_POSITION', position });
+            }
+            else {
+                dispatch({ category: 'PLAY', track });
+            }
         }
         // Add to history
         const config = getConfigService();

package/dist/source/main.js

@@ -57,23 +57,68 @@ function Initializer({ flags }) {
 }
 function HeadlessLayout({ flags }) {
     const { play, pause, resume, next, previous } = usePlayer();
-    const { getTrack } = useYouTubeMusic();
+    const { getTrack, getPlaylist, search } = useYouTubeMusic();
     useEffect(() => {
-        if (flags?.playTrack) {
-            void getTrack(flags.playTrack).then(track => {
-                if (track)
-                    play(track);
-            });
-        }
-        if (flags?.action === 'pause')
-            pause();
-        if (flags?.action === 'resume')
-            resume();
-        if (flags?.action === 'next')
-            next();
-        if (flags?.action === 'previous')
-            previous();
-    }, [flags, play, pause, resume, next, previous, getTrack]);
+        void (async () => {
+            if (flags?.playTrack) {
+                const track = await getTrack(flags.playTrack);
+                if (!track) {
+                    console.error(`Track not found: ${flags.playTrack}`);
+                    process.exitCode = 1;
+                    return;
+                }
+                play(track);
+                console.log(`Playing: ${track.title}`);
+                return;
+            }
+            if (flags?.searchQuery) {
+                const response = await search(flags.searchQuery, {
+                    type: 'songs',
+                    limit: 1,
+                });
+                const songResult = response?.results.find(result => result.type === 'song');
+                if (!songResult) {
+                    console.error(`No playable tracks found for: "${flags.searchQuery}"`);
+                    process.exitCode = 1;
+                    return;
+                }
+                const track = songResult.data;
+                play(track, { clearQueue: true });
+                console.log(`Playing: ${track.title}`);
+                return;
+            }
+            if (flags?.playPlaylist) {
+                const playlist = await getPlaylist(flags.playPlaylist);
+                const firstTrack = playlist?.tracks[0];
+                if (!firstTrack) {
+                    console.error(`No playable tracks found in playlist: ${flags.playPlaylist}`);
+                    process.exitCode = 1;
+                    return;
+                }
+                play(firstTrack, { clearQueue: true });
+                console.log(`Playing playlist "${playlist.name}": ${firstTrack.title}`);
+                return;
+            }
+            if (flags?.action === 'pause')
+                pause();
+            if (flags?.action === 'resume')
+                resume();
+            if (flags?.action === 'next')
+                next();
+            if (flags?.action === 'previous')
+                previous();
+        })();
+    }, [
+        flags,
+        play,
+        pause,
+        resume,
+        next,
+        previous,
+        getTrack,
+        getPlaylist,
+        search,
+    ]);
     return (_jsx(Box, { padding: 1, children: _jsx(Text, { color: "green", children: "Headless mode active." }) }));
 }
 export default function Main({ flags }) {

package/dist/source/services/player/dependency-check.service.d.ts

@@ -0,0 +1,12 @@
+export type PlaybackDependency = 'mpv' | 'yt-dlp';
+export type InstallPlan = {
+    command: string;
+    args: string[];
+};
+export declare function buildInstallPlan(platform: NodeJS.Platform, availableManagers: readonly string[], missingDependencies: readonly PlaybackDependency[]): InstallPlan | null;
+export declare function ensurePlaybackDependencies(options: {
+    interactive: boolean;
+}): Promise<{
+    ready: boolean;
+    missing: PlaybackDependency[];
+}>;

package/dist/source/services/player/dependency-check.service.js

@@ -0,0 +1,140 @@
+import { spawn } from 'node:child_process';
+import { createInterface } from 'node:readline/promises';
+const REQUIRED_DEPENDENCIES = ['mpv', 'yt-dlp'];
+function getDependencyExecutable(dependency) {
+    if (process.platform === 'win32') {
+        return dependency === 'mpv' ? 'mpv.exe' : 'yt-dlp.exe';
+    }
+    return dependency;
+}
+function renderInstallCommand(plan) {
+    return [plan.command, ...plan.args].join(' ');
+}
+function runCommand(command, args, options) {
+    return new Promise(resolve => {
+        const child = spawn(command, args, {
+            stdio: options.stdio,
+        });
+        child.once('error', () => {
+            resolve(false);
+        });
+        child.once('close', code => {
+            resolve(code === 0);
+        });
+    });
+}
+async function commandExists(command) {
+    return runCommand(command, ['--version'], { stdio: 'ignore' });
+}
+async function getMissingDependencies() {
+    const missing = [];
+    for (const dependency of REQUIRED_DEPENDENCIES) {
+        const executable = getDependencyExecutable(dependency);
+        const exists = await commandExists(executable);
+        if (!exists) {
+            missing.push(dependency);
+        }
+    }
+    return missing;
+}
+export function buildInstallPlan(platform, availableManagers, missingDependencies) {
+    if (missingDependencies.length === 0) {
+        return null;
+    }
+    const deps = [...missingDependencies];
+    const hasManager = (manager) => availableManagers.includes(manager);
+    if ((platform === 'darwin' || platform === 'linux') && hasManager('brew')) {
+        return { command: 'brew', args: ['install', ...deps] };
+    }
+    if (platform === 'win32') {
+        if (hasManager('scoop')) {
+            return { command: 'scoop', args: ['install', ...deps] };
+        }
+        if (hasManager('choco')) {
+            return { command: 'choco', args: ['install', ...deps, '-y'] };
+        }
+        return null;
+    }
+    if (platform === 'linux') {
+        if (hasManager('apt-get')) {
+            return {
+                command: 'sudo',
+                args: ['apt-get', 'install', '-y', ...deps],
+            };
+        }
+        if (hasManager('pacman')) {
+            return {
+                command: 'sudo',
+                args: ['pacman', '-S', '--needed', ...deps],
+            };
+        }
+        if (hasManager('dnf')) {
+            return {
+                command: 'sudo',
+                args: ['dnf', 'install', '-y', ...deps],
+            };
+        }
+    }
+    return null;
+}
+async function getAvailablePackageManagers(platform) {
+    const candidates = platform === 'win32'
+        ? ['scoop', 'choco']
+        : platform === 'darwin'
+            ? ['brew']
+            : ['brew', 'apt-get', 'pacman', 'dnf'];
+    const available = [];
+    for (const manager of candidates) {
+        if (await commandExists(manager)) {
+            available.push(manager);
+        }
+    }
+    return available;
+}
+function printManualInstallHelp(missing, plan) {
+    console.error(`\nMissing playback dependencies: ${missing.join(', ')}. Install them and re-run the command.`);
+    if (plan) {
+        console.error(`Suggested install command: ${renderInstallCommand(plan)}\n`);
+        return;
+    }
+    console.error('Suggested install commands:\n  macOS: brew install mpv yt-dlp\n  Windows: scoop install mpv yt-dlp\n  Linux (apt): sudo apt-get install -y mpv yt-dlp\n');
+}
+export async function ensurePlaybackDependencies(options) {
+    const missing = await getMissingDependencies();
+    if (missing.length === 0) {
+        return { ready: true, missing: [] };
+    }
+    const availableManagers = await getAvailablePackageManagers(process.platform);
+    const installPlan = buildInstallPlan(process.platform, availableManagers, missing);
+    if (!options.interactive || !installPlan) {
+        printManualInstallHelp(missing, installPlan);
+        return { ready: false, missing };
+    }
+    const prompt = `Missing ${missing.join(', ')}. Install now with "${renderInstallCommand(installPlan)}"? [Y/n] `;
+    const readline = createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    const response = (await readline.question(prompt)).trim().toLowerCase();
+    readline.close();
+    if (response === 'n' || response === 'no') {
+        printManualInstallHelp(missing, installPlan);
+        return { ready: false, missing };
+    }
+    console.log(`\nInstalling dependencies: ${missing.join(', ')}`);
+    const installSuccess = await runCommand(installPlan.command, installPlan.args, {
+        stdio: 'inherit',
+    });
+    if (!installSuccess) {
+        console.error('\nAutomatic installation failed.');
+        printManualInstallHelp(missing, installPlan);
+        return { ready: false, missing };
+    }
+    const missingAfterInstall = await getMissingDependencies();
+    if (missingAfterInstall.length > 0) {
+        printManualInstallHelp(missingAfterInstall, installPlan);
+        return { ready: false, missing: missingAfterInstall };
+    }
+    console.log('Playback dependencies installed successfully.\n');
+    return { ready: true, missing: [] };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@involvex/youtube-music-cli",
-	"version": "0.0.26",
+	"version": "0.0.28",
 	"description": "- A Commandline music player for youtube-music",
 	"repository": {
 		"type": "git",

package/readme.md

@@ -322,6 +322,8 @@ Ensure mpv is installed and in your PATH:
 mpv --version
 ```
 
+On startup, the CLI now checks for `mpv` and `yt-dlp`. In interactive terminals it can prompt to run an install command automatically (with explicit confirmation first).
+
 ### No audio
 
 1. Check volume isn't muted (`=` to increase)