FileDownloader 基类

相关源文件

• youtube_dl/downloader/common.py
• youtube_dl/downloader/dash.py
• youtube_dl/downloader/f4m.py
• youtube_dl/downloader/fragment.py
• youtube_dl/downloader/hls.py
• youtube_dl/downloader/http.py
• youtube_dl/downloader/ism.py
• youtube_dl/downloader/rtmp.py
• youtube_dl/extractor/audioboom.py
• youtube_dl/extractor/karrierevideos.py
• youtube_dl/extractor/radiobremen.py
• youtube_dl/extractor/rtl2.py

FileDownloader 类是 youtube-dl 中所有下载功能的基础。它提供了使用不同协议从各种源下载媒体文件的基本实现。此页面记录了 FileDownloader 基类的架构和功能，该类定义了系统中所有下载器的通用接口和实用方法。

有关特定协议下载器（HTTP、HLS、DASH 等）的信息，请参阅 下载器系统。

概述

FileDownloader 基类是一个抽象类，旨在处理核心下载功能，同时允许在子类中定义特定于协议的实现。它提供了一个统一的媒体文件下载接口，并具有广泛的错误处理、进度报告和文件管理功能。

来源： youtube_dl/downloader/common.py20-406 youtube_dl/downloader/http.py27-362 youtube_dl/downloader/fragment.py22-295 youtube_dl/downloader/hls.py25-216 youtube_dl/downloader/dash.py13-83 youtube_dl/downloader/f4m.py259-438 youtube_dl/downloader/rtmp.py23-216

核心设计

FileDownloader 类采用面向对象的方法，具有必须由子类实现的抽象方法。子类必须实现的关键方法是 real_download，该方法负责从源实际下载内容。

来源： youtube_dl/downloader/common.py339-380

关键参数

FileDownloader 基类接受广泛的参数来控制下载行为。这些参数以字典的形式传递给构造函数。

参数	类型	描述
verbose	bool	向 stdout 打印额外信息
quiet	bool	不向 stdout 打印消息
ratelimit	int	下载速度限制（字节/秒）
retries	int	HTTP 错误 5xx 的重试次数
buffersize	int	下载缓冲区大小（字节）
noresizebuffer	bool	不要自动调整下载缓冲区大小
continuedl	bool	尽可能尝试继续下载
noprogress	bool	不要打印进度条
logtostderr	bool	将消息记录到 stderr 而不是 stdout
updatetime	bool	使用 Last-modified 标头设置输出文件的创建时间
test	bool	仅下载前几个字节以测试下载器
min_filesize	int	跳过小于此大小的文件
max_filesize	int	跳过大于此大小的文件
http_chunk_size	int	基于块的 HTTP 下载的块大小

来源： youtube_dl/downloader/common.py30-54

FileDownloader 方法

核心方法

FileDownloader 基类提供了几个核心方法，它们构成了下载系统的基础。

1. download(filename, info_dict)：下载操作的主入口。此方法

   • 检查文件是否已存在
   • 处理下载之间的睡眠间隔
   • 调用 real_download 来执行实际下载
   • 成功时返回 True，否则返回 False

2. real_download(filename, info_dict)：子类必须实现的抽象方法。这是为每个协议实现实际下载逻辑的地方。

3. _hook_progress(status)：调用此方法向所有已注册的进度挂钩报告进度。status 字典包含有关下载进度的信息。

4. add_progress_hook(ph)：添加一个回调函数，该函数将在下载进度更新时调用。

实用工具方法

FileDownloader 类还提供了几个实用方法来处理常见任务

1. 格式化实用程序:

   • format_seconds(seconds)：将秒值格式化为字符串（HH:MM:SS）
   • format_percent(percent)：格式化百分比值
   • format_speed(speed)：格式化下载速度（字节/秒）
   • format_eta(eta)：格式化预计到达时间

2. 计算实用程序:

   • calc_percent(byte_counter, data_len)：计算完成百分比
   • calc_eta(start, now, total, current)：计算预计到达时间
   • calc_speed(start, now, bytes)：计算下载速度

3. 文件管理实用程序:

   • temp_name(filename)：为给定文件名返回一个临时文件名
   • undo_temp_name(filename)：从文件名中删除 .part 扩展名
   • try_rename(old_filename, new_filename)：尝试重命名文件
   • try_utime(filename, last_modified_hdr)：更新文件修改时间

4. 限流:

   • slow_down(start_time, now, byte_counter)：通过在需要时睡眠来实现速率限制

来源： youtube_dl/downloader/common.py68-180 youtube_dl/downloader/common.py193-235 youtube_dl/downloader/common.py177-191

进度报告

FileDownloader 类的一个关键特性是其进度报告系统。进度通过一系列可以通过下载器注册的挂钩来报告。

进度状态字典包含：

• status：'downloading' 或 'finished'
• downloaded_bytes：迄今已下载的字节数
• total_bytes 或 total_bytes_estimate：文件的总大小（如果已知）
• tmpfilename：用于下载的临时文件名
• filename：最终文件名
• eta：预计到达时间
• speed：下载速度（字节/秒）
• elapsed：从下载开始经过的时间

来源： youtube_dl/downloader/common.py241-316 youtube_dl/downloader/common.py386-393

错误处理

FileDownloader 基类实现了几个错误处理和报告方法。

1. 重试处理:

   • report_retry(err, count, retries)：报告重试尝试
   • format_retries(retries)：格式化重试次数

2. 状态报告:

   • report_error(...)：报告下载期间发生的错误
   • report_warning(...)：报告警告
   • report_resuming_byte(resume_len)：报告在特定字节处尝试恢复下载
   • report_unable_to_resume()：报告无法恢复时
   • report_file_already_downloaded(file_name)：报告文件已下载时

来源： youtube_dl/downloader/common.py171-176 youtube_dl/downloader/common.py318-337

特定于协议的实现

FileDownloader 类由几个特定于协议的下载器扩展，每个下载器都实现了 real_download 方法以实现其特定协议。

1. HttpFD：实现标准的 HTTP 下载

   • 处理重试、续传、分块下载
   • 实现范围请求进行部分下载

2. FragmentFD：分块媒体下载器的基类

   • 处理媒体片段的下载
   • 提供下载状态跟踪以实现可恢复性
   • 用作 HLS、DASH、F4M 和 ISM 下载器的基类

3. RtmpFD：实现 RTMP 协议下载

   • 使用外部 rtmpdump 命令
   • 解析和格式化 rtmpdump 特定的参数

4. HlsFD：实现 HLS（HTTP 直播流）下载

   • 处理 M3U8 播放列表的解析
   • 下载和处理片段
   • 处理加密（AES-128）

5. DashSegmentsFD：实现 DASH（动态自适应流式传输）下载

   • 处理从 DASH 清单下载片段

6. F4mFD：实现 F4M/AdobeHDS 下载

   • 处理 F4M 清单的解析
   • 下载和处理片段
   • 处理引导信息

来源： youtube_dl/downloader/http.py27-362 youtube_dl/downloader/fragment.py22-295 youtube_dl/downloader/rtmp.py23-216 youtube_dl/downloader/hls.py25-216 youtube_dl/downloader/dash.py13-83 youtube_dl/downloader/f4m.py259-438

扩展 FileDownloader

要为特定协议实现新的下载器，您需要

1. 创建一个继承自 FileDownloader 的新类
2. 设置一个 FD_NAME 类属性来标识下载器
3. 实现 real_download(filename, info_dict) 方法
4. 使用 FileDownloader 提供的实用方法来进行进度报告、错误处理等。

一个最小化的实现可能看起来像这样：

来源： youtube_dl/downloader/common.py382-384

与YoutubeDL的集成

FileDownloader 基类被 YoutubeDL 核心使用，它会根据媒体的协议和格式选择合适的下载器。交互通常遵循此模式：

1. YoutubeDL 使用适当的提取器提取媒体信息
2. 基于 URL 方案和媒体格式，YoutubeDL 选择一个下载器
3. YoutubeDL 使用适当的参数创建所选下载器的实例
4. YoutubeDL 调用 download 方法，并传入文件名和信息字典
5. 下载器处理下载过程并报告进度

这种模块化设计允许 youtube-dl 只需实现新的下载器而无需更改核心逻辑，即可支持广泛的协议和格式。

来源： youtube_dl/downloader/common.py339-380

总结

FileDownloader 基类为 youtube-dl 中的所有下载功能提供了基础。它实现了通用的功能，如进度报告、错误处理和文件管理，同时允许特定于协议的实现专注于实际的下载过程。这种设计模式使 youtube-dl 能够以模块化和可扩展的方式支持广泛的协议和格式。