Crate rustube[][src]

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);

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.

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)

Re-exports

pub use tokio;
pub use url;

Modules

blockingblocking

Blocking wrappers for using rustube in a synchronous context.

video_infofetch

All the types, that hold video information.

Macros

blockblocking

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

Structs

Callbackcallback

Methods and streams to process either on_progress or on_complete

CallbackArgumentscallback

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.

OnCompleteTypecallback

Type to process on_progress

OnProgressTypecallback

Type to process on_progress

Statics

EMBED_URL_PATTERNregex

A pattern matching the embedded url of a video (i.e. youtube.com/embed/<ID>).

ID_PATTERNregex

A pattern matching the id of a video (^[a-zA-Z0-9_-]{11}$).

ID_PATTERNSregex

A list of possible YouTube video identifier patterns.

SHARE_URL_PATTERNregex

A pattern matching the embedded url of a video (i.e. youtu.be/<ID>).

WATCH_URL_PATTERNregex

A pattern matching the watch url of a video (i.e. youtube.com/watch?v=<ID>).

Functions

download_best_qualitydownload and regex

The absolute most straightforward way of downloading a YouTube video in high quality!

download_worst_qualitydownload and regex

The absolute most straightforward way of downloading a YouTube video in low quality!

Type Definitions

IdBuf

Alias for an owned Id.

Resultstd

Alias for Result, with the default error type Error.