视频 Faststart 工具

一个本地运行的 Web 工具，用来批量检查 MP4 系列视频是否已经适合网页快速播放，并把需要处理的视频转换为 faststart 布局。

工具会扫描指定文件夹中的 .mp4、.m4v、.mov 文件，读取顶层 MP4 box 顺序，识别 moov 是否位于 mdat 前面。需要转换的文件会通过系统 ffmpeg 复制封装为 faststart 版本。

特性

• 本地浏览器界面，默认监听 127.0.0.1:3000
• 支持递归扫描 .mp4、.m4v、.mov
• 显示每个视频的大小、box 顺序、faststart 状态和输出路径
• 只转换需要 faststart 的视频，已是 faststart 的文件会跳过
• 转换结果写入源文件夹下的 faststart-output/
• 保留原始相对目录结构
• 不覆盖原视频；如果输出文件已存在，会自动追加数字后缀
• 转换完成后会重新解析输出文件，确认结果确实是 faststart

环境要求

• Node.js 20 或更高版本
• ffmpeg 已安装并可在 PATH 中直接运行

macOS 和 Windows 上可以使用界面的“选择”按钮打开系统文件夹选择器。其他系统或选择器不可用时，可以直接在输入框中填写文件夹路径。

Windows 安装准备

1. 安装 Node.js 20 或更高版本。
2. 安装 Windows 版 ffmpeg，并把 ffmpeg 的 bin 目录加入系统 PATH。
3. 打开新的 PowerShell 或命令提示符，确认命令可用：

node --version
ffmpeg -version

如果 ffmpeg -version 无法运行，说明 ffmpeg 还没有正确加入 PATH。

快速开始

npm start

启动后打开：

http://127.0.0.1:3000

使用流程：

1. 点击“选择”或手动输入视频文件夹路径。
2. 点击“扫描”，查看每个视频的 box 顺序和状态。
3. 点击“转换”，处理所有标记为“待转换”的视频。
4. 在源文件夹下查看 faststart-output/ 中生成的新文件。

输出规则

假设选择的文件夹是：

/Users/name/Videos

源文件：

/Users/name/Videos/event/clip.mp4

转换后默认输出到：

/Users/name/Videos/faststart-output/event/clip.mp4

如果同名文件已经存在，会生成类似：

/Users/name/Videos/faststart-output/event/clip-1.mp4

原始文件不会被修改。

Windows 路径也可以手动输入，例如：

C:\Users\name\Videos

状态说明

• faststart：moov 位于 mdat 之前，适合快速播放。
• needs-faststart：moov 位于 mdat 之后，需要转换。
• unsupported-layout：文件是支持的扩展名，但 box 布局不属于当前工具可判断的常见形态。
• parse-error：文件无法被安全解析。

常用命令

npm start

启动本地 Web 服务。

npm test

运行 Node 内置测试。

项目结构

public/
  index.html      浏览器界面
  app.js          前端交互逻辑
  styles.css      页面样式
src/
  server.js       HTTP 服务、API 和静态资源
  scanner.js      文件夹扫描和视频过滤
  mp4Boxes.js     MP4 顶层 box 解析与布局分类
  converter.js    ffmpeg 转换、输出路径规划和结果校验
tests/
  *.test.js       单元测试和接口测试

API 概览

• GET /api/health：检查服务状态和 ffmpeg 可用性
• POST /api/select-folder：在 macOS 上打开系统文件夹选择器
• POST /api/scan：扫描指定文件夹
• POST /api/convert：转换指定文件列表

注意事项

• 本工具面向本地批量处理，不会上传视频文件。
• 服务只绑定到 127.0.0.1，避免暴露本地文件访问能力。
• 转换使用 ffmpeg -c copy -movflags +faststart，不会重新编码视频内容。
• faststart-output/ 会在扫描源文件夹时被跳过，避免重复处理生成结果。