BiliDown · 多平台视频下载器

一个基于 Tauri + React + Rust 的桌面下载工具，支持 B 站、YouTube 等主流视频平台，提供稳定、可控的视频下载体验。

产品目的

支持 B 站、YouTube 等主流视频平台，提供统一的下载体验。
解决”下载流程不稳定、任务状态不可控、合集识别误判、格式不兼容”的核心痛点。
提供面向日常使用的下载工作台：解析、选集、下载任务管理一体化。
在保持体验简洁的前提下，优先保证下载正确性与工程可维护性。

当前能力

多平台支持

B 站：扫码登录，登录态本地缓存（重启后可复用登录状态）。
YouTube：支持导入 Netscape 格式 cookies，下载会员专属内容。

视频解析与下载

B 站：视频 URL 解析，支持单视频、多分 P、合集场景识别。
YouTube：支持标准视频链接解析，自动选择 H.264 编码确保跨平台兼容性。
解析列表与下载列表双主 Tab 视图，操作路径更清晰。
下载列表支持”下载中 / 已下载”子 Tab 管理。
批量控制：支持”全部暂停”和”全部下载”按钮，可批量管理下载任务。
已下载列表支持”清空列表”（仅清理任务记录，不删除本地视频文件）。
任务级控制：暂停、恢复、删除、重试。
智能去重：自动检测已下载视频，避免重复下载。

配置与优化

下载设置可配置：保存路径、并发连接数、视频质量、重试次数等，支持可视化文件夹选择。
配置持久化：设置自动保存，重启应用后自动加载。
一键脚本重启开发环境：自动检测并结束旧进程后重新启动。
视频格式兼容性：自动处理 HEVC 视频，确保 macOS 可预览（使用 hvc1 标签）。
智能质量降级（B 站）：自动从 4K 开始尝试，依次降级到最高可用质量（4K → 1080P 60fps → 1080P+ → 1080P → 720P → 480P）。
H.264 优先策略（YouTube）：优先选择 H.264 编码视频，避免 AV1 等新编码格式带来的兼容性问题。

软件截图

启动界面

下载列表

技术方向

1) 正确性优先

合集识别以结构化数据为主，默认使用严格模式（strict）。
判定顺序固定：多分 P -> ugc_season 当前 section -> 单视频回退。
避免高风险”全页链接扫描”导致的”扩到 UP 主全部视频”误判。

2) 稳定性优先

下载链路采用可观测的状态机：Pending -> Downloading -> Paused -> Merging -> Completed/Failed。
支持分块下载、失败重试、任务级暂停与恢复。
合并环节通过 FFmpeg，提升输出兼容性与可播放性。
视频格式兼容性：自动检测视频编码格式，针对 macOS 平台优化 HEVC 视频。
智能质量降级：每个视频独立尝试从最高质量（4K）开始下载，自动降级到可用质量，最大化画质。

3) 可维护性优先

前后端职责清晰：前端负责交互编排，后端负责网络与任务执行。
下载模块拆分为 manager/chunked/merger，便于定位与演进。
保持 Tauri command 接口稳定，降低前端改造成本。

技术栈

前端：React 19 + TypeScript + Vite
客户端框架：Tauri 2.x
后端：Rust + Tokio + Reqwest
音视频处理：FFmpeg（自动检测/安装，内置到应用，支持 macOS 平台优化）
YouTube 支持：yt-dlp（系统依赖，需单独安装）

系统依赖

macOS:

# 安装 yt-dlp（YouTube 支持必需）
brew install yt-dlp

Windows:

# 使用 scoop 安装 yt-dlp
scoop install yt-dlp

Linux:

# 使用 pip 安装 yt-dlp
pip install yt-dlp

视频格式兼容性

YouTube H.264 优先策略

为确保下载的视频在所有平台上都能正常播放，BiliDown 对 YouTube 视频采用 H.264 优先策略：

问题背景

YouTube 提供 AV1、VP9、H.264 等多种编码格式
macOS 原生预览不支持 AV1 编码
新编码格式可能导致设备兼容性问题

解决方案

格式优先级：优先选择 H.264 编码视频，避免 AV1 等新格式
智能降级：H.264 不可用时，依次尝试 VP9、AV1 等格式
容器优化：优先选择 MP4 容器，确保最佳兼容性

工作原理

# yt-dlp 格式选择器
bestvideo[vcodec~='h264'][ext=mp4]+bestaudio[ext=m4a]
→ bestvideo[vcodec~='h264']+bestaudio
→ best[ext=mp4]/best

支持的视频格式

H.264 (AVC)：优先选择 ✅
VP9：H.264 不可用时回退 ✅
AV1：最后选择 ⚠️（macOS 无法预览）

macOS HEVC 视频支持

BiliDown 自动处理 macOS 平台的 HEVC（H.265）视频兼容性问题：

问题背景

B站返回的 HEVC 视频使用 hev1 Codec Tag
macOS 原生预览只支持 hvc1 Codec Tag
导致下载的视频无法在 macOS 上按空格键预览

解决方案

自动检测：在视频合并阶段自动检测视频编码格式
智能修复：检测到 HEVC 视频时，自动添加 -tag:v hvc1 参数
无损处理：只修改 Codec Tag，不重新编码，保持原画质
平台优化：仅在 macOS 平台应用修复，其他平台保持原样

工作原理

# 检测 HEVC 视频
ffmpeg -i video.mp4 -hide_banner

# 自动添加 macOS 兼容性标签
ffmpeg -i video.mp4 -i audio.m4a -c:v copy -tag:v hvc1 -c:a copy -y output.mp4

支持的视频格式

H.264 (AVC)：完全兼容，无需处理 ✅
HEVC (H.265)：自动处理，macOS 可预览 ✅
AAC 音频：完全兼容 ✅

兼容性矩阵

视频编码	macOS 预览	Windows 预览	Linux 预览
H.264	✅	✅	✅
HEVC	✅*	✅	✅

*需要自动添加 hvc1 标签

核心模块

前端

src/App.tsx：页面状态、解析流程、下载任务交互

后端核心

src-tauri/src/commands.rs：Tauri 命令入口（解析、下载、登录、配置、cookies 管理）
src-tauri/src/platform/：多平台抽象层
- mod.rs：平台枚举、统一接口、客户端工厂
- bilibili.rs：B 站客户端适配器
- youtube.rs：YouTube 客户端实现（基于 yt-dlp）
src-tauri/src/bilibili.rs：B 站接口访问与合集识别
src-tauri/src/login.rs：B 站扫码登录与登录态轮询
src-tauri/src/downloader/：下载模块
- manager.rs：任务生命周期与事件上报
- chunked.rs：分块下载与重试
- merger.rs：音视频合并与 macOS 兼容性处理

快速开始

环境要求

Node.js 18+
Rust stable（建议通过 rustup 安装）
macOS / Windows / Linux（以本地 Tauri 运行环境为准）

安装依赖

npm install

启动开发环境

npm run tauri dev

或使用项目脚本（会先停止旧进程再重启）：

./scripts/restart-tauri-dev.sh

前端构建检查

npm run build

macOS 一键打包 DMG

使用项目脚本一键构建 DMG：

./scripts/build-dmg.sh

构建完成后在 Finder 中定位产物：

./scripts/build-dmg.sh --open

说明：

该脚本内部执行 npm run tauri build -- --bundles dmg。
默认输出目录：src-tauri/target/release/bundle/dmg/。
脚本会在终端打印本次生成的 DMG 绝对路径。

一键清理构建过程文件

使用项目脚本清理构建产物（不删除依赖）：

./scripts/clean-build.sh

默认清理目录：

dist
src-tauri/target
src-tauri/gen

说明：

仅清理构建过程文件，不会删除 node_modules。
脚本包含路径安全检查，避免误删项目外目录。

使用流程

B 站视频下载

打开客户端，右上角扫码登录 B 站账号。
在输入框粘贴视频 URL，点击”解析”或”粘贴解析”。
在”解析列表”选择要下载的分 P/选集，点击下载。
切换到”下载列表”查看任务状态，可暂停/恢复/删除。
在”已下载”子 Tab 可清理任务记录，保持列表整洁。

YouTube 视频下载

安装 yt-dlp（首次使用）：
- macOS: brew install yt-dlp
- Windows: scoop install yt-dlp
- Linux: pip install yt-dlp
导入 Cookies（可选，用于下载会员专属内容）：

导出 Cookies 方法：
- Chrome/Edge: 使用 “Get cookies.txt LOCALLY” 插件
- Firefox: 使用 “cookies.txt” 插件
- 安装插件后，访问 YouTube 并登录
- 点击插件图标，选择”导出”或”Download”，保存为 .txt 文件
导入到 BiliDown：
- 打开客户端，进入设置界面
- 找到 “Cookies 管理” 部分
- 点击”导入 Cookies”，选择刚才导出的文件
- 导入成功后会显示”✓ 有效”状态
下载视频：
- 在输入框粘贴 YouTube 视频 URL（支持 youtube.com 和 youtu.be）
- 点击”解析”，等待视频信息加载
- 点击下载开始下载
- 视频会自动使用 H.264 编码，确保跨平台兼容性

配置说明

配置项	说明	默认值
`save_path`	下载保存目录	`~/Movies/DiliDown`
`concurrent_connections`	并发连接数（同时下载数量）	`4`
`chunk_size`	分块大小	`1MB`
`quality`	视频清晰度（B站 qn）	`120`（4K，自动降级）
`max_retry`	最大重试次数	`5`
`timeout`	单次请求超时（秒）	`60`

智能质量降级

BiliDown 采用智能质量降级策略，确保每个视频都获得最高可用画质：

降级策略

优先 4K：默认尝试 4K（qn=120）画质
自动降级：4K 不可用时，依次尝试 1080P 60fps（116）→ 1080P+（112）→ 1080P（80）→ 720P（64）→ 480P（32）
独立尝试：每个视频独立尝试，不受其他视频质量影响
智能选择：自动选择第一个可用的质量等级

质量等级对应关系

qn 值	画质	分辨率
120	4K	3840×2160
116	1080P 60fps	1920×1080 @ 60fps
112	1080P+	1920×1080 (高码率)
80	1080P	1920×1080
64	720P	1280×720
32	480P	854×480

工作原理

// 每个视频都会依次尝试所有质量等级
for quality in [120, 116, 112, 80, 64, 32] {
    if try_download(quality).success() {
        return quality; // 使用第一个可用的质量
    }
}

日志示例

✓ 视频 BV1xx411c7mD CID 12345678 使用质量: 120 (4K)
⚠ 视频 BV1yy411c7nE CID 87654321 质量 120 不可用: 视频流不存在
⚠ 视频 BV1yy411c7nE CID 87654321 质量 116 不可用: 需要大会员
✓ 视频 BV1yy411c7nE CID 87654321 使用质量: 80 (4K不可用，已降级)

影响因素

实际可用画质受以下因素影响：

会员权限：4K、1080P+、1080P 60fps 需要大会员
平台风控：个别视频可能限制高质量下载
地区限制：某些内容有地区版权限制
UP 主设置：UP 主可能限制视频最高质量

Roadmap

近期（v0.2）

✅ 批量控制功能（全部暂停/全部下载）。
✅ 配置持久化与文件夹选择器。
✅ 视频格式兼容性处理（macOS HEVC 支持）。
✅ 智能质量降级（4K 优先，自动降级到可用质量）。
✅ 前端开放合集识别模式切换（strict / compat）。
✅ 下载速度优化（并发策略、分块策略与网络重试参数调优）。
✅ 下载失败任务批量重试与错误归因增强。
✅ 下载列表增加更直观的速度/剩余时间展示。

v0.2 已完成 🎉

中期（v0.3）

✅ 任务状态持久化（支持重启后恢复任务视图）。
✅ 下载历史检索与基本统计能力。
✅ 更完善的异常网络场景回退策略。

v0.3 已完成 🎉

当前版本（v0.4）

✅ 多平台支持架构（平台抽象层）。
✅ YouTube 视频下载支持。
✅ YouTube Cookies 管理功能。
✅ YouTube H.264 优先格式选择。
✅ 跨平台视频格式兼容性优化。

v0.4 进行中 🔥

长期（v1.0+）

更完整的下载资产管理（视频、封面、元信息）。
批量任务体验优化（队列管理、规则化命名）。
面向长期维护的插件化能力探索。

已知边界

支持的平台

B 站：支持 video/BV... 视频链接解析，包括单视频、多分 P、合集
YouTube：支持标准视频链接（youtube.com/watch?v= 和 youtu.be/）

已知限制

任务状态会持久化保存，但正在下载的任务重启后需手动恢复。
受平台风控、会员权限、地区限制等因素影响，个别内容可能不可下载。
YouTube 下载需要系统安装 yt-dlp 工具。
YouTube 会员内容需要手动导入 cookies。
暂不支持 YouTube 播放列表和频道视频批量下载。
YouTube 视频字幕下载功能暂未实现。

免责声明

本项目仅用于学习与技术研究。请遵守 B 站、YouTube 等平台的服务条款及相关法律法规，仅下载你有权访问与使用的内容。使用本工具下载的任何内容，其版权归原作者所有，请勿用于商业用途或侵犯他人版权。

Name		Name	Last commit message	Last commit date
Latest commit History 34 Commits
.vscode		.vscode
docs		docs
public		public
screen		screen
scripts		scripts
src-tauri		src-tauri
src		src
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
README.md		README.md
index.html		index.html
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
tsconfig.node.json		tsconfig.node.json
vite.config.ts		vite.config.ts

Folders and files

Latest commit

History

Repository files navigation

BiliDown · 多平台视频下载器

产品目的

当前能力

多平台支持

视频解析与下载

配置与优化

软件截图

启动界面

下载列表

技术方向

1) 正确性优先

2) 稳定性优先

3) 可维护性优先

技术栈

系统依赖

视频格式兼容性

YouTube H.264 优先策略

问题背景

解决方案

工作原理

支持的视频格式

macOS HEVC 视频支持

问题背景

解决方案

工作原理

支持的视频格式

兼容性矩阵

核心模块

前端

后端核心

快速开始

环境要求

安装依赖

启动开发环境

前端构建检查

macOS 一键打包 DMG

一键清理构建过程文件

使用流程

B 站视频下载

YouTube 视频下载

配置说明

智能质量降级

降级策略

质量等级对应关系

工作原理

日志示例

影响因素

Roadmap

近期（v0.2）

中期（v0.3）

当前版本（v0.4）

长期（v1.0+）

已知边界

支持的平台

已知限制

相关文档

免责声明

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages