Media Storage

你是否想过，利用 YouTube 海量的免费存储空间来备份重要数据？

Media Storage 就是这样一款开源工具，它通过将任意文件编码为无损视频流上传至 YouTube，并在需要时解码还原，从而实现“曲线救国”式的云存储。项目同时提供了功能完整的命令行界面（CLI）和图形用户界面（GUI），既适合开发者自动化部署，也方便普通用户直观操作。

核心特性

Media Storage 不仅仅是一个简单的转码工具，它在数据完整性、安全性和易用性上做了深度优化：

• 无损编解码循环：基于 FFV1 编码器，确保任何类型的文件（文档、图片、压缩包等）在转换为视频并还原后，比特级一致，零数据丢失。
• 喷泉码冗余保护：集成 Wirehair 喷泉码技术。即使 YouTube 对视频进行了有损压缩或导致部分帧丢失，算法也能通过冗余数据自动修复并重建原始文件。
• 端到端加密：内置 libsodium 加密模块，支持使用密码对文件进行 XChaCha20-Poly1305 加密。上传到 YouTube 的只是密文视频，确保隐私安全。
• 高效批量处理：支持队列管理，可一次性添加多个文件进行批量编码，后台多线程运行，不阻塞主界面。
• 实时状态监控：提供可视化的进度条、详细的状态日志以及线程隔离机制，确保操作过程透明且界面流畅响应。

获取构建产物（无需编译）

如果你不想自行编译，可以通过项目的 CI/CD 流水线直接获取最新版本的可执行文件：

1. 访问项目的 CI/CD 流水线页面。
2. 点击 "Log in as guest"（以访客身份登录）。
3. 进入 yt-media-storage 项目，找到最近一次 Successful（成功）的构建记录。
4. 点击 "Artifacts" 下载对应系统的 CLI 和 GUI 压缩包。

注意：直接运行的可执行文件可能需要系统预装部分共享库（如 FFmpeg、Qt6 运行时等）。若遇到缺失提示，建议参考下方的安装指南配置环境。

环境依赖与安装

本项目基于 C++23 标准开发，依赖以下核心组件：

• CMake 3.22+
• C++23 编译器
• FFmpeg (含开发库)
• libsodium
• OpenMP
• Qt6

🐧 Linux 用户

Ubuntu / Debian

sudo apt update
sudo apt install cmake build-essential qt6-base-dev \
  libavcodec-dev libavformat-dev libavutil-dev libswscale-dev libswresample-dev \
  libsodium-dev libomp-dev ffmpeg

Fedora / CentOS

sudo dnf install cmake gcc-c++ qt6-qtbase-devel ffmpeg-devel libsodium-devel libgomp

Arch Linux

sudo pacman -S cmake qt6-base ffmpeg libsodium openmp

🍎 macOS 用户

推荐使用 Homebrew 一键安装：

brew install cmake qt@6 ffmpeg libsodium libomp

🪟 Windows 用户

推荐使用 vcpkg 管理依赖：

vcpkg install ffmpeg libsodium openmp qt6

或者，你可以单独通过 Qt 在线安装程序安装 Qt6，并使用 vcpkg 安装 FFmpeg 和 libsodium。

编译与构建

环境准备就绪后，即可开始构建：

mkdir build
cmake -B build
cmake --build build

构建完成后，你将获得两个可执行文件：

• media_storage：命令行工具，适合脚本调用。
• media_storage_gui：图形界面工具，适合日常交互。

使用指南

1. 命令行模式 (CLI)

编码（文件 → 视频）

./media_storage encode --input <源文件路径> --output <输出视频路径> [--encrypt --password <你的密码>]

注：加上 --encrypt 和 --password 参数即可启用加密。

解码（视频 → 文件）

./media_storage decode --input <输入视频路径> --output <还原文件路径>

2. 图形界面模式 (GUI)

启动程序：

./media_storage_gui

单文件操作流程：

• 编码：点击“输入文件”旁的浏览按钮选择源文件 → 设置输出视频路径 → 点击 “编码为视频”。
• 解码：选择已上传的视频文件 → 设置还原文件的保存路径 → 点击 “从视频解码”。

批量处理流程：

1. 点击 “添加文件”，将多个待处理文件加入队列。
2. 统一设置输出目录。
3. 点击 “全部批量编码”，程序将按序自动处理。

实时监控：
界面底部设有日志面板，详细记录每一步的操作信息；顶部进度条实时反馈当前任务状态。所有耗时操作均在独立线程运行，确保界面永不卡顿。

技术原理深挖

Media Storage 的工作流设计严谨，兼顾了效率与安全：

1. 分块与编码：原始文件被切割成数据块，通过 Wirehair 喷泉码生成带有冗余校验的数据包。
2. 视频嵌入：数据包被嵌入到视频帧的有效载荷中。
3. 格式规范：
   • 容器：MKV (Matroska)
   • 视频编码：FFV1 (Lossless Video Codec)
   • 分辨率：3840x2160 (4K)
   • 帧率：30 FPS
4. 加密层：在编码前，可选通过 libsodium 库进行 XChaCha20-Poly1305 authenticated encryption，确保只有持有密钥者才能还原。
5. 重建：解码时，从视频帧提取数据，利用喷泉码的纠错能力修复可能损坏的数据块，最终重组为原始文件。

常见问题排查 (Troubleshooting)

🔨 构建阶段问题

• 错误：未找到 Qt6
  • 解决：确认已安装 qt6-base-dev (Debian/Ubuntu) 或 qt6-qtbase-devel (Fedora) 等开发包。
• 错误：缺少 FFmpeg 库
  • 解决：安装 FFmpeg 的开发版本（通常包含 libavcodec-dev, libavformat-dev 等）。
• 错误：缺少 libsodium 或 OpenMP
  • 解决：检查是否安装了对应的 -dev 或 -devel 包。

⚙️ 运行阶段问题

• 无法打开输入文件
  • 检查：文件路径是否正确，当前用户是否有读取权限。
• 编码失败
  • 检查：目标磁盘空间是否充足；输出路径是否可写。
• 解码失败
  • 检查：输入的视频是否确实是由本工具编码生成的有效文件。
• 编码错误：无法写入头部 (Unable to write header)
  • 关键提示：如果你尝试输出 MP4 格式并使用 FFV1 编码器，必须确保 FFmpeg 版本 ≥ 8.0。
  • 建议方案：为避免兼容性问题，请始终使用 MKV 容器格式，它对 FFV1 的支持更为成熟稳定。