comfyclips 1.0.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 Hamza Imran
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,39 @@
+# ComfyClips
+
+Interactive CLI to download video or audio from social media links (YouTube, Instagram, TikTok, Facebook, X/Twitter). Built on top of [yt-dlp](https://github.com/yt-dlp/yt-dlp).
+
+## Requirements
+
+- Node.js >= 18
+- [ffmpeg](https://ffmpeg.org/) on your PATH — required to merge separate video/audio streams and to extract/convert audio formats. Without it, downloads may fail or fall back to lower quality.
+  - Debian/Ubuntu: `sudo apt-get install ffmpeg`
+  - macOS: `brew install ffmpeg`
+  - Windows: `choco install ffmpeg` (or download from ffmpeg.org and add it to PATH)
+- `yt-dlp` — not required ahead of time. If it isn't found on your PATH, ComfyClips downloads a copy automatically on first run into `~/.comfyclips/bin`.
+
+## Install
+
+```bash
+npm install
+npm link   # exposes the `comfyclips` command globally
+```
+
+## Usage
+
+```bash
+comfyclips
+```
+
+You'll be prompted to:
+1. Select a platform (YouTube, Instagram, TikTok, Facebook, X/Twitter)
+2. Paste the video link
+3. Choose Video or Audio only
+4. Pick a quality (video) or format (audio: mp3/m4a/wav/opus)
+5. Choose the destination folder (created automatically if it doesn't exist)
+
+Progress is shown live in the terminal, and the file is saved using its original title as the filename.
+
+## Notes
+
+- Downloading content you don't own or don't have rights to may violate a platform's Terms of Service or copyright law. Use responsibly.
+- Platform selection is a light sanity check on the URL's domain; actual extraction is handled by yt-dlp regardless of the platform chosen.

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "comfyclips",
+  "version": "1.0.0",
+  "description": "Interactive CLI to download video or audio from social media platforms (YouTube, Instagram, TikTok, Facebook, X/Twitter) via yt-dlp.",
+  "type": "module",
+  "bin": {
+    "comfyclips": "./src/index.js"
+  },
+  "main": "src/index.js",
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "node src/index.js"
+  },
+  "keywords": [
+    "cli",
+    "video-downloader",
+    "yt-dlp",
+    "youtube",
+    "instagram",
+    "tiktok"
+  ],
+  "author": "Hamza Imran",
+  "license": "ISC",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@inquirer/core": "^12.0.0",
+    "boxen": "^8.0.1",
+    "chalk": "^5.3.0",
+    "cli-progress": "^3.12.0",
+    "cli-table3": "^0.6.5",
+    "figlet": "^1.11.4",
+    "inquirer": "^14.1.0",
+    "ora": "^8.1.0",
+    "yt-dlp-wrap-plus": "^2.5.0"
+  },
+  "packageManager": "pnpm@9.15.0+sha512.76e2379760a4328ec4415815bcd6628dee727af3779aaa4c914e3944156c4299921a89f976381ee107d41f12cfa4b66681ca9c718f0668fa0831ed4c6d8ba56c"
+}

package/src/binaries.js

@@ -0,0 +1,46 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import chalk from 'chalk';
+import ora from 'ora';
+import YTDlpWrap from './ytdlp-lib.js';
+
+const CACHE_DIR = path.join(os.homedir(), '.comfyclips', 'bin');
+const YT_DLP_BIN_NAME = os.platform() === 'win32' ? 'yt-dlp.exe' : 'yt-dlp';
+const CACHED_YT_DLP_PATH = path.join(CACHE_DIR, YT_DLP_BIN_NAME);
+
+function commandExists(cmd, versionFlag = '--version') {
+  const result = spawnSync(cmd, [versionFlag], { stdio: 'ignore' });
+  return !result.error && result.status === 0;
+}
+
+export function isFfmpegAvailable() {
+  // ffmpeg uses single-dash flags (-version), unlike most CLIs.
+  return commandExists('ffmpeg', '-version');
+}
+
+export async function resolveYtDlpBinaryPath() {
+  if (commandExists('yt-dlp')) {
+    return 'yt-dlp';
+  }
+
+  if (existsSync(CACHED_YT_DLP_PATH)) {
+    return CACHED_YT_DLP_PATH;
+  }
+
+  console.log(chalk.yellow('yt-dlp was not found on your system.'));
+  const spinner = ora('Downloading yt-dlp binary (one-time setup)...').start();
+  try {
+    mkdirSync(CACHE_DIR, { recursive: true });
+    await YTDlpWrap.downloadFromGithub(CACHED_YT_DLP_PATH);
+    spinner.succeed(`yt-dlp downloaded to ${CACHED_YT_DLP_PATH}`);
+    return CACHED_YT_DLP_PATH;
+  } catch (err) {
+    spinner.fail('Failed to download yt-dlp automatically.');
+    throw new Error(
+      `Could not download yt-dlp: ${err.message}\n` +
+        'Please install it manually (https://github.com/yt-dlp/yt-dlp#installation) and ensure it is on your PATH.'
+    );
+  }
+}

package/src/downloader.js

@@ -0,0 +1,121 @@
+import { mkdirSync } from 'node:fs';
+import path from 'node:path';
+import chalk from 'chalk';
+import cliProgress from 'cli-progress';
+import YTDlpWrap from './ytdlp-lib.js';
+import { printWarning } from './ui.js';
+
+function heightCap(quality) {
+  if (quality === 'best') return '';
+  const height = parseInt(quality, 10);
+  return Number.isNaN(height) ? '' : `[height<=${height}]`;
+}
+
+// Prefer H.264/AAC streams in an mp4 container first — the only combination
+// virtually every player (Windows Media Player, QuickTime, phones, smart TVs)
+// can decode. Only fall back to VP9/AV1+Opus (remuxed into .mp4) when no
+// compatible stream exists at all, since some players choke on that.
+function videoFormatSelector(quality) {
+  const h = heightCap(quality);
+  return [
+    `bestvideo[ext=mp4][vcodec^=avc1]${h}+bestaudio[ext=m4a]`,
+    `bestvideo[ext=mp4]${h}+bestaudio[ext=m4a]`,
+    `best[ext=mp4]${h}`,
+    `bestvideo${h}+bestaudio`,
+    `best${h}`,
+  ].join('/');
+}
+
+export function buildArgs({ url, mode, quality, audioFormat, outputDir, ffmpegAvailable }) {
+  const outputTemplate = path.join(outputDir, '%(title)s.%(ext)s');
+  const args = [url, '-o', outputTemplate, '--no-playlist', '--newline'];
+  const warnings = [];
+
+  if (mode === 'audio') {
+    args.push('-x', '--audio-format', audioFormat, '-f', 'bestaudio/best');
+    if (!ffmpegAvailable) {
+      warnings.push(
+        'ffmpeg was not found — audio extraction may fail or the file may keep its original codec.'
+      );
+    }
+  } else if (ffmpegAvailable) {
+    args.push('-f', videoFormatSelector(quality), '--merge-output-format', 'mp4');
+  } else {
+    const h = heightCap(quality);
+    args.push('-f', `best[ext=mp4]${h}/best${h}`);
+    warnings.push(
+      'ffmpeg was not found — separate video/audio streams cannot be merged, so quality is limited to a single pre-merged format. Install ffmpeg for full quality and best compatibility.'
+    );
+  }
+
+  return { args, warnings };
+}
+
+const DESTINATION_PATTERNS = [/Destination:\s*(.+)$/, /Merging formats into "(.+)"$/];
+
+export async function downloadMedia({
+  binaryPath,
+  url,
+  mode,
+  quality,
+  audioFormat,
+  outputDir,
+  ffmpegAvailable,
+}) {
+  mkdirSync(outputDir, { recursive: true });
+
+  const ytDlpWrap = new YTDlpWrap(binaryPath);
+  const { args, warnings } = buildArgs({
+    url,
+    mode,
+    quality,
+    audioFormat,
+    outputDir,
+    ffmpegAvailable,
+  });
+  warnings.forEach(printWarning);
+
+  const bar = new cliProgress.SingleBar(
+    {
+      format: `${chalk.cyan('{bar}')} {percentage}% | {sizeStr} | {speedStr} | ETA {etaStr}`,
+      barCompleteChar: '█',
+      barIncompleteChar: '░',
+      hideCursor: true,
+      clearOnComplete: false,
+    },
+    cliProgress.Presets.shades_classic
+  );
+  bar.start(100, 0, { sizeStr: '--', speedStr: '--', etaStr: '--' });
+
+  let outputFile;
+  const startedAt = Date.now();
+
+  return new Promise((resolve, reject) => {
+    ytDlpWrap
+      .exec(args)
+      .on('progress', (progress) => {
+        bar.update(progress.percent ?? 0, {
+          sizeStr: progress.totalSize ?? '--',
+          speedStr: progress.currentSpeed ?? '--',
+          etaStr: progress.eta ?? '--',
+        });
+      })
+      .on('ytDlpEvent', (eventType, eventData) => {
+        for (const pattern of DESTINATION_PATTERNS) {
+          const match = eventData.match(pattern);
+          if (match) outputFile = match[1];
+        }
+      })
+      .on('error', (error) => {
+        bar.stop();
+        console.error(chalk.bold.red('✖ Download failed'));
+        reject(error);
+      })
+      .on('close', () => {
+        bar.update(100);
+        bar.stop();
+        console.log(chalk.bold.green('✔ Download finished'));
+        resolve({ outputFile, elapsedSeconds: ((Date.now() - startedAt) / 1000).toFixed(1) });
+      });
+  });
+}

package/src/index.js

@@ -0,0 +1,168 @@
+#!/usr/bin/env node
+import { readFileSync, statSync } from 'node:fs';
+import path from 'node:path';
+import chalk from 'chalk';
+import inquirer from 'inquirer';
+import { isFfmpegAvailable, resolveYtDlpBinaryPath } from './binaries.js';
+import { downloadMedia } from './downloader.js';
+import { PLATFORMS, hostMatchesPlatform } from './platforms.js';
+import boxedSelect from './prompts/boxedSelect.js';
+import { formatBytes, printHeader, printResultTable, printSummaryTable } from './ui.js';
+
+const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+
+const cliArgs = process.argv.slice(2);
+
+if (cliArgs.includes('--version') || cliArgs.includes('-v')) {
+  console.log(pkg.version);
+  process.exit(0);
+}
+
+if (cliArgs.includes('--help') || cliArgs.includes('-h')) {
+  console.log(`
+ComfyClips ${pkg.version}
+${pkg.description}
+
+Usage:
+  comfyclips             Start the interactive downloader
+  comfyclips --version   Print the version number
+  comfyclips --help      Show this help message
+`);
+  process.exit(0);
+}
+
+process.stdin.on('keypress', (_str, key) => {
+  if (key?.name === 'escape') {
+    if (process.stdin.isTTY) process.stdin.setRawMode(false);
+    console.log(chalk.yellow('\nCancelled.'));
+    process.exit(0);
+  }
+});
+
+function isValidUrl(value) {
+  try {
+    new URL(value);
+    return true;
+  } catch {
+    return 'Please enter a valid URL (including https://)';
+  }
+}
+
+async function main() {
+  printHeader();
+
+  const platform = await boxedSelect({
+    message: 'Select a social media platform:',
+    choices: PLATFORMS,
+  });
+  const platformName = PLATFORMS.find((p) => p.value === platform).name;
+
+  const { url } = await inquirer.prompt([
+    {
+      type: 'input',
+      name: 'url',
+      message: 'Paste the video link:',
+      validate: isValidUrl,
+    },
+  ]);
+
+  if (!hostMatchesPlatform(url, platform)) {
+    const { proceedAnyway } = await inquirer.prompt([
+      {
+        type: 'confirm',
+        name: 'proceedAnyway',
+        message: `That link doesn't look like a ${platformName} URL. Continue anyway?`,
+        default: false,
+      },
+    ]);
+    if (!proceedAnyway) {
+      console.log(chalk.yellow('Cancelled.'));
+      return;
+    }
+  }
+
+  const mode = await boxedSelect({
+    message: 'What do you want to download?',
+    choices: [
+      { name: 'Video', value: 'video' },
+      { name: 'Audio only', value: 'audio' },
+    ],
+  });
+
+  let quality = 'best';
+  let audioFormat = 'mp3';
+
+  if (mode === 'video') {
+    quality = await boxedSelect({
+      message: 'Select video quality:',
+      choices: [
+        { name: 'Best available', value: 'best' },
+        { name: 'Up to 1080p', value: '1080p' },
+        { name: 'Up to 720p', value: '720p' },
+        { name: 'Up to 480p', value: '480p' },
+      ],
+    });
+  } else {
+    audioFormat = await boxedSelect({
+      message: 'Select audio format:',
+      choices: ['mp3', 'm4a', 'wav', 'opus'],
+    });
+  }
+
+  const { outputDir } = await inquirer.prompt([
+    {
+      type: 'input',
+      name: 'outputDir',
+      message: 'Where should the file be saved?',
+      default: path.join(process.cwd(), 'downloads'),
+      filter: (value) => path.resolve(value.trim()),
+    },
+  ]);
+
+  printSummaryTable({ platformName, url, mode, quality, audioFormat, outputDir });
+
+  const { confirmDownload } = await inquirer.prompt([
+    {
+      type: 'confirm',
+      name: 'confirmDownload',
+      message: 'Start download?',
+      default: true,
+    },
+  ]);
+
+  if (!confirmDownload) {
+    console.log(chalk.yellow('Cancelled.'));
+    return;
+  }
+
+  try {
+    const binaryPath = await resolveYtDlpBinaryPath();
+    const ffmpegAvailable = isFfmpegAvailable();
+
+    const { outputFile, elapsedSeconds } = await downloadMedia({
+      binaryPath,
+      url,
+      mode,
+      quality,
+      audioFormat,
+      outputDir,
+      ffmpegAvailable,
+    });
+
+    let fileSize = 'Unknown';
+    if (outputFile) {
+      try {
+        fileSize = formatBytes(statSync(outputFile).size);
+      } catch {
+        // File path couldn't be resolved from yt-dlp output; leave as Unknown.
+      }
+    }
+
+    printResultTable({ outputFile, fileSize, elapsedSeconds, outputDir });
+  } catch (err) {
+    console.error(chalk.bold.red(`\n✖ Download failed: ${err.message}`));
+    process.exitCode = 1;
+  }
+}
+
+main();

package/src/platforms.js

@@ -0,0 +1,38 @@
+export const PLATFORMS = [
+  {
+    name: 'YouTube',
+    value: 'youtube',
+    hostPattern: /(^|\.)youtube\.com$|^youtu\.be$/i,
+  },
+  {
+    name: 'Instagram',
+    value: 'instagram',
+    hostPattern: /(^|\.)instagram\.com$/i,
+  },
+  {
+    name: 'TikTok',
+    value: 'tiktok',
+    hostPattern: /(^|\.)tiktok\.com$/i,
+  },
+  {
+    name: 'Facebook',
+    value: 'facebook',
+    hostPattern: /(^|\.)facebook\.com$|^fb\.watch$/i,
+  },
+  {
+    name: 'X / Twitter',
+    value: 'twitter',
+    hostPattern: /(^|\.)twitter\.com$|(^|\.)x\.com$/i,
+  },
+];
+
+export function hostMatchesPlatform(url, platformValue) {
+  const platform = PLATFORMS.find((p) => p.value === platformValue);
+  if (!platform) return true;
+  try {
+    const { hostname } = new URL(url);
+    return platform.hostPattern.test(hostname);
+  } catch {
+    return false;
+  }
+}

package/src/prompts/boxedSelect.js

@@ -0,0 +1,77 @@
+import {
+  createPrompt,
+  useState,
+  useKeypress,
+  usePrefix,
+  makeTheme,
+  isEnterKey,
+  isUpKey,
+  isDownKey,
+} from '@inquirer/core';
+import chalk from 'chalk';
+
+function normalizeChoices(choices) {
+  return choices.map((choice) =>
+    typeof choice === 'object' && choice !== null
+      ? { name: choice.name ?? String(choice.value), value: choice.value }
+      : { name: String(choice), value: choice }
+  );
+}
+
+const POINTER = '❯';
+const BULLET_ACTIVE = '●';
+const BULLET_IDLE = '○';
+
+export default createPrompt((config, done) => {
+  const theme = makeTheme(config.theme);
+  const items = normalizeChoices(config.choices);
+  const [status, setStatus] = useState('idle');
+  const [active, setActive] = useState(0);
+  const prefix = usePrefix({ status, theme });
+
+  useKeypress((key) => {
+    if (isEnterKey(key)) {
+      setStatus('done');
+      done(items[active].value);
+    } else if (isUpKey(key)) {
+      setActive((active - 1 + items.length) % items.length);
+    } else if (isDownKey(key)) {
+      setActive((active + 1) % items.length);
+    }
+  });
+
+  const message = theme.style.message(config.message, status);
+
+  if (status === 'done') {
+    return `${prefix} ${message} ${theme.style.answer(items[active].name)}`;
+  }
+
+  function stripLength(text) {
+    // eslint-disable-next-line no-control-regex
+    return text.replace(/\x1b\[[0-9;]*m/g, '').length;
+  }
+
+  const HEADER = 'Option';
+  const innerWidth = Math.max(HEADER.length, ...items.map((item) => item.name.length + 4));
+
+  const border = (left, fill, right) => `${left}${fill.repeat(innerWidth + 2)}${right}`;
+  const padRow = (raw) => `${raw}${' '.repeat(Math.max(0, innerWidth - stripLength(raw)))}`;
+  const row = (content) => `│ ${padRow(content)} │`;
+
+  const lines = [
+    chalk.gray(border('╭', '─', '╮')),
+    row(chalk.bold(HEADER)),
+    chalk.gray(border('├', '─', '┤')),
+    ...items.map((item, index) => {
+      const isActive = index === active;
+      const bullet = isActive ? chalk.cyan(BULLET_ACTIVE) : chalk.gray(BULLET_IDLE);
+      const pointer = isActive ? chalk.cyan(POINTER) : ' ';
+      const label = isActive ? chalk.cyan.bold(item.name) : chalk.white(item.name);
+      return row(`${pointer} ${bullet} ${label}`);
+    }),
+    chalk.gray(border('╰', '─', '╯')),
+    chalk.dim('  ↑↓ move • enter to select • esc to quit'),
+  ];
+
+  return `${prefix} ${message}\n${lines.join('\n')}`;
+});

package/src/ui.js

@@ -0,0 +1,93 @@
+import boxen from 'boxen';
+import chalk from 'chalk';
+import Table from 'cli-table3';
+import figlet from 'figlet';
+
+const BRAND = chalk.bold.hex('#00d1b2');
+const LABEL = chalk.gray;
+const VALUE = chalk.white;
+
+export function printHeader() {
+  const logo = figlet.textSync('ComfyClips', { font: 'Small Slant' });
+  const title = `${BRAND(logo)}\n${chalk.dim('Social Media Video Downloader')}\n${chalk.dim('Press esc to quit')}`;
+  console.log(
+    boxen(title, {
+      padding: { top: 0, bottom: 0, left: 3, right: 3 },
+      margin: { top: 1, bottom: 1, left: 0, right: 0 },
+      borderStyle: 'round',
+      borderColor: '#00d1b2',
+      textAlignment: 'center',
+    })
+  );
+}
+
+function baseTable() {
+  return new Table({
+    chars: {
+      top: '─',
+      'top-mid': '┬',
+      'top-left': '╭',
+      'top-right': '╮',
+      bottom: '─',
+      'bottom-mid': '┴',
+      'bottom-left': '╰',
+      'bottom-right': '╯',
+      left: '│',
+      'left-mid': '├',
+      mid: '─',
+      'mid-mid': '┼',
+      right: '│',
+      'right-mid': '┤',
+      middle: '│',
+    },
+    style: { head: [], border: ['gray'] },
+  });
+}
+
+function truncate(value, max = 60) {
+  if (typeof value !== 'string' || value.length <= max) return value;
+  return `${value.slice(0, max - 1)}…`;
+}
+
+export function printSummaryTable({ platformName, url, mode, quality, audioFormat, outputDir }) {
+  const table = baseTable();
+  table.push(
+    [LABEL('Platform'), VALUE(platformName)],
+    [LABEL('Link'), VALUE(truncate(url))],
+    [LABEL('Download'), VALUE(mode === 'audio' ? 'Audio only' : 'Video')],
+    mode === 'audio'
+      ? [LABEL('Audio format'), VALUE(audioFormat.toUpperCase())]
+      : [LABEL('Quality'), VALUE(quality === 'best' ? 'Best available' : quality)],
+    [LABEL('Save to'), VALUE(truncate(outputDir))]
+  );
+  console.log(`\n${chalk.bold('Review your selection')}`);
+  console.log(table.toString());
+}
+
+export function printWarning(message) {
+  console.log(chalk.yellow(`⚠ ${message}`));
+}
+
+export function printResultTable({ outputFile, fileSize, elapsedSeconds, outputDir }) {
+  const table = baseTable();
+  table.push(
+    [LABEL('File'), VALUE(truncate(outputFile ?? '(unknown — check destination folder)'))],
+    [LABEL('Size'), VALUE(fileSize)],
+    [LABEL('Time taken'), VALUE(`${elapsedSeconds}s`)],
+    [LABEL('Location'), VALUE(truncate(outputDir))]
+  );
+  console.log(`\n${chalk.bold.green('✔ Download complete')}`);
+  console.log(table.toString());
+}
+
+export function formatBytes(bytes) {
+  if (!bytes || Number.isNaN(bytes)) return 'Unknown';
+  const units = ['B', 'KB', 'MB', 'GB'];
+  let value = bytes;
+  let unitIndex = 0;
+  while (value >= 1024 && unitIndex < units.length - 1) {
+    value /= 1024;
+    unitIndex += 1;
+  }
+  return `${value.toFixed(1)} ${units[unitIndex]}`;
+}

package/src/ytdlp-lib.js

@@ -0,0 +1,8 @@
+import YTDlpWrapModule from 'yt-dlp-wrap-plus';
+
+// yt-dlp-wrap-plus's CJS build sometimes double-wraps its default export
+// (module.default.default instead of module.default). Unwrap defensively.
+const YTDlpWrap =
+  typeof YTDlpWrapModule === 'function' ? YTDlpWrapModule : YTDlpWrapModule.default;
+
+export default YTDlpWrap;