@involvex/youtube-music-cli 0.0.33 → 0.0.35

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [0.0.35](https://github.com/involvex/youtube-music-cli/compare/v0.0.34...v0.0.35) (2026-02-22)
+
+### Features
+
+- add history layout for recently played tracks ([a33c93c](https://github.com/involvex/youtube-music-cli/commit/a33c93c485e8e0e42a4d233cb60b06f4c08452cb))
+
+## [0.0.34](https://github.com/involvex/youtube-music-cli/compare/v0.0.33...v0.0.34) (2026-02-22)
+
+### Features
+
+- **search:** implement search filters by artist, album, and year ([d3edbe6](https://github.com/involvex/youtube-music-cli/commit/d3edbe6b61fd0afa363e1c19b420d73fd6ebbab7))
+
 ## [0.0.33](https://github.com/involvex/youtube-music-cli/compare/v0.0.32...v0.0.33) (2026-02-22)
 
 ### Features

package/dist/source/components/layouts/HistoryLayout.d.ts

@@ -0,0 +1 @@
+export default function HistoryLayout(): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,37 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box, Text } from 'ink';
+import { useTheme } from "../../hooks/useTheme.js";
+import { useHistory } from "../../stores/history.store.js";
+import { useTerminalSize } from "../../hooks/useTerminalSize.js";
+import { truncate } from "../../utils/format.js";
+import { useKeyBinding } from "../../hooks/useKeyboard.js";
+import { KEYBINDINGS } from "../../utils/constants.js";
+import { useNavigation } from "../../hooks/useNavigation.js";
+const DATE_FORMATTER = new Intl.DateTimeFormat(undefined, {
+    dateStyle: 'medium',
+    timeStyle: 'short',
+});
+function formatTimestamp(iso) {
+    const date = new Date(iso);
+    if (Number.isNaN(date.getTime())) {
+        return iso;
+    }
+    return DATE_FORMATTER.format(date);
+}
+export default function HistoryLayout() {
+    const { theme } = useTheme();
+    const { history } = useHistory();
+    const { columns } = useTerminalSize();
+    const { dispatch } = useNavigation();
+    useKeyBinding(KEYBINDINGS.BACK, () => {
+        dispatch({ category: 'GO_BACK' });
+    });
+    const maxTitleLength = Math.max(30, columns - 20);
+    return (_jsxs(Box, { flexDirection: "column", padding: 1, gap: 1, children: [_jsx(Box, { marginBottom: 1, children: _jsx(Text, { color: theme.colors.primary, bold: true, children: "Recently Played" }) }), history.length === 0 ? (_jsx(Text, { color: theme.colors.dim, children: "No listening history yet." })) : (history.map(entry => {
+                const artists = entry.track.artists
+                    ?.map(artist => artist.name)
+                    .join(', ')
+                    .trim();
+                return (_jsxs(Box, { flexDirection: "column", paddingY: 1, borderStyle: "round", borderColor: theme.colors.dim, children: [_jsx(Text, { color: theme.colors.secondary, children: formatTimestamp(entry.playedAt) }), _jsxs(Box, { children: [_jsx(Text, { color: theme.colors.text, bold: true, children: truncate(entry.track.title, maxTitleLength) }), _jsx(Text, { color: theme.colors.dim, children: artists ? ` • ${artists}` : '' })] }), entry.track.album?.name && (_jsxs(Text, { color: theme.colors.dim, children: ["Album: ", entry.track.album.name] }))] }, `${entry.playedAt}-${entry.track.videoId}`));
+            })), _jsx(Box, { marginTop: 1, children: _jsx(Text, { color: theme.colors.dim, children: "Esc to go back \u2022 Shift+H to reopen history" }) })] }));
+}

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

@@ -20,6 +20,7 @@ import SearchHistory from "../search/SearchHistory.js";
 import KeybindingsLayout from "../config/KeybindingsLayout.js";
 import TrendingLayout from "./TrendingLayout.js";
 import ExploreLayout from "./ExploreLayout.js";
+import HistoryLayout from "./HistoryLayout.js";
 import ImportLayout from "../import/ImportLayout.js";
 import ExportLayout from "../export/ExportLayout.js";
 import { KEYBINDINGS, VIEW } from "../../utils/constants.js";
@@ -51,6 +52,9 @@ function MainLayout() {
     const goToSettings = useCallback(() => {
         dispatch({ category: 'NAVIGATE', view: VIEW.SETTINGS });
     }, [dispatch]);
+    const goToHistory = useCallback(() => {
+        dispatch({ category: 'NAVIGATE', view: VIEW.HISTORY });
+    }, [dispatch]);
     const goToHelp = useCallback(() => {
         if (navState.currentView === VIEW.HELP) {
             dispatch({ category: 'GO_BACK' });
@@ -125,6 +129,7 @@ function MainLayout() {
     useKeyBinding(KEYBINDINGS.PLAYLISTS, goToPlaylists);
     useKeyBinding(KEYBINDINGS.PLUGINS, goToPlugins);
     useKeyBinding(KEYBINDINGS.SUGGESTIONS, goToSuggestions);
+    useKeyBinding(KEYBINDINGS.HISTORY, goToHistory);
     useKeyBinding(KEYBINDINGS.SETTINGS, goToSettings);
     useKeyBinding(KEYBINDINGS.HELP, goToHelp);
     useKeyBinding(['M'], togglePlayerMode);
@@ -154,6 +159,8 @@ function MainLayout() {
                 return _jsx(PlaylistList, {}, "playlists");
             case 'suggestions':
                 return _jsx(Suggestions, {}, "suggestions");
+            case 'history':
+                return _jsx(HistoryLayout, {}, "history");
             case 'settings':
                 return _jsx(Settings, {}, "settings");
             case 'plugins':

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

@@ -3,7 +3,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useNavigation } from "../../hooks/useNavigation.js";
 import { useYouTubeMusic } from "../../hooks/useYouTubeMusic.js";
 import SearchResults from "../search/SearchResults.js";
-import { useState, useCallback, useEffect, useRef } from 'react';
+import { useState, useCallback, useEffect, useRef, useMemo } from 'react';
 import React from 'react';
 import { useTheme } from "../../hooks/useTheme.js";
 import SearchBar from "../search/SearchBar.js";
@@ -12,17 +12,57 @@ import { KEYBINDINGS, VIEW } from "../../utils/constants.js";
 import { Box, Text } from 'ink';
 import { usePlayer } from "../../hooks/usePlayer.js";
 import { ICONS } from "../../utils/icons.js";
+import TextInput from 'ink-text-input';
+import { applySearchFilters } from "../../utils/search-filters.js";
+const FILTER_LABELS = {
+    artist: 'Artist',
+    album: 'Album',
+    year: 'Year',
+};
+const DURATION_ORDER = [
+    'all',
+    'short',
+    'medium',
+    'long',
+];
 function SearchLayout() {
     const { theme } = useTheme();
     const { state: navState, dispatch } = useNavigation();
     const { state: playerState } = usePlayer();
     const { isLoading, error, search } = useYouTubeMusic();
-    const [results, setResults] = useState([]);
+    const [rawResults, setRawResults] = useState([]);
+    const filteredResults = useMemo(() => applySearchFilters(rawResults, navState.searchFilters), [rawResults, navState.searchFilters]);
     const [isTyping, setIsTyping] = useState(true);
     const [isSearching, setIsSearching] = useState(false);
     const [actionMessage, setActionMessage] = useState(null);
     const actionTimeoutRef = useRef(null);
     const lastAutoSearchedQueryRef = useRef(null);
+    const [editingFilter, setEditingFilter] = useState(null);
+    const [filterDraft, setFilterDraft] = useState('');
+    const describeFilterValue = (value) => value?.trim() ? value.trim() : 'Any';
+    const handleFilterSubmit = useCallback((value) => {
+        if (!editingFilter)
+            return;
+        dispatch({
+            category: 'SET_SEARCH_FILTERS',
+            filters: { [editingFilter]: value.trim() },
+        });
+        setEditingFilter(null);
+        setFilterDraft('');
+    }, [dispatch, editingFilter]);
+    const beginFilterEdit = useCallback((field) => {
+        setEditingFilter(field);
+        setFilterDraft(navState.searchFilters[field] ?? '');
+    }, [navState.searchFilters]);
+    const cycleDurationFilter = useCallback(() => {
+        const currentIndex = DURATION_ORDER.indexOf(navState.searchFilters.duration ?? 'all');
+        const nextIndex = (currentIndex + 1) % DURATION_ORDER.length;
+        const nextDuration = DURATION_ORDER[nextIndex];
+        dispatch({
+            category: 'SET_SEARCH_FILTERS',
+            filters: { duration: nextDuration },
+        });
+    }, [dispatch, navState.searchFilters.duration]);
     // Handle search action
     const performSearch = useCallback(async (query) => {
         if (!query || isSearching)
@@ -33,7 +73,7 @@ function SearchLayout() {
             limit: navState.searchLimit,
         });
         if (response) {
-            setResults(response.results);
+            setRawResults(response.results);
             dispatch({ category: 'SET_SELECTED_RESULT', index: 0 });
             dispatch({ category: 'SET_HAS_SEARCHED', hasSearched: true });
             // Defer focus switch to avoid consuming the same Enter key
@@ -58,6 +98,10 @@ function SearchLayout() {
         }
     }, [isTyping, dispatch]);
     useKeyBinding(['h'], goToHistory);
+    useKeyBinding(KEYBINDINGS.SEARCH_FILTER_ARTIST, () => beginFilterEdit('artist'));
+    useKeyBinding(KEYBINDINGS.SEARCH_FILTER_ALBUM, () => beginFilterEdit('album'));
+    useKeyBinding(KEYBINDINGS.SEARCH_FILTER_YEAR, () => beginFilterEdit('year'));
+    useKeyBinding(KEYBINDINGS.SEARCH_FILTER_DURATION, cycleDurationFilter);
     // Initial search if query is in state (usually from CLI flags)
     useEffect(() => {
         const query = navState.searchQuery.trim();
@@ -74,6 +118,11 @@ function SearchLayout() {
     }, [navState.searchQuery, navState.hasSearched, performSearch]);
     // Handle going back
     const goBack = useCallback(() => {
+        if (editingFilter) {
+            setEditingFilter(null);
+            setFilterDraft('');
+            return;
+        }
         if (!isTyping) {
             setIsTyping(true); // Back to typing if in results
             dispatch({ category: 'SET_HAS_SEARCHED', hasSearched: false });
@@ -81,7 +130,7 @@ function SearchLayout() {
         else {
             dispatch({ category: 'GO_BACK' });
         }
-    }, [isTyping, dispatch]);
+    }, [editingFilter, isTyping, dispatch]);
     useKeyBinding(KEYBINDINGS.BACK, goBack);
     const handleMixCreated = useCallback((message) => {
         setActionMessage(message);
@@ -113,16 +162,31 @@ function SearchLayout() {
     // Reset search state when leaving view
     useEffect(() => {
         return () => {
-            setResults([]);
+            setRawResults([]);
             dispatch({ category: 'SET_HAS_SEARCHED', hasSearched: false });
             dispatch({ category: 'SET_SEARCH_QUERY', query: '' });
             lastAutoSearchedQueryRef.current = null;
         };
     }, [dispatch]);
+    useEffect(() => {
+        if (filteredResults.length > 0 &&
+            navState.selectedResult >= filteredResults.length) {
+            dispatch({ category: 'SET_SELECTED_RESULT', index: 0 });
+        }
+    }, [dispatch, filteredResults.length, navState.selectedResult]);
+    const artistFilterLabel = describeFilterValue(navState.searchFilters.artist);
+    const albumFilterLabel = describeFilterValue(navState.searchFilters.album);
+    const yearFilterLabel = describeFilterValue(navState.searchFilters.year);
+    const durationFilterLabel = navState.searchFilters.duration && navState.searchFilters.duration !== 'all'
+        ? navState.searchFilters.duration
+        : 'Any';
     return (_jsxs(Box, { flexDirection: "column", children: [playerState.currentTrack && (_jsxs(Box, { children: [_jsx(Text, { color: theme.colors.dim, children: playerState.isPlaying ? `${ICONS.PLAY} ` : `${ICONS.PAUSE} ` }), _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 => {
+                        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: !editingFilter && 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
+                } }), editingFilter ? (_jsxs(Box, { flexDirection: "column", marginY: 1, children: [_jsxs(Box, { children: [_jsxs(Text, { color: theme.colors.primary, bold: true, children: ["Set ", FILTER_LABELS[editingFilter], " filter:"] }), _jsx(TextInput, { value: filterDraft, onChange: setFilterDraft, onSubmit: handleFilterSubmit, placeholder: "Type value and hit Enter", focus: true })] }), _jsx(Text, { color: theme.colors.dim, children: "Press Enter to save (empty to clear) or Esc to cancel." })] })) : (_jsx(Box, { marginY: 1, children: _jsxs(Text, { color: theme.colors.dim, children: ["Filters: Artist=", artistFilterLabel, ", Album=", albumFilterLabel, ", Year=", yearFilterLabel, ", Duration=", durationFilterLabel, " (Ctrl+A Artist, Ctrl+L Album, Ctrl+Y Year, Ctrl+D Duration)"] }) })), (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: filteredResults, selectedIndex: navState.selectedResult, isActive: !isTyping, onMixCreated: handleMixCreated, onDownloadStatus: handleDownloadStatus })), !isLoading &&
+                navState.hasSearched &&
+                filteredResults.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'
                     : `Arrows to navigate, Enter to play, M mix, Shift+D download, ]/[ more/fewer results (${navState.searchLimit}), H history, Esc to type` })] }));
 }

package/dist/source/main.js

@@ -5,6 +5,7 @@ import { PluginsProvider } from "./stores/plugins.store.js";
 import MainLayout from "./components/layouts/MainLayout.js";
 import { ThemeProvider } from "./contexts/theme.context.js";
 import { PlayerProvider } from "./stores/player.store.js";
+import { HistoryProvider } from "./stores/history.store.js";
 import { ErrorBoundary } from "./components/common/ErrorBoundary.js";
 import { KeyboardManager } from "./hooks/useKeyboard.js";
 import { KeyboardBlockProvider } from "./hooks/useKeyboardBlocker.js";
@@ -122,5 +123,5 @@ function HeadlessLayout({ flags }) {
     return (_jsx(Box, { padding: 1, children: _jsx(Text, { color: "green", children: "Headless mode active." }) }));
 }
 export default function Main({ flags }) {
-    return (_jsx(ErrorBoundary, { children: _jsx(ThemeProvider, { children: _jsx(PlayerProvider, { children: _jsx(NavigationProvider, { children: _jsx(PluginsProvider, { children: _jsx(KeyboardBlockProvider, { children: _jsxs(Box, { flexDirection: "column", children: [_jsx(KeyboardManager, {}), flags?.headless ? (_jsx(HeadlessLayout, { flags: flags })) : (_jsxs(_Fragment, { children: [_jsx(Initializer, { flags: flags }), _jsx(MainLayout, {})] }))] }) }) }) }) }) }) }));
+    return (_jsx(ErrorBoundary, { children: _jsx(ThemeProvider, { children: _jsx(PlayerProvider, { children: _jsx(HistoryProvider, { children: _jsx(NavigationProvider, { children: _jsx(PluginsProvider, { children: _jsx(KeyboardBlockProvider, { children: _jsxs(Box, { flexDirection: "column", children: [_jsx(KeyboardManager, {}), flags?.headless ? (_jsx(HeadlessLayout, { flags: flags })) : (_jsxs(_Fragment, { children: [_jsx(Initializer, { flags: flags }), _jsx(MainLayout, {})] }))] }) }) }) }) }) }) }) }));
 }

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

@@ -0,0 +1,4 @@
+import type { HistoryEntry } from '../../types/history.types.ts';
+export declare function saveHistory(entries: HistoryEntry[]): Promise<void>;
+export declare function loadHistory(): Promise<HistoryEntry[]>;
+export declare function clearHistory(): Promise<void>;

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

@@ -0,0 +1,83 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { CONFIG_DIR } from "../../utils/constants.js";
+import { logger } from "../logger/logger.service.js";
+const HISTORY_FILE = join(CONFIG_DIR, 'history.json');
+const SCHEMA_VERSION = 1;
+const defaultHistory = {
+    schemaVersion: SCHEMA_VERSION,
+    entries: [],
+    lastUpdated: new Date().toISOString(),
+};
+export async function saveHistory(entries) {
+    try {
+        if (!existsSync(CONFIG_DIR)) {
+            await mkdir(CONFIG_DIR, { recursive: true });
+        }
+        const stateToSave = {
+            ...defaultHistory,
+            entries,
+            lastUpdated: new Date().toISOString(),
+        };
+        const tempFile = `${HISTORY_FILE}.tmp`;
+        await writeFile(tempFile, JSON.stringify(stateToSave, null, 2), 'utf8');
+        if (process.platform === 'win32' && existsSync(HISTORY_FILE)) {
+            await import('node:fs/promises').then(fs => fs.unlink(HISTORY_FILE));
+        }
+        await import('node:fs/promises').then(fs => fs.rename(tempFile, HISTORY_FILE));
+        logger.debug('HistoryService', 'Saved listening history', {
+            count: entries.length,
+        });
+    }
+    catch (error) {
+        logger.error('HistoryService', 'Failed to save listening history', {
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+}
+export async function loadHistory() {
+    try {
+        if (!existsSync(HISTORY_FILE)) {
+            logger.debug('HistoryService', 'No history file found');
+            return [];
+        }
+        const data = await readFile(HISTORY_FILE, 'utf8');
+        const persisted = JSON.parse(data);
+        if (persisted.schemaVersion !== SCHEMA_VERSION) {
+            logger.warn('HistoryService', 'Schema version mismatch', {
+                expected: SCHEMA_VERSION,
+                found: persisted.schemaVersion,
+            });
+            return [];
+        }
+        if (!Array.isArray(persisted.entries)) {
+            logger.warn('HistoryService', 'Invalid history format, resetting');
+            return [];
+        }
+        logger.info('HistoryService', 'Loaded listening history', {
+            count: persisted.entries.length,
+            lastUpdated: persisted.lastUpdated,
+        });
+        return persisted.entries;
+    }
+    catch (error) {
+        logger.error('HistoryService', 'Failed to load listening history', {
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return [];
+    }
+}
+export async function clearHistory() {
+    try {
+        if (existsSync(HISTORY_FILE)) {
+            await import('node:fs/promises').then(fs => fs.unlink(HISTORY_FILE));
+            logger.info('HistoryService', 'Cleared listening history');
+        }
+    }
+    catch (error) {
+        logger.error('HistoryService', 'Failed to clear listening history', {
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+}

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

@@ -7,6 +7,10 @@ export type PlayOptions = {
     crossfadeDuration?: number;
     equalizerPreset?: EqualizerPreset;
 };
+export type MpvArgsOptions = PlayOptions & {
+    volume: number;
+};
+export declare function buildMpvArgs(url: string, ipcPath: string, options: MpvArgsOptions): string[];
 export type PlayerEventCallback = (event: {
     timePos?: number;
     duration?: number;

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

@@ -2,6 +2,44 @@
 import { spawn } from 'node:child_process';
 import { connect } from 'node:net';
 import { logger } from "../logger/logger.service.js";
+export function buildMpvArgs(url, ipcPath, options) {
+    const gapless = options.gaplessPlayback ?? true;
+    const crossfadeDuration = Math.max(0, options.crossfadeDuration ?? 0);
+    const eqPreset = options.equalizerPreset ?? 'flat';
+    const audioFilters = [];
+    if (options.audioNormalization) {
+        audioFilters.push('dynaudnorm');
+    }
+    if (crossfadeDuration > 0) {
+        audioFilters.push(`acrossfade=d=${crossfadeDuration}`);
+    }
+    const presetFilters = EQUALIZER_PRESET_FILTERS[eqPreset] ?? [];
+    if (presetFilters.length > 0) {
+        audioFilters.push(...presetFilters);
+    }
+    const mpvArgs = [
+        '--no-video',
+        '--no-terminal',
+        `--volume=${options.volume}`,
+        '--no-audio-display',
+        '--really-quiet',
+        '--msg-level=all=error',
+        `--input-ipc-server=${ipcPath}`,
+        '--idle=yes',
+        '--cache=yes',
+        '--cache-secs=30',
+        '--network-timeout=10',
+        `--gapless-audio=${gapless ? 'yes' : 'no'}`,
+    ];
+    if (audioFilters.length > 0) {
+        mpvArgs.push(`--af=${audioFilters.join(',')}`);
+    }
+    if (options.proxy) {
+        mpvArgs.push(`--http-proxy=${options.proxy}`);
+    }
+    mpvArgs.push(url);
+    return mpvArgs;
+}
 const EQUALIZER_PRESET_FILTERS = {
     flat: [],
     bass_boost: ['equalizer=f=60:width_type=o:width=2:g=5'],
@@ -225,42 +263,14 @@ class PlayerService {
                     volume: this.currentVolume,
                     ipcPath: this.ipcPath,
                 });
-                const gapless = options?.gaplessPlayback ?? true;
-                const crossfadeDuration = Math.max(0, options?.crossfadeDuration ?? 0);
-                const eqPreset = options?.equalizerPreset ?? 'flat';
-                const audioFilters = [];
-                if (options?.audioNormalization) {
-                    audioFilters.push('dynaudnorm');
-                }
-                if (crossfadeDuration > 0) {
-                    audioFilters.push(`acrossfade=d=${crossfadeDuration}`);
-                }
-                const presetFilters = EQUALIZER_PRESET_FILTERS[eqPreset] ?? [];
-                if (presetFilters.length > 0) {
-                    audioFilters.push(...presetFilters);
-                }
-                // Spawn mpv with JSON IPC for better control
-                const mpvArgs = [
-                    '--no-video', // Audio only
-                    '--no-terminal', // Don't read from stdin
-                    `--volume=${this.currentVolume}`,
-                    '--no-audio-display', // Don't show album art in terminal
-                    '--really-quiet', // Minimal output
-                    '--msg-level=all=error', // Only show errors
-                    `--input-ipc-server=${this.ipcPath}`, // Enable IPC
-                    '--idle=yes', // Keep mpv running after playback ends
-                    '--cache=yes', // Enable cache for network streams
-                    '--cache-secs=30', // Buffer 30 seconds ahead
-                    '--network-timeout=10', // 10s network timeout
-                    `--gapless-audio=${gapless ? 'yes' : 'no'}`,
-                ];
-                if (audioFilters.length > 0) {
-                    mpvArgs.push(`--af=${audioFilters.join(',')}`);
-                }
-                if (options?.proxy) {
-                    mpvArgs.push(`--http-proxy=${options.proxy}`);
-                }
-                mpvArgs.push(playUrl);
+                const mpvArgs = buildMpvArgs(playUrl, this.ipcPath, {
+                    volume: this.currentVolume,
+                    audioNormalization: options?.audioNormalization,
+                    proxy: options?.proxy,
+                    gaplessPlayback: options?.gaplessPlayback,
+                    crossfadeDuration: options?.crossfadeDuration,
+                    equalizerPreset: options?.equalizerPreset,
+                });
                 // 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(this.getMpvCommand(), mpvArgs, {

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

@@ -0,0 +1,11 @@
+import { type ReactNode } from 'react';
+import type { HistoryEntry } from '../types/history.types.ts';
+type HistoryState = HistoryEntry[];
+type HistoryContextValue = {
+    history: HistoryState;
+};
+export declare function HistoryProvider({ children }: {
+    children: ReactNode;
+}): import("react/jsx-runtime").JSX.Element;
+export declare function useHistory(): HistoryContextValue;
+export {};

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

@@ -0,0 +1,64 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext, useEffect, useMemo, useReducer, useRef, } from 'react';
+import { usePlayer } from "../hooks/usePlayer.js";
+import { loadHistory, saveHistory } from "../services/history/history.service.js";
+const MAX_HISTORY_ENTRIES = 500;
+function historyReducer(state, action) {
+    switch (action.category) {
+        case 'SET_HISTORY':
+            return action.entries;
+        case 'ADD_ENTRY':
+            return [action.entry, ...state].slice(0, MAX_HISTORY_ENTRIES);
+        default:
+            return state;
+    }
+}
+const HistoryContext = createContext(null);
+export function HistoryProvider({ children }) {
+    const [state, dispatch] = useReducer(historyReducer, []);
+    const { state: playerState } = usePlayer();
+    const lastLoggedId = useRef(null);
+    useEffect(() => {
+        let cancelled = false;
+        void loadHistory().then(entries => {
+            if (!cancelled) {
+                dispatch({ category: 'SET_HISTORY', entries });
+            }
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, []);
+    useEffect(() => {
+        if (!playerState.currentTrack) {
+            lastLoggedId.current = null;
+            return;
+        }
+        if (!playerState.isPlaying) {
+            lastLoggedId.current = null;
+            return;
+        }
+        const videoId = playerState.currentTrack.videoId;
+        if (lastLoggedId.current === videoId) {
+            return;
+        }
+        lastLoggedId.current = videoId;
+        const entry = {
+            track: playerState.currentTrack,
+            playedAt: new Date().toISOString(),
+        };
+        dispatch({ category: 'ADD_ENTRY', entry });
+    }, [playerState.currentTrack, playerState.isPlaying]);
+    useEffect(() => {
+        void saveHistory(state);
+    }, [state]);
+    const value = useMemo(() => ({ history: state }), [state]);
+    return (_jsx(HistoryContext.Provider, { value: value, children: children }));
+}
+export function useHistory() {
+    const context = useContext(HistoryContext);
+    if (!context) {
+        throw new Error('useHistory must be used within HistoryProvider');
+    }
+    return context;
+}

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

@@ -1,5 +1,11 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { createContext, useContext, useReducer, useMemo, } from 'react';
+const defaultSearchFilters = {
+    artist: '',
+    album: '',
+    year: '',
+    duration: 'all',
+};
 const initialState = {
     currentView: 'player',
     previousView: null,
@@ -12,6 +18,7 @@ const initialState = {
     searchLimit: 10,
     history: [],
     playerMode: 'full',
+    searchFilters: defaultSearchFilters,
 };
 function navigationReducer(state, action) {
     switch (action.category) {
@@ -38,6 +45,16 @@ function navigationReducer(state, action) {
             return { ...state, searchQuery: action.query };
         case 'SET_SEARCH_CATEGORY':
             return { ...state, searchCategory: action.category };
+        case 'SET_SEARCH_FILTERS':
+            return {
+                ...state,
+                searchFilters: { ...state.searchFilters, ...action.filters },
+            };
+        case 'CLEAR_SEARCH_FILTERS':
+            return {
+                ...state,
+                searchFilters: defaultSearchFilters,
+            };
         case 'SET_SELECTED_RESULT':
             return { ...state, selectedResult: action.index };
         case 'SET_SELECTED_PLAYLIST':

package/dist/source/types/actions.d.ts

@@ -1,4 +1,4 @@
-import type { Track } from './youtube-music.types.ts';
+import type { SearchFilters, Track } from './youtube-music.types.ts';
 export interface PlayAction {
     readonly category: 'PLAY';
     track: Track;
@@ -111,6 +111,13 @@ export interface SetSearchCategoryAction {
     readonly category: 'SET_SEARCH_CATEGORY';
     searchType: string;
 }
+export interface SetSearchFiltersAction {
+    readonly category: 'SET_SEARCH_FILTERS';
+    filters: Partial<SearchFilters>;
+}
+export interface ClearSearchFiltersAction {
+    readonly category: 'CLEAR_SEARCH_FILTERS';
+}
 export interface SetSelectedResultAction {
     readonly category: 'SET_SELECTED_RESULT';
     index: number;

package/dist/source/types/history.types.d.ts

@@ -0,0 +1,10 @@
+import type { Track } from './youtube-music.types.ts';
+export interface HistoryEntry {
+    track: Track;
+    playedAt: string;
+}
+export interface PersistedHistory {
+    schemaVersion: number;
+    entries: HistoryEntry[];
+    lastUpdated: string;
+}

package/dist/source/types/history.types.js

@@ -0,0 +1 @@
+export {};

package/dist/source/types/navigation.types.d.ts

@@ -1,4 +1,5 @@
-import type { NavigateAction, GoBackAction, SetSearchQueryAction, SetSearchCategoryAction, SetSelectedResultAction, SetSelectedPlaylistAction, SetHasSearchedAction, SetSearchLimitAction, TogglePlayerModeAction, DetachAction } from './actions.ts';
+import type { NavigateAction, GoBackAction, SetSearchQueryAction, SetSearchCategoryAction, SetSearchFiltersAction, ClearSearchFiltersAction, SetSelectedResultAction, SetSelectedPlaylistAction, SetHasSearchedAction, SetSearchLimitAction, TogglePlayerModeAction, DetachAction } from './actions.ts';
+import type { SearchFilters } from './youtube-music.types.ts';
 export interface NavigationState {
     currentView: string;
     previousView: string | null;
@@ -11,5 +12,6 @@ export interface NavigationState {
     searchLimit: number;
     history: string[];
     playerMode: 'full' | 'mini';
+    searchFilters: SearchFilters;
 }
-export type NavigationAction = NavigateAction | GoBackAction | SetSearchQueryAction | SetSearchCategoryAction | SetSelectedResultAction | SetSelectedPlaylistAction | SetHasSearchedAction | SetSearchLimitAction | TogglePlayerModeAction | DetachAction;
+export type NavigationAction = NavigateAction | GoBackAction | SetSearchQueryAction | SetSearchCategoryAction | SetSearchFiltersAction | ClearSearchFiltersAction | SetSelectedResultAction | SetSelectedPlaylistAction | SetHasSearchedAction | SetSearchLimitAction | TogglePlayerModeAction | DetachAction;

package/dist/source/types/youtube-music.types.d.ts

@@ -33,3 +33,10 @@ export interface SearchOptions {
     limit?: number;
     continuation?: string;
 }
+export type SearchDurationFilter = 'all' | 'short' | 'medium' | 'long';
+export interface SearchFilters {
+    artist?: string;
+    album?: string;
+    year?: string;
+    duration?: SearchDurationFilter;
+}

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

@@ -20,6 +20,7 @@ export declare const VIEW: {
     readonly EXPLORE: "explore";
     readonly IMPORT: "import";
     readonly EXPORT_PLAYLISTS: "export_playlists";
+    readonly HISTORY: "history";
 };
 export declare const SEARCH_TYPE: {
     readonly ALL: "all";
@@ -34,6 +35,7 @@ export declare const KEYBINDINGS: {
     readonly SEARCH: readonly ["/"];
     readonly PLAYLISTS: readonly ["shift+p"];
     readonly SUGGESTIONS: readonly ["g"];
+    readonly HISTORY: readonly ["shift+h"];
     readonly SETTINGS: readonly [","];
     readonly PLUGINS: readonly ["p"];
     readonly DETACH: readonly ["shift+q"];
@@ -63,6 +65,10 @@ export declare const KEYBINDINGS: {
     readonly PREV_RESULT: readonly ["shift+tab"];
     readonly INCREASE_RESULTS: readonly ["]"];
     readonly DECREASE_RESULTS: readonly ["["];
+    readonly SEARCH_FILTER_ARTIST: readonly ["ctrl+a"];
+    readonly SEARCH_FILTER_ALBUM: readonly ["ctrl+l"];
+    readonly SEARCH_FILTER_YEAR: readonly ["ctrl+y"];
+    readonly SEARCH_FILTER_DURATION: readonly ["ctrl+d"];
     readonly ADD_TO_PLAYLIST: readonly ["a"];
     readonly REMOVE_FROM_PLAYLIST: readonly ["d"];
     readonly CREATE_PLAYLIST: readonly ["c"];

package/dist/source/utils/constants.js

@@ -25,6 +25,7 @@ export const VIEW = {
     EXPLORE: 'explore',
     IMPORT: 'import',
     EXPORT_PLAYLISTS: 'export_playlists',
+    HISTORY: 'history',
 };
 // Search types
 export const SEARCH_TYPE = {
@@ -42,6 +43,7 @@ export const KEYBINDINGS = {
     SEARCH: ['/'],
     PLAYLISTS: ['shift+p'],
     SUGGESTIONS: ['g'],
+    HISTORY: ['shift+h'],
     SETTINGS: [','],
     PLUGINS: ['p'],
     DETACH: ['shift+q'],
@@ -74,6 +76,10 @@ export const KEYBINDINGS = {
     PREV_RESULT: ['shift+tab'],
     INCREASE_RESULTS: [']'],
     DECREASE_RESULTS: ['['],
+    SEARCH_FILTER_ARTIST: ['ctrl+a'],
+    SEARCH_FILTER_ALBUM: ['ctrl+l'],
+    SEARCH_FILTER_YEAR: ['ctrl+y'],
+    SEARCH_FILTER_DURATION: ['ctrl+d'],
     // Playlist
     ADD_TO_PLAYLIST: ['a'],
     REMOVE_FROM_PLAYLIST: ['d'],

package/dist/source/utils/search-filters.d.ts

@@ -0,0 +1,2 @@
+import type { SearchFilters, SearchResult } from '../types/youtube-music.types.ts';
+export declare function applySearchFilters(results: SearchResult[], filters: SearchFilters): SearchResult[];

package/dist/source/utils/search-filters.js

@@ -0,0 +1,100 @@
+const DURATION_BUCKETS = {
+    short: { min: 0, max: 180 },
+    medium: { min: 181, max: 300 },
+    long: { min: 301, max: Number.POSITIVE_INFINITY },
+};
+function includesIgnoreCase(value, filter) {
+    return Boolean(value && value.toLowerCase().includes(filter));
+}
+function isSongResult(result) {
+    return result.type === 'song';
+}
+function isAlbumResult(result) {
+    return result.type === 'album';
+}
+function isArtistResult(result) {
+    return result.type === 'artist';
+}
+function isPlaylistResult(result) {
+    return result.type === 'playlist';
+}
+function matchesArtistFilter(result, filter) {
+    if (!filter)
+        return true;
+    if (isSongResult(result)) {
+        const track = result.data;
+        if (track.artists.some(artist => includesIgnoreCase(artist.name, filter))) {
+            return true;
+        }
+        if (track.album?.artists?.some(artist => includesIgnoreCase(artist.name, filter))) {
+            return true;
+        }
+    }
+    if (isAlbumResult(result)) {
+        return result.data.artists.some(artist => includesIgnoreCase(artist.name, filter));
+    }
+    if (isArtistResult(result)) {
+        return includesIgnoreCase(result.data.name, filter);
+    }
+    if (isPlaylistResult(result)) {
+        return includesIgnoreCase(result.data.name, filter);
+    }
+    return true;
+}
+function matchesAlbumFilter(result, filter) {
+    if (!filter)
+        return true;
+    if (isSongResult(result)) {
+        return includesIgnoreCase(result.data.album?.name, filter);
+    }
+    if (isAlbumResult(result)) {
+        return includesIgnoreCase(result.data.name, filter);
+    }
+    if (isPlaylistResult(result)) {
+        return includesIgnoreCase(result.data.name, filter);
+    }
+    return true;
+}
+function matchesYearFilter(result, filter) {
+    if (!filter)
+        return true;
+    const normalizedFilter = filter.toLowerCase();
+    const textSources = [];
+    if (isSongResult(result)) {
+        textSources.push(result.data.title, result.data.album?.name);
+    }
+    if (isAlbumResult(result)) {
+        textSources.push(result.data.name);
+        textSources.push(...result.data.artists.map(artist => artist.name));
+    }
+    if (isArtistResult(result)) {
+        textSources.push(result.data.name);
+    }
+    if (isPlaylistResult(result)) {
+        textSources.push(result.data.name);
+    }
+    return textSources.some(source => includesIgnoreCase(source, normalizedFilter));
+}
+function matchesDurationFilter(result, filter) {
+    if (!filter || filter === 'all') {
+        return true;
+    }
+    if (!isSongResult(result)) {
+        return true;
+    }
+    const duration = result.data.duration ?? 0;
+    const range = DURATION_BUCKETS[filter];
+    return duration >= range.min && duration <= range.max;
+}
+export function applySearchFilters(results, filters) {
+    const artistFilter = filters.artist?.trim().toLowerCase() ?? '';
+    const albumFilter = filters.album?.trim().toLowerCase() ?? '';
+    const yearFilter = filters.year?.trim() ?? '';
+    const durationFilter = filters.duration;
+    return results.filter(result => {
+        return (matchesArtistFilter(result, artistFilter) &&
+            matchesAlbumFilter(result, albumFilter) &&
+            matchesYearFilter(result, yearFilter) &&
+            matchesDurationFilter(result, durationFilter));
+    });
+}

package/package.json

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

package/readme.md

@@ -28,6 +28,10 @@ A powerful Terminal User Interface (TUI) music player for YouTube Music
 - 💾 **Downloads** - Save tracks/playlists/artists with `Shift+D`
 - 🏷️ **Metadata Tagging** - Auto-tag title/artist/album with optional cover art
 
+## Roadmap
+
+Visit [`SUGGESTIONS.md`](SUGGESTIONS.md) for the full backlog and use `docs/roadmap.md` to understand the current implementation focus (crossfade + gapless playback) and the next steps planned for equalizer/enhancements. The roadmap doc also explains how to pick up work so reviewers and contributors remain aligned.
+
 ## Prerequisites
 
 **Required:**