FluentYTDL 详细部署教程

FluentYTDL 是一款专为 Windows 平台设计的桌面下载器，它使用 Fluent Design 语言，为 yt-dlp 和 FFmpeg 提供了图形化操作界面。您可以通过它轻松下载 YouTube 和 X (Twitter) 上的媒体内容，并支持视频剪辑、格式转换、字幕下载等高级功能。

本教程将指导您完成从安装到使用的全流程。

1. 准备工作

1.1 系统要求

  • 操作系统：64位 Windows 10 或 Windows 11。
  • Python (仅从源码运行)：版本 3.10 或更高。

1.2 支持的平台与范围

  • YouTube：全面支持视频、Shorts、直播回放、播放列表、频道、字幕和封面。
  • X (Twitter)：支持单个帖子中的可下载媒体。
  • 注意：其他 yt-dlp 支持的网站不在本项目官方支持范围内。

2. 安装 FluentYTDL

2.1 方式一：使用预构建的 Windows 安装包（推荐）

这是最简单快捷的方式，适合大多数用户。

  1. 访问项目的 GitHub Releases 页面。
  2. 在最新版本的 Assets 部分，根据需求下载以下文件之一：
    • *-setup.exe：标准的 Windows 安装程序，推荐。
    • *-full.7z：便携版，包含完整运行环境，解压即用。
    • *-app-core.7z：仅应用核心文件，用于更新。
  3. （可选）下载 SHA256SUMS.txt 文件以校验下载文件的完整性。
  4. 如果下载的是安装程序，双击运行并按提示安装。如果下载的是便携版，使用 7-Zip 等工具解压到目标文件夹，然后运行其中的 FluentYTDL.exe。

2.2 方式二：从源码运行

适合开发者或希望运行最新代码的用户。

  1. 克隆仓库：

    1
    2
    git clone https://github.com/SakuraForgot/FluentYTDL.git
    cd FluentYTDL

  2. 安装依赖 (推荐使用 uv)：

    1
    2
    3
    4
    # 安装 uv (如果尚未安装)
    pip install uv
    # 同步依赖并创建虚拟环境
    uv sync --extra dev

  3. 启动应用：

    1
    uv run python main.py

    或者，使用标准 Python 虚拟环境：

    1
    2
    3
    4
    python -m venv venv
    venv\Scripts\activate
    pip install -e ".[dev]"
    python main.py

首次运行：应用会自动下载并管理所需的 yt-dlp、FFmpeg 等外部组件，请保持网络畅通。

3. 基本使用流程

3.1 解析链接并选择格式

  1. 在应用主界面的输入框中，粘贴一个 YouTube 或 X 的视频/帖子链接。
  2. 点击 解析 (Parse) 按钮。应用会获取可用的媒体信息。
  3. 在格式选择界面中，您可以根据需要：
    • 快速预设：选择低、中、高等质量预设。
    • 精细控制：手动选择分辨率、容器格式 (如 MP4/MKV)、视频编码、音频语言等。

3.2 添加到任务队列

  1. 确认格式选择后，点击 “添加到队列” 或 “下载” 按钮。
  2. 任务会出现在主界面的任务队列中，您可以：
    • 查看下载进度和状态。
    • 暂停/恢复任务。
    • 调整任务优先级。

3.3 高级处理选项

在下载前或下载后，您可以启用以下处理功能：

  • 视频剪辑：设定开始和结束时间，只下载视频的特定片段。
  • 字幕处理：单独下载字幕、合并双语字幕，或将字幕嵌入视频。
  • SponsorBlock 集成：自动标记或跳过视频中的赞助商片段。
  • 格式转换：使用 FFmpeg 将下载的媒体转换为其他格式。

4. 高级功能与配置

4.1 批量下载

  • 解析播放列表/频道：粘贴 YouTube 播放列表或频道 URL 进行解析。应用会列出所有条目，您可以全选或挑选部分项目，然后批量添加到下载队列。

4.2 管理身份验证会话

对于需要登录才能访问的内容（如私人视频或年龄限制内容）：

  1. 在应用设置中找到 “身份验证” 部分。
  2. 使用 “导入 Cookie” 或启动集成的 WebView2 登录流程 来建立有效的浏览器会话。应用会安全地管理这些凭证。

4.3 应用与组件更新

  • 应用更新：FluentYTDL 支持内置更新。当有新版本时，您会收到提示，并可通过应用内的更新功能一键升级。
  • 工具更新：您也可以在应用设置中手动检查并更新 yt-dlp、FFmpeg 等核心组件，以获取最新的兼容性和性能改进。

5. 开发与贡献（可选）

如果您有兴趣为 FluentYTDL 开发或贡献代码：

  1. 环境设置：按照“从源码运行”的步骤设置开发环境。

  2. 代码风格：项目使用 ruff 进行代码检查和格式化。

    1
    uv run ruff check src tests

  3. 运行测试：

    1
    2
    $env:QT_QPA_PLATFORM = "offscreen"
    uv run pytest tests -q

  4. 提交贡献：请阅读项目根目录下的 CONTRIBUTING.md 文件，了解详细的贡献指南和 PR 流程。

6. 常见问题与提示

  • 下载失败或解析错误：
    • 检查网络连接。
    • 尝试在应用设置中更新 yt-dlp 到最新版本。
    • 某些平台（如 YouTube）的频繁变更可能导致临时故障，请关注项目更新。
  • 需要登录的内容无法下载：
    • 请使用应用内的身份验证功能，通过 WebView2 登录您的账户以建立有效会话。
  • 便携版与安装版的选择：
    • 推荐使用安装版以获得更好的系统集成（如文件关联、开始菜单快捷方式）。
    • 便携版适合放在 U 盘或无需安装的环境中使用。
  • 数据与配置位置：
    • 应用的数据（如队列、设置、Cookies）通常存储在用户目录下。通过源码运行时，数据会存放在项目目录附近。

总结

通过以上步骤，您应该能够成功部署并使用 FluentYTDL。它的核心价值在于将 yt-dlp 强大的命令行能力封装到一个清晰、易用的图形界面中，特别适合不熟悉命令行操作，但又需要处理复杂媒体下载任务的 Windows 用户。

建议从下载安装程序开始，快速体验其核心流程。如果您是开发者，可以尝试从源码运行并探索其项目结构。使用过程中，请注意遵守您所下载内容的平台条款和版权法律。