VidCore CLI - Simple Video Downloader

A command-line tool for downloading videos from YouTube and other platforms.

Installation

npm install -g vidcore

Usage

Interactive Mode (Recommended)

vidcore

This will prompt you to enter:

1. Video URL
2. Format (mp4 or mp3)
3. Quality (for videos)
4. Output directory

Command Line Mode

# Basic download
vidcore "https://www.youtube.com/watch?v=dQw4w9WgXcQ"

# Specify quality and format
vidcore "https://youtu.be/dQw4w9WgXcQ" --quality 720p --format mp4

# Download audio only
vidcore "https://youtu.be/dQw4w9WgXcQ" --format mp3

# Custom output directory
vidcore "https://youtu.be/dQw4w9WgXcQ" --output ./my-videos

# List available formats
vidcore list-formats "https://youtu.be/dQw4w9WgXcQ"

Options

| Option | Short | Description | Default | |--------|-------|-------------|---------| | --quality | -q | Video quality (best, 1080p, 720p, 480p, 360p) | 720p | | --format | -f | Output format (mp4) | mp4 | | --output | -o | Output directory | ./downloads | | --help | -h | Show help | | | --version | -V | Show version | |

Interactive Mode Walkthrough

1. Run VidCore without arguments:

   vidcore

2. Enter the video URL when prompted:

   🔗 Enter the video URL: https://youtu.be/dQw4w9WgXcQ

3. Select format:

   Available formats:
     1. mp4 (Video)
     2. mp3 (Audio)
      
   📁 Select format (1 for mp4, 2 for mp3): 1

4. Select quality (for video format):

   Available qualities:
     1. best
     2. 1080p
     3. 720p
     4. 480p
     5. 360p
      
   📺 Select quality (1-5): 3

5. Enter output path:

   💾 Enter output path (default: ./downloads): 

6. Confirm download:

   🚀 Start download? (y/n): y

Examples

# Download in highest quality
vidcore "https://youtu.be/dQw4w9WgXcQ" -q best

# Download in 1080p
vidcore "https://youtu.be/dQw4w9WgXcQ" -q 1080p

# Download to specific folder
vidcore "https://youtu.be/dQw4w9WgXcQ" -o ~/Downloads/videos

# Check available formats first
vidcore list-formats "https://youtu.be/dQw4w9WgXcQ"

Supported Platforms

• YouTube (youtube.com, youtu.be)
• Facebook (facebook.com, fb.watch)
• Reddit (reddit.com)
• Instagram (instagram.com)
• TikTok (tiktok.com)
• Twitter/X (twitter.com, x.com)

Important Limitations

Image/GIF Files

• VidCore only downloads videos, not images or GIFs
• If you try to download an image/GIF URL, you'll get an error
• Make sure you're using a video URL, not an image URL

How It Works

VidCore CLI uses yt-dlp to extract video streams directly from various platforms:

1. Direct Download: Downloads videos directly from platform servers
2. Multiple Formats: Supports various quality options
3. Progress Tracking: Shows real-time download progress
4. Metadata Extraction: Retrieves video title, duration, and other information
5. Automatic Cleanup: Removes temporary files after download completion

Automatic Cleanup

VidCore automatically cleans up temporary files created during the download process:

• Partial download files (.part)
• Temporary metadata files
• Cache files
• Fragment files
• Platform-specific temporary files (Facebook, Instagram, TikTok, Twitter/X, Reddit)

This ensures your filesystem stays clean and only contains the final downloaded videos. The cleanup functionality has been enhanced to properly handle duplicate files across all supported platforms, ensuring that only the final downloaded video file is preserved.

Audio Conversion

To convert videos to MP3 format, you need to install FFmpeg:

Windows

# Using Chocolatey
choco install ffmpeg

# Using Scoop
scoop install ffmpeg

macOS

# Using Homebrew
brew install ffmpeg

Linux (Ubuntu/Debian)

sudo apt update
sudo apt install ffmpeg

After installing FFmpeg, you can convert MP4 files to MP3:

ffmpeg -i input.mp4 -q:a 0 -map a output.mp3

Troubleshooting

Video Not Available

• The video might be private or deleted
• Try a different video URL
• Some videos have regional restrictions
• Age-restricted videos require authentication

Download Fails

• Check your internet connection
• Try again in a few minutes (platforms update frequently)
• Use list-formats to see available options
• Some videos require login or have age restrictions

Installation Issues

# Clear npm cache
npm cache clean --force

# Install with verbose logging
npm install -g vidcore --verbose

Platform-Specific Issues

Facebook Videos

• Try using different URL formats:
  • https://www.facebook.com/watch/?v=VIDEO_ID
  • https://fb.watch/SHORT_CODE/
• Some videos require Facebook login
• Update yt-dlp regularly: pip install -U yt-dlp
• Use direct video URLs instead of share links when possible

Reddit Videos

• Make sure the URL points to a video, not an image/GIF
• Remove tracking parameters from URLs
• Some Reddit videos may require login
• Update yt-dlp for the latest platform support

YouTube Videos

• Remove tracking parameters from URLs
• Some videos may be region-restricted
• Age-restricted content may require authentication

Development

# Clone and install dependencies
git clone https://github.com/your-username/vidcore-cli
cd vidcore-cli
npm install

# Install yt-dlp
pip install yt-dlp

# Test locally
node bin/vidcore.js "https://youtu.be/dQw4w9WgXcQ"

# Link for global testing
npm link

License

MIT License - see LICENSE file for details.

Disclaimer

This tool is for personal use only. Please:

1. Respect platform terms of service
2. Comply with copyright laws
3. Only download content you have rights to access
4. Do not use for commercial purposes without permission