Crate rustube

Expand description

A complete (WIP), and easy to use YouTube downloader.

§Just show me the code!

You just want to download a video, and don’t care about any intermediate steps and any video information?

That’s it:

let url = "https://www.youtube.com/watch?v=Edx9D2yaOGs&ab_channel=CollegeHumor";
let path_to_video = rustube::download_best_quality(url).await?;

And with the blocking feature enabled, you don’t even have to bring your own runtime:

let url = "https://youtu.be/nv2wQvn6Wxc";
let path_to_video = rustube::blocking::download_best_quality(url)?;

§Getting video information

Of course, there’s also the use case, where you want to find out information about a video, like it’s view count, it’s title, or if it is_unplugged_corpus (I mean who of us doesn’t have the desire to find that out).

In these cases, straigt out using download_best_quality won’t serve you well. The VideoDescrambler returned by VideoFetcher::fetch will probaply fit your usecase a lot better:

let id = Id::from_raw("https://www.youtube.com/watch?v=bKldI-XGHIw")?;
let descrambler = VideoFetcher::from_id(id.into_owned())?
   .fetch()
   .await?;

let video_info = descrambler.video_info();
let the_only_truth = &video_info.player_response.tracking_params;

If, after finding out everything about a video, you suddenly decide downloading it is worth it, you, of curse, can keep using the VideoDescrambler for that:

let video = descrambler.descramble()?;
let path_to_video = video.best_quality().unwrap().download().await?;

§Maybe something in between?

So then, what does rustube offer, if I already know, that I want information as well as downloading the video? That’s exactly, what the handy from_* methods on Video are for. Those methods provide easy to use shortcuts with no need for first fetching and then descrambeling the video seperatly:

 let id = Id::from_str("hFZFjoX2cGg")?;
 let video = Video::from_id(id.into_owned()).await?;

 let the_truth_the_whole_truth_and_nothing_but_the_truth = video.video_info();
 let path_to_video = video
    .worst_audio()
    .unwrap()
    .download()
    .await?;

§Choosing something exotic

Till now, you only saw the methods Video::best_quality and Video::worst_audio that magically tell you which video stream you truly desire. But wait, what’s a Stream? If you ever watched a video on YouTube, you probably know that most videos come in different resolutions. So when your internet connection sucks, you may watch the 240p version, instead of the full fleged 4k variant. Each of those resolutions is a Stream. Besides those video Streams, there are often also video-only or audio-only Streams. The methods we used so far are actually just a nice shortcut for making your life easier. But since all these success gurus tell us, we should take the hard road, we will!

For doing so, and to get a little more control over which Stream of a Video to download, we can use Video::streams, the Stream attributes, and Rusts amazing Iterator methods:

let best_quality = video
   .streams()
   .iter()
   .filter(|stream| stream.includes_video_track && stream.includes_audio_track)
   .max_by_key(|stream| stream.quality_label);

Note, that often the video-audio streams have slightly worse quality than the video-only or audio-only streams. This is not a limitation of rustube, but rather a weird design choice of YouTube. So if you want the absolute best quality possible, you will sometimes have to download the best video-only and the best audio-only stream separate. This, however, doesn’t affect all videos.

§Different ways of downloading

As you may already have noticed, all the above examples just call Stream::download, and then get back a path to a video. This path will always point to <VIDEO_ID>.mp4 in the current working directory. But what if you want to have a little more control over where to download the video to?

Stream::download_to_dir and Stream::download_to have your back! Those methods allow you to specify exactly, where the video should be downloaded too.

If you want to do something, while the download is progressing, enable the callback feature and use the then availabe *_with_callback methods, like Stream::download_with_callback.

The Callback struct can take up to one on_progress method and one on_complete method.

For even more control, or when you just want to access the videos URL, have a look at the url field inside of Stream::signature_cipher. This field contains the video URL of that particular Stream. You can, i.e., use this URL to watch the video directly in your browser.

§Feature flags

One of the goals of rustube is to eventually deserialize the complete video information, so even the weirdest niche cases get all the information they need. Another goal is to become the fastest and best performing YouTube downloader out there, while also using little resources. These two goals don’t go hand in hand and require rustube to offer some kind of feature system, which allows users to specify precisely, what they need, so they don’t have to pay the price for stuff they don’t use.

When compiling with no features at all, you will be left with only Id. This is a no_std build. Still, it’s highly recommended to at least enable the regex feature, which will currently break no_std (#476), as well as the std feature. This combination enables Id::from_raw, which is the only way of extracting ids from arbitrary video identifiers, like URLs.

The feature system is still WIP, and currently, you can just opt-in or opt-out of quite huge bundles of functionality.

download: [default] Enables all utilities required for downloading videos.
regex: [default] Enables Id::from_raw, which extracts valid Ids from arbitrary video identifiers like URLs.
serde: [default] Enables serde support for Id (Keep in mind, that this feature does not enable the regex automatically).
std: [default] Enables std usage, which a lot of things depend on.
fetch: [default] Enables VideoFetcher, which can be used to fetch video information.
descramble: [default] Enables VideoDescrambler, which can decrypt video signatures and is necessary to extract the individual streams.
stream: [default] Enables Stream, a representation of a video stream that can be used to download this particular stream.
blocking: Enables the blocking API, which internally creates a tokio runtime for you , so you don’t have to care about it yourself. (Keep in mind, that this feature does not enable any of the other features above automatically)
callback: Enables to add callbacks to downlaods and the Callback struct itself

Re-exports§

pub use tokio;
pub use url;

Modules§

blocking: Blocking wrappers for using rustube in a synchronous context.
video_info: All the types, that hold video information.

Macros§

block: A convenient macro for executing asynchronous code in a synchronous context.

Structs§

Callback: Methods and streams to process either on_progress or on_complete
CallbackArguments: Arguments given either to a on_progress callback or on_progress receiver
Id: A wrapper around a Cow<’a, str> that makes sure the video id, which is contained, always has the correct format.
Microformat
PlayerResponse
Stream: A downloadable video Stream, that contains all the important information.
Video: A YouTube downloader, which allows you to download all available formats and qualities of a YouTube video.
VideoDescrambler: A descrambler used to decrypt the data fetched by VideoFetcher.
VideoDetails
VideoFetcher: A fetcher used to download all necessary data from YouTube, which then could be used to extract video-URLs.
VideoInfo

Enums§

Error: Errors that can occur during the id extraction or the video download process.
OnCompleteType: Type to process on_progress
OnProgressType: Type to process on_progress

Statics§

EMBED_URL_PATTERN: A pattern matching the embedded url of a video (i.e. youtube.com/embed/<ID>).
ID_PATTERN: A pattern matching the id of a video (^[a-zA-Z0-9_-]{11}$).
ID_PATTERNS: A list of possible YouTube video identifier patterns.
SHARE_URL_PATTERN: A pattern matching the embedded url of a video (i.e. youtu.be/<ID>).
WATCH_URL_PATTERN: A pattern matching the watch url of a video (i.e. youtube.com/watch?v=<ID>).

Functions§

download_best_quality: The absolute most straightforward way of downloading a YouTube video in high quality!
download_worst_quality: The absolute most straightforward way of downloading a YouTube video in low quality!

Type Aliases§

IdBuf: Alias for an owned Id.
Result: Alias for Result, with the default error type Error.

Crate rustubeCopy item path