@involvex/youtube-music-cli 0.0.33 → 0.0.34

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [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/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/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/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

@@ -63,6 +63,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

@@ -74,6 +74,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.34",
 	"description": "- A Commandline music player for youtube-music",
 	"repository": {
 		"type": "git",