@involvex/youtube-music-cli 0.0.34 → 0.0.35

package/CHANGELOG.md

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

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/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/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/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"];

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'],

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@involvex/youtube-music-cli",
-	"version": "0.0.34",
+	"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:**