mscfetch 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,37 @@
-# Temporary Holding Version
+# mscfetch
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Interactive terminal music search and batch MP3 downloader.
+
+## Prerequisites
+
+- [Node.js](https://nodejs.org/) (v18+)
+- [FFmpeg](https://ffmpeg.org/download.html) in your system PATH (required for audio conversion)
+
+## Usage
+
+Run directly via `npx` without prior installation:
+
+```bash
+npx mscfetch
+```
+
+Or install globally:
+
+```bash
+npm install -g mscfetch
+mscfetch
+```
+
+## Features
+
+- **Interactive Search**: Search YouTube for songs or artists directly from the command line.
+- **Multi-Search Queue**: Accumulate tracks from different searches into a batch queue before downloading.
+- **High Quality Audio**: Extracts highest available audio quality and converts to MP3 (VBR 0, ~320kbps).
+- **Metadata Tags**: Automatically embeds track title, artist, and metadata into MP3 files.
+- **Concurrent Downloads**: Downloads batch items concurrently with a pool of 2 workers.
+- **Sanitized Filenames**: Automatically cleans illegal Windows/Unix filesystem characters.
+- **Cross-Platform**: Saves all downloads directly to `~/Downloads/MusicDownloads`.
+
+## License
+
+MIT

package/bin/index.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+
+import { runController } from '../src/controllers/appController.js';
+
+runController().catch((error) => {
+  console.error('Fatal error:', error);
+  process.exit(1);
+});

package/index.js

@@ -0,0 +1 @@
+import './bin/index.js';

package/package.json

@@ -1,6 +1,36 @@
 {
   "name": "mscfetch",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Interactive terminal music search and batch MP3 downloader",
+  "main": "./bin/index.js",
+  "bin": {
+    "mscfetch": "bin/index.js",
+    "music-fetch": "bin/index.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "index.js",
+    "README.md"
+  ],
+  "type": "module",
+  "scripts": {
+    "start": "node ./bin/index.js"
+  },
+  "keywords": [
+    "music",
+    "downloader",
+    "mp3",
+    "cli",
+    "yt-dlp",
+    "mscfetch"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "@inquirer/prompts": "^8.7.4",
+    "chalk": "^6.0.1",
+    "ora": "^9.4.1",
+    "yt-dlp-exec": "^1.0.2"
+  }
+}

package/src/config/paths.js

@@ -0,0 +1,11 @@
+import os from 'os';
+import path from 'path';
+import fs from 'fs';
+
+export function getDownloadDir() {
+  const downloadDir = path.join(os.homedir(), 'Downloads', 'MusicDownloads');
+  if (!fs.existsSync(downloadDir)) {
+    fs.mkdirSync(downloadDir, { recursive: true });
+  }
+  return downloadDir;
+}

package/src/controllers/appController.js

@@ -0,0 +1,121 @@
+import { checkFFmpeg } from '../utils/envCheck.js';
+import { getDownloadDir } from '../config/paths.js';
+import { searchTracks } from '../services/searchService.js';
+import { downloadBatch } from '../services/downloadService.js';
+import {
+  displayBanner,
+  promptSearchQuery,
+  promptTrackSelection,
+  promptQueueAction,
+  displayQueueSummary,
+  promptContinue,
+  createSpinner,
+} from '../views/terminalView.js';
+import chalk from 'chalk';
+
+export async function runController() {
+  checkFFmpeg();
+  getDownloadDir();
+
+  displayBanner();
+
+  let queue = [];
+  let isRunning = true;
+
+  while (isRunning) {
+    try {
+      const query = await promptSearchQuery();
+      const spinner = createSpinner('Searching YouTube...').start();
+      let tracks;
+      try {
+        tracks = await searchTracks(query);
+      } finally {
+        spinner.stop();
+      }
+
+      if (!tracks || tracks.length === 0) {
+        console.log(chalk.yellow('No tracks found for your query.'));
+      } else {
+        const selected = await promptTrackSelection(tracks);
+        if (selected.length > 0) {
+          const newTracks = selected.filter(
+            (item) => !queue.some((q) => q.id === item.id || q.url === item.url)
+          );
+          const duplicates = selected.length - newTracks.length;
+          queue.push(...newTracks);
+
+          const dupMsg = duplicates > 0 ? chalk.gray(` (${duplicates} duplicate(s) omitted)`) : '';
+          console.log(
+            chalk.green(`\n✔ Added ${newTracks.length} track(s) to queue.${dupMsg} Total in queue: ${queue.length}`)
+          );
+        } else {
+          console.log(chalk.yellow('\nNo tracks selected from this search.'));
+        }
+      }
+
+      // Queue decision loop: allow searching again, downloading, clearing, or exiting
+      let deciding = true;
+      while (deciding) {
+        displayQueueSummary(queue);
+        const action = await promptQueueAction(queue);
+
+        if (action === 'search') {
+          deciding = false; // loops back to promptSearchQuery
+        } else if (action === 'download') {
+          if (queue.length === 0) {
+            console.log(chalk.yellow('Queue is empty. Search and select tracks first.'));
+            continue;
+          }
+
+          console.log(chalk.cyan(`\nStarting batch download of ${queue.length} track(s)...`));
+          const downloadSpinner = createSpinner('Initializing downloads...').start();
+
+          let completedCount = 0;
+          const total = queue.length;
+          await downloadBatch(queue, (update) => {
+            if (update.status === 'started') {
+              downloadSpinner.text = `Downloading (${update.index + 1}/${total}): ${update.track.title}`;
+            } else if (update.status === 'completed') {
+              completedCount++;
+              if (update.result.success) {
+                downloadSpinner.succeed(chalk.green(`Downloaded: ${update.track.title}`));
+              } else {
+                downloadSpinner.fail(chalk.red(`Failed: ${update.track.title} - ${update.result.error}`));
+              }
+              if (completedCount < total) {
+                downloadSpinner.start('Processing downloads...');
+              }
+            }
+          });
+
+          downloadSpinner.stop();
+          console.log(chalk.green(`\n✔ All downloads saved to: ${getDownloadDir()}`));
+          queue = []; // Reset queue after download
+          deciding = false;
+
+          isRunning = await promptContinue();
+        } else if (action === 'clear') {
+          queue = [];
+          console.log(chalk.yellow('\nQueue cleared.'));
+        } else if (action === 'exit') {
+          deciding = false;
+          isRunning = false;
+        }
+      }
+    } catch (error) {
+      if (error?.name === 'ExitPromptError') {
+        console.log(chalk.gray('\nOperation canceled.'));
+        break;
+      }
+      console.error(chalk.red(`Error: ${error.message}`));
+      try {
+        isRunning = await promptContinue();
+      } catch (promptError) {
+        if (promptError?.name === 'ExitPromptError') break;
+        throw promptError;
+      }
+    }
+  }
+
+  console.log(chalk.magenta('\nThank you for using Music Fetcher CLI!\n'));
+}

package/src/models/track.js

@@ -0,0 +1,24 @@
+export class Track {
+  constructor({ id, title, channel, duration, url, thumbnail }) {
+    this.id = id;
+    this.title = title || 'Unknown Title';
+    this.channel = channel || 'Unknown Channel';
+    this.duration = duration ?? 0;
+    this.url = url;
+    this.thumbnail = thumbnail || null;
+  }
+
+  getFormattedDuration() {
+    if (!this.duration || this.duration === 'N/A') return 'Unknown';
+    if (typeof this.duration === 'string') {
+      if (this.duration.includes(':')) return this.duration;
+      const parsed = Number(this.duration);
+      if (Number.isNaN(parsed)) return 'Unknown';
+      this.duration = parsed;
+    }
+    const totalSeconds = Math.floor(this.duration);
+    const minutes = Math.floor(totalSeconds / 60);
+    const seconds = totalSeconds % 60;
+    return `${minutes}:${seconds.toString().padStart(2, '0')}`;
+  }
+}

package/src/services/downloadService.js

@@ -0,0 +1,85 @@
+import ytDlp from 'yt-dlp-exec';
+import path from 'path';
+import { getDownloadDir } from '../config/paths.js';
+
+export function sanitizeFilename(title) {
+  if (!title || typeof title !== 'string') {
+    return 'untitled_track';
+  }
+  const stripped = title
+    .replace(/[<>:"/\\|?*]/g, '')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .replace(/[. ]+$/, '');
+
+  return stripped.length > 0 ? stripped : 'untitled_track';
+}
+
+export async function downloadTrack(track) {
+  if (!track || !track.url) {
+    return {
+      success: false,
+      title: track?.title || 'Unknown Track',
+      error: 'Missing track URL',
+    };
+  }
+
+  const downloadDir = getDownloadDir();
+  const sanitizedTitle = sanitizeFilename(track.title);
+  const safeTemplateName = sanitizedTitle.replace(/%/g, '%%');
+  const outputTemplate = path.join(downloadDir, `${safeTemplateName}.%(ext)s`);
+
+  try {
+    await ytDlp.exec(track.url, {
+      extractAudio: true,
+      audioFormat: 'mp3',
+      audioQuality: '0', // VBR 0 (~320kbps)
+      output: outputTemplate,
+      embedMetadata: true,
+      noWarnings: true,
+      format: 'bestaudio/best',
+      jsRuntimes: 'node',
+    });
+    return {
+      success: true,
+      title: track.title,
+      path: path.join(downloadDir, `${sanitizedTitle}.mp3`),
+    };
+  } catch (error) {
+    return {
+      success: false,
+      title: track.title,
+      error: error.message,
+    };
+  }
+}
+
+export async function downloadBatch(tracks, onUpdate) {
+  if (!tracks || !Array.isArray(tracks) || tracks.length === 0) {
+    return [];
+  }
+
+  const concurrency = 2;
+  const results = new Array(tracks.length);
+  let currentIndex = 0;
+
+  async function worker() {
+    while (currentIndex < tracks.length) {
+      const idx = currentIndex++;
+      const track = tracks[idx];
+      if (typeof onUpdate === 'function') {
+        onUpdate({ status: 'started', track, index: idx });
+      }
+      const res = await downloadTrack(track);
+      results[idx] = res;
+      if (typeof onUpdate === 'function') {
+        onUpdate({ status: 'completed', track, result: res, index: idx });
+      }
+    }
+  }
+
+  const workerCount = Math.min(concurrency, tracks.length);
+  const workers = Array.from({ length: workerCount }, () => worker());
+  await Promise.all(workers);
+  return results;
+}

package/src/services/searchService.js

@@ -0,0 +1,36 @@
+import ytDlp from 'yt-dlp-exec';
+import { Track } from '../models/track.js';
+
+export async function searchTracks(query, maxResults = 8) {
+  if (!query || typeof query !== 'string' || query.trim().length === 0) {
+    throw new Error('Valid search query required');
+  }
+
+  try {
+    const rawOutput = await ytDlp.exec(`ytsearch${maxResults}:${query.trim()}`, {
+      dumpSingleJson: true,
+      flatPlaylist: true,
+      noWarnings: true,
+      jsRuntimes: 'node',
+    });
+
+    const parsed = JSON.parse(rawOutput.stdout);
+
+    if (!parsed?.entries || !Array.isArray(parsed.entries)) {
+      return [];
+    }
+
+    return parsed.entries
+      .filter((item) => item && (item.id || item.url))
+      .map((item) => new Track({
+        id: item.id,
+        title: item.title,
+        channel: item.uploader || item.channel || 'Unknown Artist',
+        duration: item.duration ?? 0,
+        url: item.url || (item.id ? `https://www.youtube.com/watch?v=${item.id}` : null),
+        thumbnail: item.thumbnails?.[0]?.url || item.thumbnail || null
+      }));
+  } catch (error) {
+    throw new Error(`Search operation failed: ${error.message}`);
+  }
+}

package/src/utils/envCheck.js

@@ -0,0 +1,13 @@
+import { execSync } from 'child_process';
+
+export function checkFFmpeg() {
+  try {
+    execSync('ffmpeg -version', { stdio: 'ignore' });
+    return true;
+  } catch (error) {
+    console.error('Error: FFmpeg is required but was not found in your system PATH.');
+    console.error('Please install FFmpeg and ensure it is added to your PATH.');
+    console.error('Visit https://ffmpeg.org/download.html for installation instructions.');
+    process.exit(1);
+  }
+}

package/src/views/terminalView.js

@@ -0,0 +1,82 @@
+import { input, checkbox, confirm, select } from '@inquirer/prompts';
+import chalk from 'chalk';
+import ora from 'ora';
+
+export async function promptSearchQuery() {
+  return await input({
+    message: chalk.cyan('Enter search query (artist or song):'),
+    validate: (value) => value.trim().length > 0 || 'Query cannot be empty',
+  });
+}
+
+export async function promptTrackSelection(tracks) {
+  const choices = tracks.map((track) => ({
+    name: `${track.title} ${chalk.gray(`(${track.channel} - ${track.getFormattedDuration()})`)}`,
+    value: track,
+    checked: false, // Default to unchecked per user preference
+  }));
+
+  return await checkbox({
+    message: chalk.cyan('Select tracks to add to queue (Space to toggle, Enter to confirm):'),
+    choices,
+  });
+}
+
+export async function promptQueueAction(queue) {
+  const choices = [
+    {
+      name: '➕ Add more songs to queue (search again)',
+      value: 'search',
+    },
+    {
+      name: `⬇️ Download queue (${queue.length} track${queue.length === 1 ? '' : 's'})`,
+      value: 'download',
+      disabled: queue.length === 0 ? '(Queue is empty)' : false,
+    },
+  ];
+
+  if (queue.length > 0) {
+    choices.push({
+      name: '🗑️ Clear queue',
+      value: 'clear',
+    });
+  }
+
+  choices.push({
+    name: '❌ Exit',
+    value: 'exit',
+  });
+
+  return await select({
+    message: chalk.cyan('Queue Menu - choose action:'),
+    choices,
+  });
+}
+
+export function displayQueueSummary(queue) {
+  if (!queue || queue.length === 0) return;
+  console.log(chalk.bold.blue(`\n📋 Current Download Queue (${queue.length}):`));
+  queue.forEach((track, idx) => {
+    console.log(
+      chalk.gray(`  ${idx + 1}. `) +
+        chalk.white(track.title) +
+        chalk.gray(` [${track.channel} - ${track.getFormattedDuration()}]`)
+    );
+  });
+  console.log();
+}
+
+export async function promptContinue() {
+  return await confirm({
+    message: chalk.cyan('Would you like to start another search session?'),
+    default: true,
+  });
+}
+
+export function createSpinner(text) {
+  return ora(text);
+}
+
+export function displayBanner() {
+  console.log(chalk.bold.magenta('\n🎵 Music Fetcher CLI 🎵\n'));
+}