Ytdlp.NET 1.2.1

Ytdlp.NET

Ytdlp.NET is a fluent, strongly-typed .NET wrapper around the powerful yt-dlp command-line tool. It provides an intuitive and customizable interface to download videos, extract audio, retrieve metadata, and process media from YouTube and hundreds of other supported platforms.

🚀 Features

• Fluent API: Easily construct yt-dlp commands with chainable methods.
• Progress & Events: Real-time progress tracking, completion, and error callbacks.
• Format Listing: Retrieve and parse all available formats for any video.
• Batch Downloads: Download multiple videos with sequential or parallel execution.
• Custom Command Injection: Use AddCustomCommand to include advanced or new options.
• Validated Options: Rejects invalid yt-dlp commands with a built-in option whitelist.
• Cross-Platform: Works on Windows, macOS, and Linux (where yt-dlp is supported).
• Output Templates: Customize naming patterns with standard yt-dlp placeholders.

📦 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.

✨ Basic Usage

🔽 Download a Single Video

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

var ytdlp = new Ytdlp("yt-dlp", new ConsoleLogger());

await ytdlp
    .SetFormat("best")
    .SetOutputFolder("downloads")
    .DownloadThumbnails()
    .ExecuteAsync("https://www.youtube.com/watch?v=RGg-Qx1rL9U");

🎵 Extract Audio + Embed Metadata

await ytdlp
    .ExtractAudio("mp3")
    .EmbedMetadata()
    .SetOutputFolder("audio")
    .ExecuteAsync("https://www.youtube.com/watch?v=RGg-Qx1rL9U");

🧾 List Available Formats

var formats = await ytdlp.GetAvailableFormatsAsync("https://youtube.com/watch?v=abc123");
foreach (var f in formats)
{
    Console.WriteLine($"ID: {f.ID}, Resolution: {f.Resolution}, VCodec: {f.VCodec}");
}

🧪 Get Video Metadata Only

var metadata = await ytdlp.GetVideoMetadataJsonAsync("https://youtube.com/watch?v=abc123");
Console.WriteLine($"Title: {metadata?.Title}, Duration: {metadata?.Duration}");

📦 Batch Download

Sequential (one after another)

await ytdlp
    .SetFormat("best")
    .SetOutputFolder("batch")
    .ExecuteBatchAsync(new[] {
        "https://youtu.be/vid1", "https://youtu.be/vid2"
    });

Parallel (max 3 at a time)

await ytdlp
    .SetFormat("best")
    .SetOutputFolder("batch")
    .ExecuteBatchAsync(new[] {
        "https://youtu.be/vid1", "https://youtu.be/vid2"
    }, maxConcurrency: 3);

⚙️ Configuration & Options

✅ Common Fluent Methods

• .SetFormat(string format)
• .SetOutputFolder(string path)
• .ExtractAudio(string format)
• .EmbedMetadata()
• .DownloadThumbnails()
• .DownloadSubtitles("en")
• .UseCookies("cookies.txt")
• .SetUserAgent("MyApp/1.0")
• .Simulate()
• .DisableAds()
• .SetDownloadTimeout("30")
• .SetAuthentication(username, password)
• .PostProcessFiles("--audio-quality 0")
• .AddCustomCommand(string command)

🧩 Add Custom yt-dlp Option

ytdlp.AddCustomCommand("--sponsorblock-mark all");

Will be validated against internal whitelist. Invalid commands will trigger error logging via ILogger.

📡 Events

ytdlp.OnProgressMessage += (s, msg) => Console.WriteLine($"Progress: {msg}");
ytdlp.OnErrorMessage += (s, err) => Console.WriteLine($"Error: {err}");
ytdlp.OnCommandCompleted += (success, message) => Console.WriteLine($"Finished: {message}");
ytdlp.OnOutputMessage += (s, msg) => Console.WriteLine(msg);
ytdlp.OnPostProcessingComplete += (s, msg) => Console.WriteLine($"Postprocessing: {msg}");

📄 Output Template

You can customize file naming using yt-dlp placeholders:

ytdlp.SetOutputTemplate("%(title)s-%(id)s.%(ext)s");

🧪 Validation & Safety

All AddCustomCommand(...) calls are validated against a known safe set of yt-dlp options, minimizing the risk of malformed or unsupported commands.

To preview what command will run:

string preview = ytdlp.PreviewCommand();
Console.WriteLine(preview);

❗ Error Handling

All exceptions are wrapped in YtdlpException:

try
{
    await ytdlp.ExecuteAsync("https://invalid-url");
}
catch (YtdlpException ex)
{
    Console.WriteLine($"Error: {ex.Message}");
}

🧪 Version Check

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

💡 Tips

• For livestreams, use:

  .DownloadLivestream(true)
  

• To skip already-downloaded videos:

  .SkipDownloaded()
  

🛠 Custom Logging

Implement your own ILogger:

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

🤝 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.