Awesome
YoutubeDLSharp
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 |
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.