Struct DashDownloader

pub struct DashDownloader {

    pub mpd_url: String,
    pub redirected_url: Url,
    pub output_path: Option<PathBuf>,
    pub verbosity: u8,
    pub muxer_preference: HashMap<String, String>,
    pub concat_preference: HashMap<String, String>,
    pub decryptor_preference: String,
    pub ffmpeg_location: String,
    pub vlc_location: String,
    pub mkvmerge_location: String,
    pub mp4box_location: String,
    pub mp4decrypt_location: String,
    pub shaka_packager_location: String,
    /* private fields */
}

The DashDownloader allows the download of streaming media content from a DASH MPD manifest.

This involves:

• fetching the manifest file
• parsing its XML contents
• identifying the different Periods, potentially filtering out Periods that contain undesired content such as advertising
• selecting for each Period the desired audio and video representations, according to user preferences concerning the audio language, video dimensions and quality settings, and other attributes such as label and role
• downloading all the audio and video segments for each Representation
• concatenating the audio segments and video segments into a stream
• potentially decrypting the audio and video content, if DRM is present
• muxing the audio and video streams to produce a single video file including audio
• concatenating the streams from each Period into a single media container.

This should work with both MPEG-DASH MPD manifests (where the media segments are typically placed in fragmented MP4 or MPEG-2 TS containers) and for WebM-DASH.

Fields

mpd_url: String

redirected_url: Url

output_path: Option<PathBuf>

verbosity: u8

muxer_preference: HashMap<String, String>

concat_preference: HashMap<String, String>

decryptor_preference: String

ffmpeg_location: String

vlc_location: String

mkvmerge_location: String

mp4box_location: String

mp4decrypt_location: String

shaka_packager_location: String

Implementations

impl DashDownloader

The DashDownloader follows the builder pattern to allow various optional arguments concerning the download of DASH media content (preferences concerning bitrate/quality, specifying an HTTP proxy, etc.).

Example

use dash_mpd::fetch::DashDownloader;

let url = "https://storage.googleapis.com/shaka-demo-assets/heliocentrism/heliocentrism.mpd";
match DashDownloader::new(url)
       .worst_quality()
       .download().await
{
   Ok(path) => println!("Downloaded to {path:?}"),
   Err(e) => eprintln!("Download failed: {e}"),
}

pub fn new(mpd_url: &str) -> DashDownloader

Create a DashDownloader for the specified DASH manifest URL mpd_url.

pub fn with_http_client(self, client: HttpClient) -> DashDownloader

Specify the reqwest Client to be used for HTTP requests that download the DASH streaming media content. Allows you to specify a proxy, the user agent, custom request headers, request timeouts, additional root certificates to trust, client identity certificates, etc.

Example

use dash_mpd::fetch::DashDownloader;

let client = reqwest::Client::builder()
     .user_agent("Mozilla/5.0")
     .timeout(Duration::new(30, 0))
     .build()
     .expect("creating HTTP client");
 let url = "https://cloudflarestream.com/31c9291ab41fac05471db4e73aa11717/manifest/video.mpd";
 let out = PathBuf::from(env::temp_dir()).join("cloudflarestream.mp4");
 DashDownloader::new(url)
     .with_http_client(client)
     .download_to(out)

pub fn with_referer(self, referer: String) -> DashDownloader

Specify the value for the Referer HTTP header used in network requests. This value is used when retrieving the MPD manifest, when retrieving video and audio media segments, and when retrieving subtitle data.

pub fn with_authentication( self, username: String, password: String, ) -> DashDownloader

Specify the username and password to use to authenticate network requests for the manifest and media segments.

pub fn with_auth_bearer(self, token: String) -> DashDownloader

Specify the Bearer token to use to authenticate network requests for the manifest and media segments.

pub fn add_progress_observer( self, observer: Arc<dyn ProgressObserver>, ) -> DashDownloader

Add a observer implementing the ProgressObserver trait, that will receive updates concerning the progression of the download (allows implementation of a progress bar, for example).

pub fn best_quality(self) -> DashDownloader

If the DASH manifest specifies several Adaptations with different bitrates (levels of quality), prefer the Adaptation with the highest bitrate (largest output file).

pub fn intermediate_quality(self) -> DashDownloader

If the DASH manifest specifies several Adaptations with different bitrates (levels of quality), prefer the Adaptation with an intermediate bitrate (closest to the median value).

pub fn worst_quality(self) -> DashDownloader

If the DASH manifest specifies several Adaptations with different bitrates (levels of quality), prefer the Adaptation with the lowest bitrate (smallest output file).

pub fn prefer_language(self, lang: String) -> DashDownloader

Specify the preferred language when multiple audio streams with different languages are available. Must be in RFC 5646 format (e.g. “fr” or “en-AU”). If a preference is not specified and multiple audio streams are present, the first one listed in the DASH manifest will be downloaded.

pub fn prefer_roles(self, role_preference: Vec<String>) -> DashDownloader

Specify the preference ordering for Role annotations on AdaptationSet elements. Some DASH streams include multiple AdaptationSets, one annotated “main” and another “alternate”, for example. If role_preference is [“main”, “alternate”] and one of the AdaptationSets is annotated “main”, then we will only download that AdaptationSet. If no role annotations are specified, this preference is ignored. This preference selection is applied before the preferences related to stream quality and video height/width: for example an AdaptationSet with role=alternate will be ignored when a role=main AdaptationSet is present, even if we also specify a quality preference for highest and the role=alternate stream has a higher quality.

pub fn prefer_video_width(self, width: u64) -> DashDownloader

If the DASH manifest specifies several video Adaptations with different resolutions, prefer the Adaptation whose width is closest to the specified width.

pub fn prefer_video_height(self, height: u64) -> DashDownloader

If the DASH manifest specifies several video Adaptations with different resolutions, prefer the Adaptation whose height is closest to the specified height.

pub fn video_only(self) -> DashDownloader

If the media stream has separate audio and video streams, only download the video stream.

pub fn audio_only(self) -> DashDownloader

If the media stream has separate audio and video streams, only download the audio stream.

pub fn keep_video_as<P: Into<PathBuf>>(self, video_path: P) -> DashDownloader

Keep the file containing video at the specified path. If the path already exists, file contents will be overwritten.

pub fn keep_audio_as<P: Into<PathBuf>>(self, audio_path: P) -> DashDownloader

Keep the file containing audio at the specified path. If the path already exists, file contents will be overwritten.

pub fn save_fragments_to<P: Into<PathBuf>>( self, fragment_path: P, ) -> DashDownloader

Save media fragments to the directory fragment_path. The directory will be created if it does not exist.

pub fn add_decryption_key(self, id: String, key: String) -> DashDownloader

Add a key to be used to decrypt MPEG media streams that use Common Encryption (cenc). This function may be called several times to specify multiple kid/key pairs. Decryption uses the external commandline application specified by with_decryptor_preference (either mp4decrypt from Bento4 or shaka-packager, defaulting to mp4decrypt), run as a subprocess.

Arguments

• id - a track ID in decimal or, a 128-bit KID in hexadecimal format (32 hex characters). Examples: “1” or “eb676abbcb345e96bbcf616630f1a3da”.

• key - a 128-bit key in hexadecimal format.

pub fn with_xslt_stylesheet<P: Into<PathBuf>>( self, stylesheet: P, ) -> DashDownloader

Register an XSLT stylesheet that will be applied to the MPD manifest after XLink processing and before deserialization into Rust structs. The stylesheet will be applied to the manifest using the xsltproc commandline tool, which supports XSLT 1.0. If multiple stylesheets are registered, they will be called in sequence in the same order as their registration. If the application of a stylesheet fails, the download will be aborted.

This is an experimental API which may change in future versions of the library.

Arguments

• stylesheet: the path to an XSLT stylesheet.

pub fn minimum_period_duration(self, value: Duration) -> DashDownloader

Don’t download (skip) Periods in the manifest whose duration is less than the specified value.

pub fn fetch_audio(self, value: bool) -> DashDownloader

Parameter value determines whether audio content is downloaded. If disabled, the output media file will either contain only a video track (if fetch_video is true and the manifest includes a video stream), or will be empty.

pub fn fetch_video(self, value: bool) -> DashDownloader

Parameter value determines whether video content is downloaded. If disabled, the output media file will either contain only an audio track (if fetch_audio is true and the manifest includes an audio stream which is separate from the video stream), or will be empty.

pub fn fetch_subtitles(self, value: bool) -> DashDownloader

Specify whether subtitles should be fetched, if they are available. If subtitles are requested and available, they will be downloaded to a file named with the same name as the media output and an appropriate extension (“.vtt”, “.ttml”, “.srt”, etc.).

Arguments

• value: enable or disable the retrieval of subtitles.

pub fn concatenate_periods(self, value: bool) -> DashDownloader

For multi-Period manifests, parameter value determines whether the content of multiple Periods is concatenated into a single output file where their resolutions, frame rate and aspect ratios are compatible, or kept in individual files.

pub fn without_content_type_checks(self) -> DashDownloader

Don’t check that the content-type of downloaded segments corresponds to audio or video content (may be necessary with poorly configured HTTP servers).

pub fn content_type_checks(self, value: bool) -> DashDownloader

Specify whether to check that the content-type of downloaded segments corresponds to audio or video content (this may need to be set to false with poorly configured HTTP servers).

pub fn conformity_checks(self, value: bool) -> DashDownloader

Specify whether to run various conformity checks on the content of the DASH manifest before downloading media segments.

pub fn use_index_range(self, value: bool) -> DashDownloader

Specify whether the use the sidx/Cue index for SegmentBase@indexRange addressing.

If set to true (the default value), downloads of media whose manifest uses SegmentBase@indexRange addressing will retrieve the index information (currently only sidx information used in ISOBMFF/MP4 containers; Cue information for WebM containers is currently not supported) with a byte range request, then retrieve and concatenate the different bytes ranges indicated in the index. This is the download method used by most DASH players (set-top box and browser-based). It avoids downloading the content identified by the BaseURL as a very large chunk, which can fill up RAM and may be banned by certain content servers.

If set to false, the BaseURL content will be downloaded as a single large chunk. This may be more robust on certain content streams that have been encoded in a manner which is not suitable for byte range retrieval.

pub fn fragment_retry_count(self, count: u32) -> DashDownloader

The upper limit on the number of times to attempt to fetch a media segment, even in the presence of network errors. Transient network errors (such as timeouts) do not count towards this limit.

pub fn max_error_count(self, count: u32) -> DashDownloader

The upper limit on the number of non-transient network errors encountered for this download before we abort the download. Transient network errors such as an HTTP 408 “request timeout” are retried automatically with an exponential backoff mechanism, and do not count towards this upper limit. The default is to fail after 30 non-transient network errors over the whole download.

pub fn sleep_between_requests(self, seconds: u8) -> DashDownloader

Specify a number of seconds to sleep between network requests (default 0).

pub fn allow_live_streams(self, value: bool) -> DashDownloader

Specify whether to attempt to download from a “live” stream, or dynamic DASH manifest. Default is false.

Downloading from a genuinely live stream won’t work well, because this library doesn’t implement the clock-related throttling needed to only download media segments when they become available. However, some media sources publish pseudo-live streams where all media segments are in fact available, which we will be able to download. You might also have some success in combination with the sleep_between_requests() method.

You may also need to force a duration for the live stream using method force_duration(), because live streams often don’t specify a duration.

pub fn force_duration(self, seconds: f64) -> DashDownloader

Specify the number of seconds to capture from the media stream, overriding the duration specified in the DASH manifest. This is mostly useful for live streams, for which the duration is often not specified. It can also be used to capture only the first part of a normal (static/on-demand) media stream.

pub fn with_rate_limit(self, bps: u64) -> DashDownloader

A maximal limit on the network bandwidth consumed to download media segments, expressed in octets (bytes) per second. No limit on bandwidth if set to zero (the default value). Limiting bandwidth below 50kB/s is not recommended, as the downloader may fail to respect this limit.

pub fn verbosity(self, level: u8) -> DashDownloader

Set the verbosity level of the download process.

Arguments

• Level - an integer specifying the verbosity level.

• 0: no information is printed
• 1: basic information on the number of Periods and bandwidth of selected representations
• 2: information above + segment addressing mode
• 3 or larger: information above + size of each downloaded segment

pub fn record_metainformation(self, record: bool) -> DashDownloader

Specify whether to record metainformation concerning the media content (origin URL, title, source and copyright metainformation) as extended attributes in the output file, assuming this information is present in the DASH manifest.

pub fn with_muxer_preference( self, container: &str, ordering: &str, ) -> DashDownloader

When muxing audio and video streams to a container of type container, try muxing applications following the order given by ordering.

This function may be called multiple times to specify the ordering for different container types. If called more than once for the same container type, the ordering specified in the last call is retained.

Arguments

• container: the container type (e.g. “mp4”, “mkv”, “avi”)
• ordering: the comma-separated order of preference for trying muxing applications (e.g. “ffmpeg,vlc,mp4box”)

Example

let out = DashDownloader::new(url)
     .with_muxer_preference("mkv", "ffmpeg")
     .download_to("wonderful.mkv")
     .await?;

pub fn with_concat_preference( self, container: &str, ordering: &str, ) -> DashDownloader

When concatenating streams from a multi-period manifest to a container of type container, try concat helper applications following the order given by ordering.

This function may be called multiple times to specify the ordering for different container types. If called more than once for the same container type, the ordering specified in the last call is retained.

Arguments

• container: the container type (e.g. “mp4”, “mkv”, “avi”)
• ordering: the comma-separated order of preference for trying concat helper applications. Valid possibilities are “ffmpeg” (the ffmpeg concat filter, slow), “ffmpegdemuxer” (the ffmpeg concat demuxer, fast but less robust), “mkvmerge” (fast but not robust), and “mp4box”.

Example

let out = DashDownloader::new(url)
     .with_concat_preference("mkv", "ffmpeg,mkvmerge")
     .download_to("wonderful.mkv")
     .await?;

pub fn with_decryptor_preference(self, decryption_tool: &str) -> DashDownloader

Specify the commandline application to be used to decrypt media which has been enriched with ContentProtection (DRM).

Arguments

• decryption_tool: either “mp4decrypt” or “shaka”

pub fn with_ffmpeg(self, ffmpeg_path: &str) -> DashDownloader

Specify the location of the ffmpeg application, if not located in PATH.

Arguments

• ffmpeg_path: the path to the ffmpeg application. If it does not specify an absolute path, the PATH environment variable will be searched in a platform-specific way (implemented in std::process::Command).

Example

#[cfg(target_os = "unix")]
let ddl = ddl.with_ffmpeg("/opt/ffmpeg-next/bin/ffmpeg");

pub fn with_vlc(self, vlc_path: &str) -> DashDownloader

Specify the location of the VLC application, if not located in PATH.

Arguments

• vlc_path: the path to the VLC application. If it does not specify an absolute path, the PATH environment variable will be searched in a platform-specific way (implemented in std::process::Command).

Example

#[cfg(target_os = "windows")]
let ddl = ddl.with_vlc("C:/Program Files/VideoLAN/VLC/vlc.exe");

pub fn with_mkvmerge(self, path: &str) -> DashDownloader

Specify the location of the mkvmerge application, if not located in PATH.

Arguments

• path: the path to the mkvmerge application. If it does not specify an absolute path, the PATH environment variable will be searched in a platform-specific way (implemented in std::process::Command).

pub fn with_mp4box(self, path: &str) -> DashDownloader

Specify the location of the MP4Box application, if not located in PATH.

Arguments

• path: the path to the MP4Box application. If it does not specify an absolute path, the PATH environment variable will be searched in a platform-specific way (implemented in std::process::Command).

pub fn with_mp4decrypt(self, path: &str) -> DashDownloader

Specify the location of the Bento4 mp4decrypt application, if not located in PATH.

Arguments

• path: the path to the mp4decrypt application. If it does not specify an absolute path, the PATH environment variable will be searched in a platform-specific way (implemented in std::process::Command).

pub fn with_shaka_packager(self, path: &str) -> DashDownloader

Specify the location of the shaka-packager application, if not located in PATH.

Arguments

• path: the path to the shaka-packager application. If it does not specify an absolute path, the PATH environment variable will be searched in a platform-specific way (implemented in std::process::Command).

pub async fn download_to<P: Into<PathBuf>>( self, out: P, ) -> Result<PathBuf, DashMpdError>

Download DASH streaming media content to the file named by out. If the output file out already exists, its content will be overwritten.

Note that the media container format used when muxing audio and video streams depends on the filename extension of the path out. If the filename extension is .mp4, an MPEG-4 container will be used; if it is .mkv a Matroska container will be used, for .webm a WebM container (specific type of Matroska) will be used, and otherwise the heuristics implemented by the selected muxer (by default ffmpeg) will apply (e.g. an .avi extension will generate an AVI container).

pub async fn download(self) -> Result<PathBuf, DashMpdError>

Download DASH streaming media content to a file in the current working directory and return the corresponding PathBuf.

The name of the output file is derived from the manifest URL. The output file will be overwritten if it already exists. The downloaded media will be placed in an MPEG-4 container. To select another media container, see the download_to function.