@involvex/youtube-music-cli 0.0.12 → 0.0.14

package/CHANGELOG.md

@@ -1,3 +1,21 @@
+## [0.0.14](https://github.com/involvex/youtube-music-cli/compare/v0.0.13...v0.0.14) (2026-02-18)
+
+### Features
+
+- **download:** add download feature with configuration and shortcuts ([a616c4c](https://github.com/involvex/youtube-music-cli/commit/a616c4c2443cb6f7d929268fd08453708255503c))
+
+## [0.0.13](https://github.com/involvex/youtube-music-cli/compare/v0.0.12...v0.0.13) (2026-02-18)
+
+### Features
+
+- **download:** add cover art and improved file organization ([1d48f7d](https://github.com/involvex/youtube-music-cli/commit/1d48f7de3a4787e9341697b4c6f44a50a43e752c))
+
+### BREAKING CHANGES
+
+- **download:** The output file structure has changed from flat directory
+  to nested artist/album directories. Existing workflows expecting the old
+  structure will need to be updated.
+
 ## [0.0.12](https://github.com/involvex/youtube-music-cli/compare/v0.0.11...v0.0.12) (2026-02-18)
 
 ## [0.0.11](https://github.com/involvex/youtube-music-cli/compare/v0.0.10...v0.0.11) (2026-02-18)

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

@@ -1,4 +1,4 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
 // Search view layout
 import { useNavigation } from "../../hooks/useNavigation.js";
 import { useYouTubeMusic } from "../../hooks/useYouTubeMusic.js";
@@ -108,7 +108,7 @@ function SearchLayout() {
             dispatch({ category: 'SET_SEARCH_QUERY', query: '' });
         };
     }, [dispatch]);
-    return (_jsxs(Box, { flexDirection: "column", gap: 1, children: [_jsxs(Box, { borderStyle: "single", borderColor: theme.colors.secondary, paddingX: 1, children: [_jsx(Text, { bold: true, color: theme.colors.primary, children: "Search" }), _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: [_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/components/search/SearchBar.js

@@ -48,8 +48,8 @@ function SearchBar({ onInput, isActive = true }) {
     useKeyBinding(['tab'], cycleType);
     useKeyBinding(['escape'], clearSearch);
     useKeyboardBlocker(isActive);
-    return (_jsxs(Box, { flexDirection: "column", borderStyle: "single", borderColor: theme.colors.secondary, padding: 1, children: [_jsxs(Box, { marginBottom: 1, children: [_jsx(Text, { color: theme.colors.dim, children: "Type: " }), searchTypes.map((type, index) => (_jsxs(Text, { color: navState.searchType === type
+    return (_jsxs(Box, { flexDirection: "column", borderStyle: "single", borderColor: theme.colors.secondary, paddingX: 1, children: [_jsxs(Box, { children: [_jsx(Text, { color: theme.colors.dim, children: "Type: " }), searchTypes.map((type, index) => (_jsxs(Text, { color: navState.searchType === type
                             ? theme.colors.primary
-                            : theme.colors.dim, bold: navState.searchType === type, children: [type, index < searchTypes.length - 1 && ' '] }, type))), _jsx(Text, { color: theme.colors.dim, children: " (Tab to switch)" })] }), isActive && (_jsxs(Box, { children: [_jsx(Text, { color: theme.colors.primary, children: "Search: " }), _jsx(TextInput, { value: input, onChange: setInput, onSubmit: handleSubmit, placeholder: "Type to search...", focus: isActive })] })), !isActive && (_jsxs(Box, { children: [_jsx(Text, { color: theme.colors.primary, children: "Search: " }), _jsx(Text, { color: theme.colors.dim, children: input || 'Type to search...' })] })), _jsx(Text, { color: theme.colors.dim, children: "Type to search, Enter to search, Tab to change type, Esc to clear" })] }));
+                            : theme.colors.dim, bold: navState.searchType === type, children: [type, index < searchTypes.length - 1 && ' '] }, type))), _jsx(Text, { color: theme.colors.dim, children: " (Tab to switch)" })] }), isActive && (_jsxs(Box, { children: [_jsx(Text, { color: theme.colors.primary, children: "Search: " }), _jsx(TextInput, { value: input, onChange: setInput, onSubmit: handleSubmit, placeholder: "Type to search...", focus: isActive })] })), !isActive && (_jsxs(Box, { children: [_jsx(Text, { color: theme.colors.primary, children: "Search: " }), _jsx(Text, { color: theme.colors.dim, children: input || 'Type to search...' })] }))] }));
 }
 export default React.memo(SearchBar);

package/dist/source/components/search/SearchResults.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 results component
 import React from 'react';
 import { Box, Text } from 'ink';
@@ -7,7 +7,7 @@ import { useNavigation } from "../../hooks/useNavigation.js";
 import { useKeyBinding } from "../../hooks/useKeyboard.js";
 import { usePlayer } from "../../hooks/usePlayer.js";
 import { usePlaylist } from "../../hooks/usePlaylist.js";
-import { KEYBINDINGS, VIEW } from "../../utils/constants.js";
+import { KEYBINDINGS } from "../../utils/constants.js";
 import { truncate } from "../../utils/format.js";
 import { useCallback, useRef, useEffect, useState } from 'react';
 import { logger } from "../../services/logger/logger.service.js";
@@ -211,12 +211,9 @@ function SearchResults({ results, selectedIndex, isActive = true, onMixCreated,
         if (firstTrack) {
             playerDispatch({ category: 'PLAY', track: firstTrack });
         }
-        // Navigate to player view so the user lands on the queue/player
-        dispatch({ category: 'NAVIGATE', view: VIEW.PLAYER });
-        mixCreatedRef.current?.(`Created mix "${playlist.name}" with ${uniqueTracks.length} tracks — playing now.`);
+        mixCreatedRef.current?.(`Created mix "${playlist.name}" with ${uniqueTracks.length} tracks — playing now (Esc to go back).`);
     }, [
         createPlaylist,
-        dispatch,
         isActive,
         musicService,
         playerDispatch,
@@ -273,11 +270,11 @@ function SearchResults({ results, selectedIndex, isActive = true, onMixCreated,
     }
     // Calculate responsive truncation
     const maxTitleWidth = Math.max(20, Math.floor(columns * 0.4));
-    return (_jsxs(Box, { flexDirection: "column", gap: 1, children: [_jsxs(Text, { color: theme.colors.dim, bold: true, children: ["Results (", results.length, ")"] }), _jsx(Box, { paddingX: 1, children: _jsxs(Text, { color: theme.colors.dim, bold: true, children: ['#'.padEnd(6), " ", 'Type'.padEnd(10), " ", 'Title'.padEnd(maxTitleWidth)] }) }), results.map((result, index) => {
-                const isSelected = index === selectedIndex;
-                const data = result.data;
-                const title = 'title' in data ? data.title : 'name' in data ? data.name : 'Unknown';
-                return (_jsxs(Box, { paddingX: 1, borderStyle: isSelected ? 'double' : undefined, borderColor: isSelected ? theme.colors.primary : undefined, children: [_jsx(Text, { color: isSelected ? theme.colors.primary : theme.colors.dim, bold: isSelected, children: (isSelected ? '> ' : '  ') + (index + 1).toString().padEnd(4) }), _jsx(Text, { color: isSelected ? theme.colors.primary : theme.colors.dim, bold: isSelected, children: result.type.toUpperCase().padEnd(10) }), _jsx(Text, { color: isSelected ? theme.colors.primary : theme.colors.text, bold: isSelected, children: truncate(title, maxTitleWidth) })] }, index));
-            })] }));
+    return (_jsx(Box, { flexDirection: "column", children: results.map((result, index) => {
+            const isSelected = index === selectedIndex;
+            const data = result.data;
+            const title = 'title' in data ? data.title : 'name' in data ? data.name : 'Unknown';
+            return (_jsxs(Box, { paddingX: 1, backgroundColor: isSelected ? theme.colors.secondary : undefined, children: [_jsx(Text, { color: isSelected ? theme.colors.primary : theme.colors.dim, bold: isSelected, children: (isSelected ? '> ' : '  ') + (index + 1).toString().padEnd(4) }), _jsx(Text, { color: isSelected ? theme.colors.primary : theme.colors.dim, bold: isSelected, children: result.type.toUpperCase().padEnd(10) }), _jsx(Text, { color: isSelected ? theme.colors.primary : theme.colors.text, bold: isSelected, children: truncate(title, maxTitleWidth) })] }, index));
+        }) }));
 }
 export default React.memo(SearchResults);

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

@@ -30,8 +30,10 @@ declare class DownloadService {
     private fetchAudio;
     private ensureFfmpeg;
     private convertAudio;
+    private buildMetadataArgs;
     private runFfmpeg;
     private recordViaYtDlp;
+    private downloadCoverArt;
     private recordViaMpv;
 }
 export declare function getDownloadService(): DownloadService;

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

@@ -76,11 +76,13 @@ class DownloadService {
             for (const track of tracks) {
                 const destination = this.getDestinationPath(track, directory, format);
                 const tempSource = `${destination}.source`;
+                const tempCover = `${destination}.cover.jpg`;
                 try {
                     logger.info('DownloadService', 'Starting track download', {
                         videoId: track.videoId,
                         title: track.title,
                     });
+                    mkdirSync(path.dirname(destination), { recursive: true });
                     if (existsSync(destination)) {
                         result.skipped++;
                         logger.debug('DownloadService', 'Skipping existing file', {
@@ -113,7 +115,8 @@ class DownloadService {
                             await this.recordViaMpv(track.videoId, tempSource);
                         }
                     }
-                    await this.convertAudio(tempSource, destination, format);
+                    const hasCover = await this.downloadCoverArt(track.videoId, tempCover);
+                    await this.convertAudio(tempSource, destination, format, track, hasCover ? tempCover : undefined);
                     result.downloaded++;
                     logger.info('DownloadService', 'Track download complete', {
                         videoId: track.videoId,
@@ -134,6 +137,9 @@ class DownloadService {
                     if (existsSync(tempSource)) {
                         unlinkSync(tempSource);
                     }
+                    if (existsSync(tempCover)) {
+                        unlinkSync(tempCover);
+                    }
                 }
             }
             return result;
@@ -155,8 +161,11 @@ class DownloadService {
     }
     getDestinationPath(track, directory, format) {
         const artist = track.artists[0]?.name ?? 'Unknown Artist';
-        const baseName = this.sanitizeFilename(`${artist} - ${track.title}`);
-        return path.join(directory, `${baseName}.${format}`);
+        const album = track.album?.name ?? 'Singles';
+        const artistDir = this.sanitizeFilename(artist) || 'Unknown Artist';
+        const albumDir = this.sanitizeFilename(album) || 'Singles';
+        const fileName = this.sanitizeFilename(track.title) || track.videoId;
+        return path.join(directory, artistDir, albumDir, `${fileName}.${format}`);
     }
     sanitizeFilename(value) {
         return value.replace(/[<>:"/\\|?*\u0000-\u001F]/g, '_').trim();
@@ -186,32 +195,52 @@ class DownloadService {
             throw new Error('ffmpeg is required for downloads. Install ffmpeg and ensure it is available in PATH.');
         }
     }
-    async convertAudio(sourcePath, destinationPath, format) {
+    async convertAudio(sourcePath, destinationPath, format, track, coverPath) {
+        const metadataArgs = this.buildMetadataArgs(track);
         if (format === 'mp3') {
-            await this.runFfmpeg([
-                '-y',
-                '-i',
-                sourcePath,
-                '-vn',
-                '-codec:a',
-                'libmp3lame',
-                '-q:a',
-                '2',
-                destinationPath,
-            ]);
+            const args = ['-y', '-i', sourcePath];
+            if (coverPath) {
+                args.push('-i', coverPath, '-map', '0:a:0', '-map', '1:v:0');
+            }
+            else {
+                args.push('-map', '0:a:0', '-vn');
+            }
+            args.push('-codec:a', 'libmp3lame', '-q:a', '2', ...metadataArgs);
+            if (coverPath) {
+                args.push('-codec:v', 'mjpeg', '-disposition:v:0', 'attached_pic', '-metadata:s:v', 'title=Album cover', '-metadata:s:v', 'comment=Cover (front)');
+            }
+            args.push(destinationPath);
+            await this.runFfmpeg(args);
             return;
         }
-        await this.runFfmpeg([
-            '-y',
-            '-i',
-            sourcePath,
-            '-vn',
-            '-codec:a',
-            'aac',
-            '-b:a',
-            '192k',
-            destinationPath,
-        ]);
+        const args = ['-y', '-i', sourcePath];
+        if (coverPath) {
+            args.push('-i', coverPath, '-map', '0:a:0', '-map', '1:v:0');
+        }
+        else {
+            args.push('-map', '0:a:0', '-vn');
+        }
+        args.push('-codec:a', 'aac', '-b:a', '192k', ...metadataArgs);
+        if (coverPath) {
+            args.push('-codec:v', 'mjpeg', '-disposition:v:0', 'attached_pic');
+        }
+        args.push(destinationPath);
+        await this.runFfmpeg(args);
+    }
+    buildMetadataArgs(track) {
+        const artist = track.artists
+            .map(row => row.name)
+            .filter(Boolean)
+            .join(', ') || 'Unknown Artist';
+        const album = track.album?.name || 'Singles';
+        return [
+            '-metadata',
+            `title=${track.title}`,
+            '-metadata',
+            `artist=${artist}`,
+            '-metadata',
+            `album=${album}`,
+        ];
     }
     async runFfmpeg(args) {
         await new Promise((resolve, reject) => {
@@ -264,6 +293,28 @@ class DownloadService {
             });
         });
     }
+    async downloadCoverArt(videoId, outputPath) {
+        const candidates = [
+            `https://i.ytimg.com/vi/${videoId}/maxresdefault.jpg`,
+            `https://i.ytimg.com/vi/${videoId}/hqdefault.jpg`,
+        ];
+        for (const url of candidates) {
+            try {
+                const response = await fetch(url);
+                if (!response.ok)
+                    continue;
+                const image = Buffer.from(await response.arrayBuffer());
+                if (image.length === 0)
+                    continue;
+                writeFileSync(outputPath, image);
+                return true;
+            }
+            catch {
+                continue;
+            }
+        }
+        return false;
+    }
     async recordViaMpv(videoId, outputPath) {
         const watchUrl = `https://www.youtube.com/watch?v=${videoId}`;
         await new Promise((resolve, reject) => {

package/package.json

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

package/readme.md

@@ -25,6 +25,8 @@ A powerful Terminal User Interface (TUI) music player for YouTube Music
 - 🔌 **Plugin System** - Extend functionality with plugins
 - ⌨️ **Keyboard-Driven** - Efficient vim-style navigation
 - 🖥️ **Headless Mode** - Run without TUI for scripting
+- 💾 **Downloads** - Save tracks/playlists/artists with `Shift+D`
+- 🏷️ **Metadata Tagging** - Auto-tag title/artist/album with optional cover art
 
 ## Prerequisites
 
@@ -194,6 +196,12 @@ youtube-music-cli play dQw4w9WgXcQ --shuffle
 | `Enter`   | Select    |
 | `Esc`     | Back      |
 
+### Downloads
+
+| Key       | Action                                                  |
+| --------- | ------------------------------------------------------- |
+| `Shift+D` | Download selected song/artist/playlist or playlist view |
+
 ## Plugins
 
 Extend youtube-music-cli with plugins!
@@ -259,7 +267,10 @@ Config is stored in `~/.youtube-music-cli/config.json`:
 	"volume": 70,
 	"shuffle": false,
 	"repeat": "off",
-	"streamQuality": "high"
+	"streamQuality": "high",
+	"downloadsEnabled": false,
+	"downloadDirectory": "D:/Music/youtube-music-cli",
+	"downloadFormat": "mp3"
 }
 ```
 
@@ -271,6 +282,15 @@ Config is stored in `~/.youtube-music-cli/config.json`:
 | `medium` | 128kbps - Balanced      |
 | `high`   | 256kbps+ - Best quality |
 
+### Download Settings
+
+- Enable/disable downloads in **Settings** (`,`).
+- Set your download directory in **Settings → Download Folder**.
+- Choose format in **Settings → Download Format** (`mp3` or `m4a`).
+- Downloads are saved as:
+  - `<downloadDirectory>/<artist>/<album>/<title>.mp3` (or `.m4a`)
+- MP3/M4A files are tagged with metadata (`title`, `artist`, `album`) and include cover art when available.
+
 ## Troubleshooting
 
 ### mpv not found
@@ -350,3 +370,11 @@ MIT © [Involvex](https://github.com/involvex)
 Made with ❤️ for music lovers
 
 </div>
+
+## Supporting
+
+**[☕ Buymeacoffee](https://buymeacoffee.com/involvex)**
+
+**[🪙 Paypal](https://paypal.me/involvex)**
+
+**⌨️ [Github Sponsors](https://github.com/sponsors/involvex)**