nodes/EricRollei-PDF-Tools
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Files
main
EricRollei-PDF-Tools/Docs/yt_dlp_node_complete_guide.md
T

14 KiB
Raw Permalink Blame History

Yt-dlp Downloader Node - Complete Guide

Overview

The Yt-dlp Downloader Node is a powerful ComfyUI node that allows you to download audio and video content from hundreds of websites using the yt-dlp library. It provides a user-friendly interface with advanced features like format selection, audio extraction, subtitle downloads, and automatic file organization.

Features

🎬 Video Downloads

  • Download videos from YouTube, Vimeo, TikTok, Twitter, and hundreds more sites
  • Format selection (best quality, specific resolution, audio-only, etc.)
  • Playlist support with range selection
  • Concurrent fragment downloads for speed
  • Rate limiting to be respectful to servers

🎵 Audio Extraction

  • Extract audio from videos in various formats (MP3, AAC, FLAC, etc.)
  • Configurable audio quality (32-320 kbps)
  • Perfect for music, podcasts, and lectures
  • Automatic format conversion with ffmpeg

📝 Subtitle Support

  • Download subtitles in multiple languages
  • Embed subtitles directly in video files
  • Support for auto-generated captions
  • Organize subtitle files separately

🍪 Authentication

  • Browser cookie extraction (Firefox, Chrome, Edge, Safari)
  • Custom cookie file support
  • Configuration file support
  • Automatic authentication detection

📂 File Organization

  • Automatic organization by file type (videos/, audio/, subtitles/, other/)
  • Channel/uploader-based directory structure
  • Duplicate handling with smart renaming
  • Custom output templates

🔧 Advanced Features

  • Download archive to prevent re-downloads
  • Metadata extraction and embedding
  • Thumbnail downloads
  • Post-processing options
  • Custom command-line options
  • Comprehensive error handling and debugging

Installation Requirements

Required

  • yt-dlp: pip install yt-dlp
  • Python 3.9+: Modern Python version

Optional but Recommended

  • ffmpeg: Required for audio extraction, format merging, and subtitle embedding
  • browser-cookie3: For browser cookie extraction
    • pip install browser-cookie3

Quick Start

Basic Video Download

# In ComfyUI workflow
yt_dlp_node = YtDlpDownloader()
result = yt_dlp_node.execute(
    url_list="https://www.youtube.com/watch?v=example",
    output_dir="./downloads"
)

Audio Extraction

result = yt_dlp_node.execute(
    url_list="https://www.youtube.com/watch?v=example",
    output_dir="./music",
    extract_audio=True,
    audio_format="mp3",
    audio_quality="192"
)

Parameter Reference

Required Parameters

url_list

  • Type: Multiline String
  • Description: URLs to download, one per line
  • Example: 
    https://www.youtube.com/watch?v=example1
https://soundcloud.com/user/track
# Comments starting with # are ignored

output_dir

  • Type: String
  • Default: ./yt-dlp-output
  • Description: Directory where files will be saved
  • Example: ./downloads or C:/MyVideos

Optional Parameters

File Input/Output

batch_file
  • Type: String
  • Default: Empty
  • Description: Path to text file containing URLs (one per line)
  • Example: ./urls.txt
config_path
  • Type: String
  • Default: Empty
  • Description: Path to yt-dlp configuration file
  • Example: ./configs/yt-dlp.conf
use_download_archive
  • Type: Boolean
  • Default: True
  • Description: Use archive file to skip already downloaded content
archive_file
  • Type: String
  • Default: ./yt-dlp-archive.txt
  • Description: Path to download archive file

Authentication

cookie_file
  • Type: String
  • Default: Empty
  • Description: Path to Netscape cookies file
  • Example: ./cookies.txt
use_browser_cookies
  • Type: Boolean
  • Default: True
  • Description: Extract cookies from browser (ignored if cookie file provided)
browser_name
  • Type: Dropdown
  • Options: firefox, chrome, chromium, edge, safari, opera
  • Default: firefox
  • Description: Browser to extract cookies from

Format Selection

format_selector
  • Type: Dropdown
  • Options: best, worst, best[height<=720], best[height<=480], bestvideo+bestaudio, bestvideo, bestaudio, mp4, webm
  • Default: best
  • Description: Video format to download

Common Format Examples:

  • best: Highest quality available
  • worst: Lowest quality (for testing)
  • bestaudio: Audio only
  • best[height<=720]: Max 720p resolution
  • bestvideo+bestaudio: Best video + best audio merged

Audio Extraction

extract_audio
  • Type: Boolean
  • Default: False
  • Description: Extract audio from videos (requires ffmpeg)
audio_format
  • Type: Dropdown
  • Options: mp3, aac, flac, m4a, opus, vorbis, wav
  • Default: mp3
  • Description: Audio format when extracting
audio_quality
  • Type: Dropdown
  • Options: 32, 64, 128, 192, 256, 320
  • Default: 192
  • Description: Audio bitrate in kbps

Subtitles

download_subtitles
  • Type: Boolean
  • Default: False
  • Description: Download subtitle files
subtitle_langs
  • Type: String
  • Default: en
  • Description: Subtitle languages (comma-separated)
  • Examples:
    • en: English only
    • en,es,fr: Multiple languages
    • all: All available languages
embed_subtitles
  • Type: Boolean
  • Default: False
  • Description: Embed subtitles in video files (requires ffmpeg)

File Organization

organize_files
  • Type: Boolean
  • Default: True
  • Description: Sort files into subfolders by type
write_info_json
  • Type: Boolean
  • Default: True
  • Description: Save video metadata to JSON files

Performance

rate_limit
  • Type: String
  • Default: Empty
  • Description: Maximum download speed
  • Examples: 1M (1MB/s), 500K (500KB/s)
concurrent_fragments
  • Type: Dropdown
  • Options: 1, 2, 4, 8
  • Default: 1
  • Description: Number of fragments to download simultaneously

Playlist Options

playlist_start
  • Type: String
  • Default: Empty
  • Description: Start index for playlists
  • Example: 1 (start from first video)
playlist_end
  • Type: String
  • Default: Empty
  • Description: End index for playlists
  • Example: 10 (stop at tenth video)

Advanced

extra_options
  • Type: String
  • Default: Empty
  • Description: Additional yt-dlp command-line options
  • Examples:
    • --write-thumbnail: Download thumbnails
    • --embed-metadata: Embed metadata in files
    • --sleep-interval 2: Sleep 2 seconds between downloads

Output Structure

With file organization enabled, downloads are structured as:

output_dir/
├── ChannelName1/
│   ├── videos/
│   │   ├── video1.mp4
│   │   └── video2.webm
│   ├── audio/
│   │   ├── song1.mp3
│   │   └── song2.flac
│   ├── subtitles/
│   │   ├── video1.en.srt
│   │   └── video1.es.srt
│   └── other/
│       ├── video1.info.json
│       └── thumbnail.jpg
└── ChannelName2/
    └── videos/
        └── video3.mp4

Configuration Files

Pre-made configuration files are available in the configs/ directory:

yt-dlp.conf - General Purpose

  • Good quality settings (max 1080p)
  • Basic metadata and thumbnails
  • Rate limiting enabled
  • Suitable for most use cases

yt-dlp-audio.conf - Audio Optimized

  • Audio extraction enabled
  • High quality MP3 (320K)
  • Optimized for music and podcasts
  • Playlist handling enabled

yt-dlp-hq.conf - High Quality Archival

  • Best available quality
  • All metadata and subtitles
  • Comprehensive archiving
  • Slower but thorough

Usage Examples

Example 1: Basic YouTube Download

result = node.execute(
    url_list="https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    output_dir="./youtube-downloads",
    format_selector="best[height<=720]",
    organize_files=True
)

Example 2: Podcast Audio Extraction

result = node.execute(
    url_list="""
    https://www.youtube.com/watch?v=podcast1
    https://www.youtube.com/watch?v=podcast2
    """,
    output_dir="./podcasts",
    extract_audio=True,
    audio_format="mp3",
    audio_quality="128",
    organize_files=True
)

Example 3: Playlist with Range

result = node.execute(
    url_list="https://www.youtube.com/playlist?list=PLExample",
    output_dir="./playlist-downloads",
    playlist_start="1",
    playlist_end="10",
    format_selector="best[height<=480]",
    rate_limit="500K"
)

Example 4: Multilingual Subtitles

result = node.execute(
    url_list="https://www.youtube.com/watch?v=example",
    output_dir="./videos-with-subs",
    download_subtitles=True,
    subtitle_langs="en,es,fr,de",
    embed_subtitles=True,
    organize_files=True
)

Example 5: Batch File Processing

# Create urls.txt file:
# https://www.youtube.com/watch?v=example1
# https://vimeo.com/example2
# https://soundcloud.com/user/track

result = node.execute(
    url_list="",  # Empty when using batch file
    batch_file="./urls.txt",
    output_dir="./batch-downloads",
    use_download_archive=True
)

Example 6: High Quality with Config

result = node.execute(
    url_list="https://www.youtube.com/watch?v=example",
    output_dir="./hq-downloads",
    config_path="./configs/yt-dlp-hq.conf",
    use_browser_cookies=True,
    browser_name="firefox"
)

Supported Sites

Yt-dlp supports hundreds of websites. Some popular ones include:

Video Platforms

  • YouTube, YouTube Music
  • Vimeo, Dailymotion
  • TikTok, Instagram
  • Twitter/X, Facebook
  • Twitch, Kick

Audio Platforms

  • SoundCloud, Bandcamp
  • Mixcloud, AudioBoom
  • Spotify (limited)

Educational

  • Khan Academy, Coursera
  • edX, Udemy
  • TED Talks

News & Media

  • BBC iPlayer, CNN
  • NPR, PBS
  • Various news outlets

See the full list at: https://github.com/yt-dlp/yt-dlp/blob/master/supportedsites.md

Troubleshooting

Common Issues

"yt-dlp not found"

Solution: Install yt-dlp

pip install yt-dlp

"Audio extraction failed"

Solution: Install ffmpeg

  • Windows: Download from https://ffmpeg.org/
  • macOS: brew install ffmpeg
  • Linux: sudo apt install ffmpeg

"Cookie access failed"

Solution:

  • Use Firefox (doesn't require admin rights)
  • Or export cookies manually to a file
  • Or disable cookie usage for public content

"Download failed with 403/404"

Possible causes:

  • Video is private/deleted
  • Geographic restrictions
  • Authentication required
  • Rate limiting

Solutions:

  • Check if URL is accessible in browser
  • Use browser cookies for authentication
  • Enable rate limiting
  • Try different format selector

"Files not organized"

Solution:

  • Ensure organize_files=True
  • Check if files were actually downloaded
  • Verify write permissions in output directory

Debug Information

The node provides detailed debug output including:

  • Detected target sites
  • Authentication status
  • Command used
  • File organization progress
  • Error details

Check the summary output for debug information when troubleshooting.

Performance Tips

Speed Optimization

  1. Concurrent Fragments: Set to 4 or 8 for faster downloads
  2. Format Selection: Use specific formats instead of "best"
  3. Rate Limiting: Don't set too low unless necessary
  4. Archive File: Enable to skip re-downloads

Quality Optimization

  1. Format Selector: Use bestvideo+bestaudio for best quality
  2. Audio Quality: Set to 320K for best audio
  3. Subtitles: Download all languages with all
  4. Metadata: Enable JSON and embedding

Reliability

  1. Download Archive: Always enable for large batches
  2. Error Handling: Built-in retry and ignore-errors
  3. Browser Cookies: Use for authenticated content
  4. Rate Limiting: Be respectful to servers

Advanced Usage

Custom Format Selectors

# Download only 720p MP4
format_selector="best[height=720][ext=mp4]"

# Audio only, prefer MP3
format_selector="bestaudio[ext=mp3]/bestaudio"

# Best video under 100MB
format_selector="best[filesize<100M]"

Complex Extra Options

extra_options="""
--write-thumbnail
--embed-metadata
--sleep-interval 2
--max-sleep-interval 5
--add-metadata
"""

Custom Output Templates (via config file)

# In yt-dlp.conf
--output "%(uploader)s/%(upload_date)s - %(title)s [%(id)s].%(ext)s"

API Reference

Return Values

The node returns a tuple with:

  1. output_dir (str): Path to output directory
  2. summary (str): Detailed summary with debug info
  3. download_count (int): Number of files downloaded
  4. success (bool): Whether download succeeded

Error Handling

The node includes comprehensive error handling:

  • Timeout protection (10 minutes)
  • Automatic retries (3 attempts)
  • Graceful failure with partial results
  • Detailed error reporting

Best Practices

For Regular Use

  1. Enable download archive
  2. Use file organization
  3. Set reasonable rate limits
  4. Use browser cookies for authenticated content

For Archival

  1. Use high-quality config
  2. Download all subtitles
  3. Save all metadata
  4. Use descriptive output templates

For Audio Content

  1. Use audio extraction
  2. Set appropriate quality
  3. Organize by type
  4. Consider format compatibility

For Batch Processing

  1. Use batch files for large lists
  2. Enable archive to resume interrupted downloads
  3. Use playlist ranges for testing
  4. Monitor disk space

Version History

  • v1.0.0 (January 2025): Initial release
    • Full yt-dlp integration
    • File organization
    • Audio extraction
    • Subtitle support
    • Browser cookie integration
    • Comprehensive error handling

Support

For issues and questions:

  1. Check the debug output in the summary
  2. Verify yt-dlp and ffmpeg installation
  3. Test with simple URLs first
  4. Check yt-dlp documentation for format-specific issues

License

This node is part of the PDF_tools ComfyUI extension and follows the same licensing terms.

Happy downloading! 🎉

Reference in New Issue View Git Blame Copy Permalink