VDDT使用指南

概述

　　VDDT（Video Downloader & Transcoder Tool）是一款基于 yt-dlp 的多功能视频下载与转码工具，采用模块化架构设计，提供命令行界面（CLI）与终端图形界面（TUI）两种交互方式。项目经过多次迭代，从最初的单文件脚本发展为支持依赖自动检查、离线转码、配置持久化、日志记录等功能的完整工具集。

项目架构

　　项目包含三个版本分支，可根据需求选择使用：

版本	位置	版本号	特点
VDDT.py	根目录	v1.2.0	单文件版，适合快速使用
VDDT-beta/	VDDT-beta/	v2.0.5-beta	模块化 CLI 版，功能最完整，稳定
DEBUG/	DEBUG/	v2.1.0	TUI 终端图形界面版（实验性）

推荐使用 VDDT-beta 版本，其代码结构清晰、功能完善，是当前的主力版本。

功能特点

多种下载模式：支持视频+音频自动合并、仅视频、仅音频以及手动选择视频+音频格式等多种下载模式。
丰富的格式选择：能够获取并列出给定 URL 的所有可用格式，包括分辨率和文件大小等详细信息。
自定义配置：提供自定义文件名模板、下载目录设置、Cookie 文件管理等功能。
下载辅助功能：支持下载字幕、嵌入视频封面、下载 B 站弹幕等辅助功能。
离线转码：支持对已下载视频进行离线转码，包括 AMV 格式转换（160x112 低分辨率）和通用格式转换（MP4/MKV/AVI/MOV 等），支持自定义分辨率，实时显示转码进度。
批量下载：支持从文本文件读取多个链接进行批量下载。
依赖自动检测：启动时自动检查并安装缺失的 Python 依赖库。
终端图形界面（TUI）（实验性）：基于 curses 实现的可视化菜单界面，支持键盘导航、对话框操作，提供更友好的交互体验。
日志记录系统：支持彩色控制台输出和文件日志轮转，方便问题排查。
配置持久化：配置以 JSON 格式保存，支持下载、转码、网络、界面等分类配置。

环境依赖

Python：3.8 或更高版本。
yt-dlp：核心下载引擎，pip install yt-dlp。
ffmpeg：用于视频合并、转码、嵌入封面等，需提前安装并配置环境变量。
ffmpeg_progress_yield：离线转码进度显示，pip install ffmpeg_progress_yield。
tqdm：转码进度条美化，pip install tqdm。
colorama：终端彩色输出，pip install colorama。

提示：VDDT-beta 版本启动时会自动检测并提示安装缺失依赖，用户只需确认即可。

使用方法

1. VDDT-beta 版本（推荐）

进入 beta 目录，运行 main.py：

1 2	cd VDDT-beta python main.py

程序将自动检测依赖，缺失时会询问是否自动安装。主菜单提供以下操作：

下载单个视频/链接：输入视频 URL，选择下载模式和格式，设置字幕、封面、弹幕等选项。
批量下载：从文本文件读取多个链接，逐一下载。
离线转码：将本地视频文件转码为其他格式。

下载模式说明

模式	说明
1. 视频+音频自动合并	自动选择最高画质视频 + 最佳音频，合并为 MP4
2. 仅视频	列出所有视频格式，用户手动选择
3. 仅音频	下载最佳音频并转换为 MP3 192kbps
4. 手动选择视频+音频格式	列出所有格式，可手动组合

2. VDDT.py 单文件版

1	python VDDT.py

单文件版功能精简，所有代码集中在单一文件中，适合快速使用或移植。

3. DEBUG TUI 版（实验性）

1 2	cd DEBUG python main.py

该版本启动后进入 curses 终端图形界面，支持键盘导航：

方向键 / j/k：上下导航
Enter：确认选择
数字键：快速选择菜单项
Q：返回/退出
H：帮助

注意：TUI 版需要支持 curses 的终端环境，部分 Android 终端可能不完全兼容。

离线转码功能

独立于下载功能，可对本地视频文件进行转码：

1
2
3

# 从 VDDT-beta 主菜单选择 "离线转码"
# 或在 VDDT-beta 目录下直接运行：
python offline_transcoder.py

支持两种转码模式：

AMV 模式：转换为 160x112 低分辨率 AMV 格式，适用于便携设备
通用格式：可选择 MP4/MKV/AVI/MOV/FLV 等格式，可自定义分辨率

转码过程中实时显示进度条，支持批量处理。

代码结构与关键模块说明

VDDT-beta 模块架构

项目采用模块化设计，各模块职责明确：

VDDT-beta/
├── main.py                  # 主入口：菜单流程控制、版本信息
├── check_deps.py            # 依赖自动检测与安装
├── downloader_core.py        # 下载核心：格式获取、文件下载、Cookie管理
├── downloader_handler.py     # 下载处理器：用户交互、模式选择、配置选项
├── offline_transcoder.py     # 离线转码：AMV/通用格式转换，进度显示
├── utils.py                 # 工具函数：输入询问、文件名清洗、进度回调、Cookie转换
├── test_douyin.py           # 抖音下载测试脚本
├── cookies/                 # Cookie 文件存放目录
└── VDDT_Downloads/          # 默认下载目录

模块 check_deps.py

定义需要检查的依赖库列表（yt_dlp、colorama、ffmpeg_progress_yield、tqdm、requests）。
启动时逐个导入检查，发现缺失则询问用户是否自动安装。
安装通过 pip install 子进程完成。

模块 downloader_core.py

核心下载逻辑，包含以下函数：

suggest_best_quality(formats)：基于视频高度智能推荐最高画质的格式 ID。
get_format_lists(url, ydl_opts)：获取并列出所有可用格式，含格式 ID、扩展名、分辨率、视频编码、音频编码、文件大小等。
download(url, format_id, output_dir, ydl_opts, info_dict)：核心下载函数，支持片段并发下载、重试机制、进度回调。
prepare_cookies_netscape(target_url)：自动检测并转换 Cookie 文件为 Netscape 格式，支持三种命名方式。

模块 downloader_handler.py

handle_single_download(url, base_ydl_opts, output_dir)：处理单个 URL 的完整下载流程。引导用户选择模式、选择格式、配置字幕/封面/弹幕/转码等选项。

模块 offline_transcoder.py

离线转码功能，基于 ffmpeg 实现：

parse_resolution(s)：解析用户输入的分辨率字符串（支持 1920*1080、1080p、1920x1080）。
get_video_files(folder)：扫描文件夹中的视频文件（支持 mp4/mkv/avi/mov/flv/wmv/m4v/ts/webm）。
run_offline_transcoder()：主流程，提供文件选择、模式选择、格式和分辨率设置，使用 FfmpegProgress + tqdm 实时显示进度。

模块 utils.py

通用工具函数：

ask(prompt)：询问用户是/否问题并返回布尔值。
convert_to_netscape_cookie(cookie_str, output_file)：将原始 cookie 字符串转换为 Netscape 格式并保存。
sanitize_filename(name)：移除 Windows 文件名中的非法字符。
progress_hook(d)：yt-dlp 下载进度的回调函数，可视化加载条显示进度、速度、ETA。

配置文件管理

DEBUG TUI 版本支持完整的配置管理系统：

配置文件：vddt_config.json（JSON 格式）。
配置分类：
- 下载配置：输出目录、默认模式、并发数、重试次数、文件名模板、字幕、封面、弹幕。
- 转码配置：默认预设、编码器、CRF 值、码率。
- 网络配置：代理服务器、超时时间、User-Agent。
- 界面配置：进度条长度、详细输出、颜色开关。
配置加载失败时自动回退到默认值。

　　对于需要登录或有访问限制的视频内容，将 cookie 保存到 cookies/ 文件夹内。支持三种命名方式（按优先级）：

文件名	示例	说明
`域名.ck`	`bilibili.com.ck`	完整域名
`域名_下划线.ck`	`bilibili_com.ck`	下划线代替点号
`common.ck`	`common.ck`	通用 cookie 文件

程序自动检测并转换为 Netscape 格式，无需手动操作。

日志系统

DEBUG TUI 版内置日志系统：

控制台输出：彩色分级日志（DEBUG/INFO/WARNING/ERROR）。
文件日志：自动保存到 logs/vddt_YYYYMMDD.log。
日志轮转：单文件最大 5MB，保留 3 个备份。
便捷调用：get_logger() 获取全局日志实例，支持 debug()、info()、warning()、error()、exception() 等方法。

常见问题与解决方法

下载失败

网络问题：检查网络连接和代理设置。
链接无效或过期：确认视频链接是否正确。
需要登录：配置有效的 cookie 文件到 cookies/ 目录。
地理限制：可能需要使用代理服务器。

Cookie 无效

确保 cookie 文件位于 cookies/ 目录下。
文件名符合规范（如 bilibili.com.ck）。
Cookie 未过期，更新后重新保存。

转码失败

检查 ffmpeg 是否已安装并可用。
确认输入文件未被损坏或加密。
自定义分辨率参数需符合格式规范（如 1920*1080、720p）。

依赖安装失败

重试时使用 pip install <包名> 手动安装。
Android 环境可能需要先更新 pip（pip install --upgrade pip）。

文件名乱码

系统区域设置和编码格式需正确。
使用 sanitize_filename 函数清洗文件名中的非法字符。

结语

　　VDDT 从最初的单文件下载脚本，逐步演化为支持依赖检测、离线转码、配置管理和终端图形界面的多功能工具集。VDDT-beta 作为主力版本，采用模块化架构，代码清晰可维护，功能完整稳定。DEBUG 目录下的 TUI 版本则探索了更友好的终端交互方式。未来随着 yt-dlp 的更新，VDDT 将持续跟进优化，为用户带来更完善的使用体验。