ZWScan：把本地视频文件夹一键生成 ZWMAP 播放列表

指向一个视频文件夹，ZWScan 按子目录自动分组、自动匹配字幕/章节/缩略图/配音轨，输出一份完整的 ZWMAP 播放列表 JSON。配合 ZWServe 提供目录服务，ZWPlayer 即可播放整个媒体库——无需手动逐条建列表。

下载（预编译，免安装）：

• 🪟 Windows (.exe)
• 🍎 macOS（Apple Silicon）
• 🐧 Linux x86
• 🐧 Linux ARM64

免费 · 单一自包含二进制 · 无需运行时 · 免登录

痛点：手动逐条建播放列表太繁琐

你已经有了一个整理好的视频文件夹——一套课程、一批讲座、孩子的动画合集。在线播放列表编辑器适合逐条精修，但当文件有 50 个、500 个时，手动添加每一项就成了苦差事；而且一旦忘了给某个视频挂上对应的 .srt 字幕或 .chapter.json 章节，字幕、章节这些增强功能就悄悄失效了。

ZWScan 替你完成这些繁琐工作：遍历文件夹、按目录分组、按文件名匹配每一个配套文件，一次扫描输出完整的 ZWMAP/1.0 播放列表。

ZWScan 做了什么

给它一个根目录和一个 URL 前缀，它会：

1. 分组：每个视频所在的最深一级目录成为它的分组（以该文件夹命名）。支持嵌套布局——library/课程/第一季/ep01.mp4 归入分组"第一季"。根目录下的散落文件归入以根目录名命名的分组，不会丢失。若两个不相关的文件夹同名（比如两套课程都有"第一季"），ZWScan 会用父目录消歧为 课程A/第一季、课程B/第一季，而不是合并。
2. 节目：每个视音频文件成为一个可播放节目（mp4、mkv、mov、webm、m3u8、mpd、flv、mp3、m4a、aac、wav）。
3. 匹配配套：为每个节目，在同一目录里查找同名前缀的配套文件并自动挂载——字幕、章节、标注、缩略图、水印、配音轨。
4. 输出：生成一份 ZWMAP/1.0 playlist.json，每个 URL 都带上你指定的 -prefix（通常是你的 ZWServe 地址）。

输出是符合标准的播放列表，ZWPlayer 可直接加载。

目录约定

ZWScan 读取你用 -dir 指定的根目录：

library/                       ← -dir 指向这里
├── intro.mp4                  ← 根目录散落文件 → 分组 "library"
├── intro.srt                  ←   自动匹配的字幕
├── 英语启蒙/                   ← 一个分组（组名 = 文件夹名）
│   ├── 01-ABC.mp4             ← 一个节目
│   ├── 01-ABC.srt             ← 自动匹配到 01-ABC.mp4 的字幕
│   ├── 01-ABC.chapter.json    ← 自动匹配的章节
│   ├── 02-Numbers.mp4
│   └── 02-Numbers.zh.srt      ← 带语言标签的字幕
├── Course/                    ← 支持嵌套布局
│   └── Season1/               ← 分组 "Season1"（取最深一级目录）
│       ├── ep01.mp4           ←   URL 保留完整路径：Course/Season1/ep01.mp4
│       └── ep02.mp4
├── Classic Cartoons/          ← 另一个分组
│   ├── ep01.mp4
│   ├── ep01_en.srt
│   └── ep01_ru.srt
└── playlist.json              ← 生成的输出（默认位置）

分组规则：包含视频的最深一级目录即为该视频的分组。-dir 根目录下的散落文件归入以根目录名命名的分组（这里是 “library”），不会被丢弃。嵌套子目录（Course/Season1/）按最后一级文件夹（“Season1”）分组，播放 URL 保留完整相对路径。若两个不相关的文件夹同名，ZWScan 会用父目录消歧（如 课程A/第一季、课程B/第一季）。

配套文件匹配规则

ZWScan 在同一目录下，按同名前缀匹配配套文件。以节目 01.mp4（基名 01）为例，它查找这些模式——.、_、- 都可作为分隔符：

字幕语言代码（zh、en、ja……）会自动展开为人类可读的标签（中文、English、日本語……），方便播放器的字幕菜单显示。匹配不到的字段就留空，不做猜测。

三端快速上手

下载对应系统的二进制，对你的媒体目录运行。

Windows

.\zwscan-win.exe -dir D:\videos -prefix http://192.168.1.20:8000

macOS（Apple Silicon）

chmod +x zwscan-macos
./zwscan-macos -dir ./library -prefix http://192.168.1.20:8000

Linux

chmod +x zwscan-linux   # ARM 设备用 zwscan-linux-arm64
./zwscan-linux -dir ./library -prefix http://192.168.1.20:8000

启动时 ZWScan 会打印扫描结果：

ZWScan — from zwplayer.com (local media → ZWMAP playlist scanner)
-------------------------------------------------
scanning : /home/me/library
prefix   : http://192.168.1.20:8000

[done] summary:
  output         : /home/me/library/playlist.json
  groups         : 4
  items          : 47
  subtitles      : 38
  chapters       : 12
  annotations    : 0
  thumbnails     : 0
  watermarks     : 0
  audio tracks   : 3

命令行参数

不带 -dir 或 -prefix 时，ZWScan 只显示用法并退出，不扫描。

完整工作流：ZWScan + ZWServe + ZWPlayer

ZWScan 是"本地文件夹 → 可播放网络媒体库"三步工作流的中间一环：

# 1. 扫描文件夹 → 生成 playlist.json（URL 带上服务器地址前缀）
zwscan -dir ./library -prefix http://192.168.1.20:8000 -out ./library/playlist.json

# 2. 通过 HTTP 提供该文件夹（带 CORS，让在线播放器能访问）
zwserv -dir ./library

# 3. 打开 ZWPlayer，加载播放列表地址
#    → http://192.168.1.20:8000/playlist.json

在 ZWPlayer 中加载后，每个分组和节目都会出现，字幕、章节、配音轨已自动接好——自动播放下一集、续播以及播放器的全部功能都能在你的本地媒体库上使用。

为什么要 URL 前缀？

因为 ZWPlayer 运行在浏览器里、通过 HTTP 加载视频，播放列表里需要指向你 ZWServe 实例的绝对 URL。ZWScan 把每个节目的 URL 拼成 <prefix>/<分组>/<文件>，所以你传入的就是即将用来提供服务的那个地址。

常见问题

不是视频的文件会怎样？

它们只用于配套匹配。.srt、.json、.jpg 永远不会成为节目——要么按文件名前缀匹配到某个视频，要么被忽略。

我的字幕叫 movie_zh.srt，不是 movie.zh.srt，能匹配吗？

能。ZWScan 接受 .、_、- 作为基名和语言/标签后缀之间的分隔符（movie.zh.srt、movie_zh.srt、movie-zh.srt 都能匹配 movie.mp4）。

生成后还能编辑吗？

当然——playlist.json 是标准的 ZWMAP/1.0 JSON。用在线播放列表编辑器打开，即可重新排序、改名、调整 URL，或补上 ZWScan 没找到的节目。

会递归扫描嵌套子目录吗？

会。ZWScan 会遍历 -dir 下的整棵目录树。每个视频的分组是它所在的直接（最深一级）父目录，所以 library/课程/第一季/ep01.mp4 会归入名为"第一季"的分组，播放 URL 保留完整相对路径。根目录下的散落文件归入以根目录名命名的分组。

总结

ZWScan 一条命令把视频文件夹变成一份带字幕、章节感知的完整 ZWMAP 播放列表。配合 ZWServe 提供目录服务、ZWPlayer 播放，即可获得一个完整的本地媒体库——分组、标注齐全，从任何浏览器都能播放——无需手动逐条建立播放列表。

• 🪟 Windows (.exe) · 🍎 macOS · 🐧 Linux x86 · 🐧 Linux ARM64
• ▶️ 打开 ZWPlayer 播放生成的播放列表
• ✏️ 播放列表编辑器 精修结果
• 🖥️ ZWServe 提供目录服务