Ytdlp.NET 1.0.0

Ytdlp.NET

A .NET wrapper for the yt-dlp command-line tool, providing a fluent interface to build and execute commands for downloading videos, audio, subtitles, thumbnails, and more from YouTube and other supported platforms. Ytdlp.NET simplifies interaction with yt-dlp by offering a strongly-typed API, progress parsing, and event-based feedback for real-time monitoring.

Features

• Fluent Interface: Build yt-dlp commands with a chainable, intuitive API.
• Progress Tracking: Parse and monitor download progress, errors, and completion events.
• Batch Downloading: Download multiple videos or playlists in a single operation.
• Format Selection: Easily select video/audio formats, resolutions, and other options.
• Event-Driven: Subscribe to events for progress, errors, and command completion.
• Customizable: Support for custom yt-dlp options and advanced configurations.
• Cross-Platform: Compatible with Windows, macOS, and Linux (requires yt-dlp installed).

Prerequisites

• .NET: Requires .NET 8.0 or later.
• yt-dlp: The yt-dlp command-line tool must be installed and accessible in your system�s PATH or specified explicitly.
  • Install yt-dlp via pip:

    pip install -U yt-dlp
    

  • Verify installation:

    yt-dlp --version
    

• FFmpeg (optional): Required for certain operations like merging formats or extracting audio. Install via your package manager or download from FFmpeg.org.

Usage

Basic Example: Download a Single Video

Download a video with the best quality to a specified folder:

using System;
using System.Threading.Tasks;
using YtdlpDotNet;

class Program
{
    static async Task Main()
    {
        var ytdlp = new Ytdlp("yt-dlp", new ConsoleLogger());

        // Subscribe to progress events
        ytdlp.OnProgressMessage += (sender, message) => Console.WriteLine($"Progress: {message}");
        ytdlp.OnCompleteDownload += (sender, message) => Console.WriteLine($"Complete: {message}");
        ytdlp.OnErrorMessage += (sender, message) => Console.WriteLine($"Error: {message}");

        try
        {
            await ytdlp
                .SetFormat("b") // Best quality
                .SetOutputFolder("./downloads")
                .DownloadThumbnails() // Include thumbnails
                .ExecuteAsync("https://www.youtube.com/watch?v=RGg-Qx1rL9U");
        }
        catch (YtdlpException ex)
        {
            Console.WriteLine($"Error: {ex.Message}");
        }
    }

    private class ConsoleLogger : ILogger
    {
        public void Log(LogType type, string message)
        {
            Console.WriteLine($"[{type}] {message}");
        }
    }
}

Example: Batch Download Multiple Videos

Download multiple videos in a batch:

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using YtdlpDotNet;

class Program
{
    static async Task Main()
    {
        var ytdlp = new Ytdlp("yt-dlp", new ConsoleLogger());

        // Subscribe to events
        ytdlp.OnProgressMessage += (sender, message) => Console.WriteLine($"Progress: {message}");
        ytdlp.OnCompleteDownload += (sender, message) => Console.WriteLine($"Complete: {message}");
        ytdlp.OnErrorMessage += (sender, message) => Console.WriteLine($"Error: {message}");

        var videoUrls = new List<string>
        {
            "https://www.youtube.com/watch?v=RGg-Qx1rL9U",
            "https://www.youtube.com/watch?v=iBVxogg5QwE"
        };

        try
        {
            await ytdlp
                .SetFormat("b")
                .SetOutputFolder("./batch_downloads")
                .ExecuteBatchAsync(videoUrls);
        }
        catch (YtdlpException ex)
        {
            Console.WriteLine($"Failed to batch download: {ex.Message}");
        }
    }

    private class ConsoleLogger : ILogger
    {
        public void Log(LogType type, string message)
        {
            Console.WriteLine($"[{type}] {message}");
        }
    }
}

Example: Get Available Formats

Retrieve available formats for a video:

using System;
using System.Threading.Tasks;
using YtdlpDotNet;

class Program
{
    static async Task Main()
    {
        var ytdlp = new Ytdlp("yt-dlp", new ConsoleLogger());

        try
        {
            var formats = await ytdlp.GetAvailableFormatsAsync("https://www.youtube.com/watch?v=RGg-Qx1rL9U");
            foreach (var format in formats)
            {
                Console.WriteLine($"ID: {format.ID}, Extension: {format.Extension}, Resolution: {format.Resolution}, VCodec: {format.VCodec}");
            }
        }
        catch (YtdlpException ex)
        {
            Console.WriteLine($"Error: {ex.Message}");
        }
    }

    private class ConsoleLogger : ILogger
    {
        public void Log(LogType type, string message)
        {
            Console.WriteLine($"[{type}] {message}");
        }
    }
}

Example: Extract Audio with Metadata

Extract audio in MP3 format and embed metadata:

using System;
using System.Threading.Tasks;
using YtdlpDotNet;

class Program
{
    static async Task Main()
    {
        var ytdlp = new Ytdlp("yt-dlp", new ConsoleLogger());

        try
        {
            await ytdlp
                .ExtractAudio("mp3")
                .EmbedMetadata()
                .SetOutputFolder("./audio_downloads")
                .ExecuteAsync("https://www.youtube.com/watch?v=RGg-Qx1rL9U");
        }
        catch (YtdlpException ex)
        {
            Console.WriteLine($"Error: {ex.Message}");
        }
    }

    private class ConsoleLogger : ILogger
    {
        public void Log(LogType type, string message)
        {
            Console.WriteLine($"[{type}] {message}");
        }
    }
}

Configuration

• Custom yt-dlp Path: Specify a custom path to the yt-dlp executable if it�s not in the system PATH:

  var ytdlp = new Ytdlp("/path/to/yt-dlp");
  

• Custom Logger: Implement a custom ILogger for logging:

  public class CustomLogger : ILogger
  {
      public void Log(LogType type, string message)
      {
          // Custom logging logic (e.g., write to file or logging framework)
          Console.WriteLine($"[{type}] {message}");
      }
  }
  var ytdlp = new Ytdlp("yt-dlp", new CustomLogger());
  

• Event Subscriptions: Subscribe to events for real-time feedback:

  ytdlp.OnProgressDownload += (sender, args) => Console.WriteLine($"Progress: {args.Percent}% of {args.Size}");
  ytdlp.OnError += (message) => Console.WriteLine($"Error: {message}");
  ytdlp.OnCommandCompleted += (success, message) => Console.WriteLine($"Command: {message}");
  

Supported yt-dlp Options

Ytdlp.NET supports a wide range of yt-dlp options, including:

• --extract-audio, --audio-format
• --format, --playlist-items
• --write-subs, --write-thumbnail
• --live-from-start, --download-sections
• --user-agent, --cookies, --referer
• And more (see the Ytdlp class for full list).

Use AddCustomCommand for unsupported options, ensuring they are valid yt-dlp commands.

Error Handling

The library throws YtdlpException for errors during execution. Always wrap calls in a try-catch block:

try
{
    await ytdlp.ExecuteAsync("https://www.youtube.com/watch?v=invalid");
}
catch (YtdlpException ex)
{
    Console.WriteLine($"Error: {ex.Message}");
}

Notes

• Thread Safety: The Ytdlp.NET class is not thread-safe. Create a new instance for concurrent operations.
• Performance: Batch downloads are executed sequentially. For parallel downloads, manage multiple Ytdlp.NET instances.
• Version Compatibility: Tested with yt-dlp version 2025.06.30 and later. Run GetVersionAsync to verify:

  string version = await ytdlp.GetVersionAsync();
  Console.WriteLine($"yt-dlp version: {version}");
  

Contributing

Contributions are welcome! Please submit issues or pull requests to the GitHub repository. Ensure code follows the project�s style guidelines and includes unit tests.

License

This project is licensed under the MIT License. See the LICENSE file for details.