YoutubeDLSharp 1.1.1

dotnet add package YoutubeDLSharp --version 1.1.1                
NuGet\Install-Package YoutubeDLSharp -Version 1.1.1                
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="YoutubeDLSharp" Version="1.1.1" />                
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add YoutubeDLSharp --version 1.1.1                
#r "nuget: YoutubeDLSharp, 1.1.1"                
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install YoutubeDLSharp as a Cake Addin
#addin nuget:?package=YoutubeDLSharp&version=1.1.1

// Install YoutubeDLSharp as a Cake Tool
#tool nuget:?package=YoutubeDLSharp&version=1.1.1                

YoutubeDLSharp

Build status

A simple .NET wrapper library for youtube-dl and yt-dlp.

For yt-dlp For youtube-dl
Versions >= v.1.0 Versions v.0.x
Nuget NuGet

What is it?

YoutubeDLSharp is a wrapper for the popular command-line video downloaders youtube-dl and yt-dlp. It allows you to use the extensive features of youtube-dl/ yt-dlp in a .NET project. For more about the features of youtube-dl/ yt-dlp, supported websites and anything else, visit their project pages at http://ytdl-org.github.io/youtube-dl/ and https://github.com/yt-dlp/yt-dlp.

How do I install it?

First, add the package from NuGet:

PM> Install-Package YoutubeDLSharp

Next, you would want to have the binaries for yt-dlp and FFmpeg available. If you don't have them set up already, you can either...

  • ...download them from their respective download pages manually: [yt-dlp Download] [FFmpeg Download]
  • ...use the built-in download methods:
    await YoutubeDLSharp.Utils.DownloadYtDlp();
    await YoutubeDLSharp.Utils.DownloadFFmpeg();
    

How do I use it?

There are two ways to use YoutubeDLSharp: the class YoutubeDL provides high level methods for downloading and converting videos while the class YoutubeDLProcess allows directer and flexibler access to the youtube-dl process.

Using the YoutubeDL class

In the simplest case, initializing the downloader and downloading a video can be achieved like this:

var ytdl = new YoutubeDL();
// set the path of yt-dlp and FFmpeg if they're not in PATH or current directory
ytdl.YoutubeDLPath = "path\\to\\yt-dlp.exe";
ytdl.FFmpegPath = "path\\to\\ffmpeg.exe";
// optional: set a different download folder
ytdl.OutputFolder = "some\\directory\\for\\video\\downloads";
// download a video
var res = await ytdl.RunVideoDownload("https://www.youtube.com/watch?v=bq9ghmgqoyc");
// the path of the downloaded file
string path = res.Data;

Instead of only downloading a video, you can also directly extract the audio track ...

var res = await ytdl.RunAudioDownload(
    "https://www.youtube.com/watch?v=QUQsqBqxoR4",
    AudioConversionFormat.Mp3
);

... or selectively download videos from a playlist:

var res = await ytdl.RunVideoPlaylistDownload(
    "https://www.youtube.com/playlist?list=PLPfak9ofGSn9sWgKrHrXrxQXXxwhCblaT",
    start: 52, end: 76
);

All of the above methods also allow you to track the download progress or cancel an ongoing download:

// a progress handler with a callback that updates a progress bar
var progress = new Progress<DownloadProgress>(p => progressBar.Value = p.Progress);
// a cancellation token source used for cancelling the download
// use `cts.Cancel();` to perform cancellation
var cts = new CancellationTokenSource();
// ...
await ytdl.RunVideoDownload("https://www.youtube.com/watch?v=_QdPW8JrYzQ",
                            progress: progress, ct: cts.Token);

As youtube-dl also allows you to extract extensive metadata for videos, you can also fetch these (without downloading the video):

var res = await ytdl.RunVideoDataFetch("https://www.youtube.com/watch?v=_QdPW8JrYzQ");
// get some video information
VideoData video = res.Data;
string title = video.Title;
string uploader = video.Uploader;
long? views = video.ViewCount;
// all available download formats
FormatData[] formats = video.Formats;
// ...

This intro does not show all available options. Refer to the method documentations for more.

The project includes a demo WPF desktop app under WpfDemoApp that uses the YoutubeDL class.

Working with options

YoutubeDLSharp uses the OptionSet class to model youtube-dl/ yt-dlp options. The names of the option properties correspond to the names of youtube-dl, so defining a set of options can look like this:

var options = new OptionSet()
{
    NoContinue = true,
    RestrictFilenames = true,
    Format = "best",
    RecodeVideo = VideoRecodeFormat.Mp4,
    Exec = "echo {}"
}

Some options of yt-dlp can be set multiple times. This is reflected in YoutubeDLSharp by passing an array of values to the corresponding option properties:

var options = new OptionSet()
{
    PostprocessorArgs = new[]
    {
        "ffmpeg:-vcodec h264_nvenc",
        "ffmpeg_i1:-hwaccel cuda -hwaccel_output_format cuda"
    }
};

OptionSet instances can be passed to many YoutubeDL methods to override the default behaviour:

var options = new OptionSet()
{
    NoContinue = true,
    RestrictFilenames = true
}
var ytdl = new YoutubeDL();
var res = await ytdl.RunVideoDownload(
    "https://www.youtube.com/watch?v=bq9ghmgqoyc",
    overrideOptions: options
);

Alternatively, RunWithOptions() can be used to directly run youtube-dl/ yt-dlp with a given OptionSet:

var ytdl = new YoutubeDL();
var res = await ytdl.WithOptions("<YOUR_URL>", options);

For documentation of all options supported by yt-dlp and their effects, visit https://github.com/yt-dlp/yt-dlp#usage-and-options.

Additionally, YoutubeDLSharp allows you to pass custom options to the downloader program. This is especially useful when a forked/ modified version of youtube-dl is used. Custom can be specified like this:

// add
options.AddCustomOption<string>("--my-custom-option", "value");
// set
options.SetCustomOption<string>("--my-custom-option", "new value");

YoutubeDLProcess

To start a youtube-dl/ yt-dlp process directly with the defined options, you can also use the low-level YoutubeDLProcess class, giving you more control over the process:

var ytdlProc = new YoutubeDLProcess();
// capture the standard output and error output
ytdlProc.OutputReceived += (o, e) => Console.WriteLine(e.Data);
ytdlProc.ErrorReceived += (o, e) => Console.WriteLine("ERROR: " + e.Data);
// start running
string[] urls = new[] { "https://github.com/ytdl-org/youtube-dl#options" };
await ytdlProc.RunAsync(urls, options);

Loading/ Saving configuration

You can persist a youtube-dl/ yt-dlp configuration to a file and reload it:

// Save to file
var saveOptions = new OptionSet();
saveOptions.WriteConfigFile("path\\to\\file");

// Reload configuration
OptionSet loadOptions = OptionSet.LoadConfigFile("path\\to\\file");

The file format is compatible with the format used by youtube-dl/ yt-dlp itself. For more, read https://github.com/yt-dlp/yt-dlp#configuration.

Issues & Contributing

You are very welcome to contribute by reporting issues, fixing bugs or resolving inconsistencies to youtube-dl/ yt-dlp. If you want to contribute a new feature to the library, please open an issue with your suggestion before starting to implement it.

All issues related to downloading specific videos, support for websites or downloading/ conversion features should better be reported to https://github.com/yt-dlp/yt-dlp/issues.

Version History

See Changelog.

License

This project is licensed under BSD-3-Clause license.

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 is compatible.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 was computed. 
.NET Framework net45 is compatible.  net451 was computed.  net452 was computed.  net46 was computed.  net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (2)

Showing the top 2 NuGet packages that depend on YoutubeDLSharp:

Package Downloads
Scraper.Net.YoutubeDl

Package Description

Orobouros

A fully-featured and modular online scraper tool. Yes we know the name is spelled wrong. Icon Credit: Hyliian @ DeviantArt

GitHub repositories (1)

Showing the top 1 popular GitHub repositories that depend on YoutubeDLSharp:

Repository Stars
Bluegrams/Vividl
Modern Windows GUI for youtube-dl/ yt-dlp
Version Downloads Last updated
1.1.1 7,750 7/28/2024
1.1.0 5,793 1/6/2024
1.0.0 4,663 7/1/2023
1.0.0-beta6 605 4/8/2023
1.0.0-beta5 174 4/2/2023
1.0.0-beta4 642 3/5/2023
1.0.0-beta3 654 1/17/2023
1.0.0-beta2 208 12/28/2022
1.0.0-beta 231 10/31/2022
0.4.3 3,350 11/20/2022
0.4.2 1,591 3/12/2022
0.4.1 909 1/18/2022
0.4.0 789 10/11/2021
0.3.1 2,068 6/6/2021
0.3.0 1,226 9/27/2020
0.2.1 625 5/2/2020
0.2.0 522 3/22/2020
0.1.0 644 1/12/2020