媒体服务器
& 智能流媒体

1.1 XteVision Media Server 是什么？

XteVision Media Server（xtevision-media-server v1.0.0）是一个本地视频流媒体服务器，从目录树通过网络提供影片和视频文件。它提供一个现代网页界面，可在任何浏览器中浏览、过滤和播放视频——客户端无需安装额外软件。它设计为可由任何企业进行再品牌化并运行。

1.2 核心功能

• 浏览器媒体库——所有视频以网格缩略图形式展示
• 文件夹分类——项目/客户作为过滤按钮
• 智能流媒体——对不支持的编解码器自动转码为 H.264
• 缩略图生成——自动从视频文件中提取
• 多语言——英语、德语、中文
• 深色/浅色模式——可切换设计
• 播放列表功能——自动播放下一个视频

1.3 目标用户

• 主要：需要通过局域网在任意浏览器中流式传输内部/制作视频（项目素材、客户录像、培训内容）的企业
• 次要：任何需要自托管、无客户端依赖、带智能编解码器回退功能媒体库的组织

2.1 高层架构

┌─────────────────────────────────────────────────────────────────┐
│                         浏览器（现代浏览器）                        │
│  ┌──────────┐ ┌──────────┐ ┌──────────────────────────────────┐  │
│  │ 视频网格   │ │ 分类      │ │ 视频播放器（HTML5 模态框）          │  │
│  │          │ │ 过滤       │ │ + 智能编解码器回退                 │  │
│  └──────────┘ └──────────┘ └──────────────────────────────────┘  │
└──────────────────────────────┬──────────────────────────────────┘
                               │ HTTP/REST API
┌──────────────────────────────┴──────────────────────────────────┐
│                    Node.js 服务器 — Express.js（端口 5002）         │
│  ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌──────────────────┐  │
│  │ /videos     │ │ /thumbnail  │ │ /video/    │ │ FFmpeg（转码）      │  │
│  │ （列表）     │ │ (JPEG)      │ │ original   │ │ H.264 + AAC        │  │
│  │             │ │             │ │ /h264      │ │                    │  │
│  └───────────┘ └───────────┘ └───────────┘ └──────────────────┘  │
└──────────────────────────────┬──────────────────────────────────┘
                               │
┌──────────────────────────────┴──────────────────────────────────┐
│                    文件系统（唯一事实来源）                           │
│  video/  →  文件夹树（分类）                                         │
│  .cache/ →  h264/ + thumbnails/                                     │
└───────────────────────────────────────────────────────────────────┘

2.2 通信流程

1. 前端 → 服务器：GET /videos 列出所有文件；GET /thumbnail/... 获取 JPEG；GET /video/original/... 和 GET /video/h264/... 流式传输媒体
2. 服务器 → 文件系统：readdirSync() 在每次 /videos 调用时读取 video/ 目录树
3. 服务器 → FFmpeg：缩略图和 H.264 转码按需生成，然后缓存

2.3 部署模型

XteVision Media Server 设计用于自托管、仅局域网运行：

• 作为独立的 Node.js 服务器运行在您自己的硬件上
• 无数据库——文件系统是唯一事实来源
• 无认证——专为本地局域网使用设计
• FFmpeg 通过 ffmpeg-static 内嵌

4.1 前置条件

• Node.js v18 或更高版本
• NPM（随 Node.js 安装）

4.2 安装

# 1. 切换到项目目录
cd /path/to/video_server

# 2. 安装依赖项
npm install

以下包将被安装：

4.3 启动服务器

npm start
# 或： node server.js

服务器将在 http://localhost:5002 上运行。成功启动时的控制台输出：

Using ffmpeg: /path/to/ffmpeg-static
Video server running at http://localhost:5002

4.4 在后台运行（Linux/macOS）

nohup node server.js > server.log 2>&1 &

5.1 视频目录

所有视频都位于项目目录下的 video/ 文件夹中。结构按客户/项目组织：

video/
├── Anting/
│   ├── anting.mp4
│   ├── biergarten720p.m4v
│   └── tiky_xuyun720p50.mp4
├── Porsche_VW/
├── Deutsche-Schule/
├── prodigy/
│   ├── prodigy_cn.mp4
│   ├── prodigy_de.mp4
│   └── prodigy_en.mp4
└── ...

5.2 添加新视频

1. 将视频文件复制到 video/ 的所需子文件夹
2. 重新加载网页——服务器在每次 /videos 调用时重新扫描目录

5.3 支持的格式

6.1 布局

位于 http://localhost:5002 的网页界面分为三个区域：

• 顶部栏：标题行、语言下拉框（English / Deutsch / 中文，保存在 localStorage）和主题切换按钮（深色/浅色）
• 分类（文件夹按钮）：所有找到的子文件夹作为过滤按钮；“全部”显示所有视频
• 视频网格：带缩略图、标题、文件夹名和播放按钮叠加的网格视图

6.2 视频播放器（模态框）

点击视频会打开一个叠加播放器：

• 带控件的 HTML5 视频播放器（播放/暂停、音量、全屏、时间线）
• 播放列表——当前分类的所有视频列表；自动跳转到下一个视频
• 关闭——点击 × 或按下 Esc

6.3 智能编解码器回退

播放器自动检测浏览器能否原生播放视频：

1. 检查 HEVC/H.265 支持——如果支持，则流式传输原始文件
2. 无 HEVC 支持——立即切换到 H.264 转码
3. 播放错误——自动回退到 H.264
4. 未检测到视频流——切换到 H.264

7.1 接口

7.2 示例

# 列出所有视频
curl http://localhost:5002/videos

# 获取缩略图
curl http://localhost:5002/thumbnail/Anting/anting.mp4

# 流式传输原始文件（带范围支持）
curl http://localhost:5002/video/original/Anting/anting.mp4

# 流式传输 H.264 转码版本
curl http://localhost:5002/video/h264/Anting/anting.mp4

[
  "Anting/anting.mp4",
  "Anting/biergarten720p.m4v",
  "prodigy/prodigy_cn.mp4"
]

8.1 H.264 流媒体

当视频无法原生播放时，服务器会将其自动转码为 H.264 + AAC——所有现代浏览器都可以播放的格式。

8.2 缩略图

• 帧位置——视频开始后 2 秒
• 分辨率——480px 宽度，比例高度
• 质量——JPEG 质量 2（高质量）
• 超时——每个缩略图 30 秒

为减轻服务器负担，缩略图生成会被放入队列，对同一缩略图的并发请求会被合并去重。生成的缩略图位于 .cache/thumbnails/，并在 24 小时内直接提供（Cache-Control: public, max-age=86400）。

8.3 缓存管理

.cache/
├── h264/          # H.264 转码视频
└── thumbnails/    # JPEG 缩略图

这两个目录镜像 video/ 的文件夹结构。要清空缓存（例如在更改原始文件后）：

# 删除缓存子目录
rm -rf .cache/h264/* .cache/thumbnails/*

# 或删除整个缓存文件夹
rm -rf .cache

9.1 服务器无法启动

• 端口已被占用：使用 lsof -i :5002 检查，然后结束进程（kill -9 [PID]）。
• FFmpeg 错误：Using ffmpeg: undefined 表示 ffmpeg-static 未正确安装——运行 npm install ffmpeg-static。

9.2 视频无法播放

• 播放器黑屏：浏览器不支持该编解码器。服务器应自动回退到 H.264——检查 .cache/h264/ 文件夹是否可写。
• “Video not found”（404）：检查文件是否存在于 video/ 目录中。含特殊字符的文件名需以 URL 编码形式提供。

9.3 缩略图不显示

• “Thumbnail generation failed”（500）：FFmpeg 无法读取视频——文件可能已损坏。检查 .cache/thumbnails/ 文件夹是否可写。
• 缩略图为黑色：视频在 2 秒处可能没有视频流（例如非常短的视频）。服务器默认取 2 秒处的帧（-ss 2）。

9.4 转码耗时过长

• 大视频（数 GB）需要时间进行 H.264 转码，这是正常的。第一次请求会阻塞直到转码完成；所有后续调用立即完成。