本地视频画廊 Web 服务 — 双击启动，浏览器里浏览、搜索、播放你的整个视频库

当前版本：7.0.0（主分支） · 分类树重构、文件夹增删改、事件委托优化

扫描本机视频目录，自动生成缩略图网格，支持分类筛选、收藏、播放记录、我的专辑、内嵌 HLS 播放与外部播放器。专为 Windows 本地大库设计：新视频拷入即索引，下载中的文件不误报失败，外部删除自动同步收藏、历史与专辑归属。

默认访问地址： http://127.0.0.1:3456

演示数据为风景图占位，非真实视频库内容。

画廊浏览 — 左侧分类与子目录树，网格分页浏览整个视频库。

内嵌播放 — 页面内播放器与右侧播放列表；支持排序、上一个/下一个、HTML5 连播。

我的收藏 — 一键筛选已收藏视频，卡片左上角显示红心标记。

最近播放 — 按播放时间倒序浏览，快速回到上次看到的内容。

设置 — 视频库管理、全局播放与缩略图选项；自动探测 PotPlayer 路径。

批量选择 — 多选后批量收藏、移动、删除，底部浮出操作栏。

管理本地视频库，常见痛点是：

• 文件夹里找 → 没有预览，文件名又长又乱
• 播放器自带库 → 分类弱、缩略图慢、特殊格式搞不定
• NAS / 媒体服务器 → 配置重、要常驻服务、个人单机用不上
• 下载还没完 → 被索引后缩略图失败，满屏报错

Loc Gallery 的做法是：只在本机跑一个轻量 Web 服务，浏览器当界面，ffmpeg 当引擎。文件怎么放磁盘就怎么扫，不搬家、不转码入库；能直传就直传，搞不定的再 HLS。下载中的文件会等稳定后再处理，不会污染失败列表。

• 在 Windows 上管理大量本地视频（多分类目录、多格式混放）
• 希望浏览器快速浏览缩略图，偶尔内嵌播放或调 PotPlayer
• 需要收藏、播放记录、批量整理，但不需要多用户 / 公网 / 刮削元数据
• 视频库里有伪装格式（如 PNG 头 + MPEG-TS）或大体积文件需要 HLS 起播

不适合： 多用户远程访问、移动端 App、TMDB 刮削、云端同步。

详细功能规格见 PRD.md。

从「视频在磁盘上」到「浏览器里能看能播」，整条链路分 4 个阶段：

① 扫描索引 — watchdog 多库监听 + 稳定检测 → scanner 按库缓存 → 内存索引 + 版本号
         ↓
② 缩略图   — 当前页高优先级排队 → ffmpeg 抽帧 → data/libraries/{id}/.thumbs/
         ↓
③ 播放策略 — ffprobe 探测编码/封装 → 写入 playback_plans.json → 选择 direct / HLS
         ↓
④ 前端展示 — SSE 推送进度 → 网格卡片 + 播放器弹层 + 收藏/历史视图

下载中文件的处理：

文件变更事件 → 加入「待稳定」队列 → 等待 size/mtime 不再变化
         ↓
通过稳定性检测 → 纳入索引 → 排队缩略图 & 播放探测
         ↓
若曾被误标失败 → reconcile 重置为「等待」，不计入失败列表

┌─────────────────────────────────────────────────────────┐
│                    浏览器 (static/)                      │
│  index.html · app.js · style.css · hls.js               │
└────────────────────────┬────────────────────────────────┘
                         │ HTTP / SSE
┌────────────────────────▼────────────────────────────────┐
│              FastAPI (loc_gallery.server)                │
│  REST API · 静态资源 · SSE 事件推送                       │
├──────────┬──────────┬──────────┬──────────┬─────────────┤
│  scanner  │thumb_mgr │hls_mgr   │media_probe│library/    │
│          │          │          │          │favorite/    │
│          │          │          │          │history/     │
│          │          │          │          │album_store  │
└────┬─────┴────┬─────┴────┬─────┴────┬─────┴──────┬──────┘
     │          │          │          │            │
     ▼          ▼          ▼          ▼            ▼
  各库视频根   libraries/  cache/hls  playback    favorites.json
  目录        {id}/.thumbs            _plans.json play_history.json
              libraries.json          albums.json

<项目根目录>/
├── README.md                   # 本文件
├── PRD.md                      # 产品需求文档（功能/API 规格）
├── restart.py                  # 一键重启（先停后起，打开浏览器）
├── pyproject.toml
├── requirements.txt
├── scripts/
│   ├── service.py              # 启停共享逻辑
│   └── build-css.bat           # Tailwind 编译
├── src/loc_gallery/            # Python 后端包
│   ├── config.py               # 端口、常量；VIDEO_ROOT 为默认库种子
│   ├── library_store.py        # 多视频库注册与 CRUD
│   ├── library_context.py      # 请求级当前库上下文
│   ├── server.py               # FastAPI 入口
│   ├── scanner.py              # 视频索引
│   ├── thumb_manager.py        # 缩略图队列
│   ├── media_probe.py          # 播放策略探测
│   ├── hls_manager.py          # HLS 切片缓存
│   ├── favorite_store.py       # 收藏
│   ├── history_store.py        # 播放历史
│   ├── album_store.py          # 我的专辑
│   └── file_stability.py       # 下载/写入稳定性检测
├── static/                     # 前端静态资源
├── tests/                      # 集成测试（含 test_multi_library.py）
├── config/
│   └── settings.example.json   # 设置模板
└── data/                       # 运行时数据（gitignored）
    ├── settings.json           # 全局设置
    ├── libraries.json          # 已注册视频库列表
    ├── libraries/
    │   └── {library_id}/       # 每库独立：收藏、历史、专辑、缩略图、HLS 缓存等
    └── logs/

把下面这段提示词复制到 Cursor / OpenCode / Claude Code 等 AI 聊天框发送，AI 会自动完成安装与配置：

请调研 https://github.com/hoolulu/Loc-Gallery 项目，按照 README 依次完成本机安装：

1. 克隆仓库到合适目录（Windows）
2. 确认 Python 3.11+ 可用，执行 pip install -r requirements.txt
3. 确认 ffmpeg 与 ffprobe 在 PATH 中可用（不可用则协助安装，如 WinGet）
4. 询问我的视频库根目录路径，并写入 src/loc_gallery/config.py 的 VIDEO_ROOT
5. 若 data/settings.json 不存在，从 config/settings.example.json 复制并按需配置
6. 运行 python restart.py 启动服务，确认 http://127.0.0.1:3456 可访问
7. 简要说明如何日常使用（重启、设置页、收藏与最近播放）

每完成一步都确认结果，最后总结安装状态与访问地址。不要提交或上传 data/ 目录中的任何文件。

AI 会读取项目文档 → 检测本机环境 → 逐项安装配置 → 启动验证。你只需提供视频库路径即可。

git clone https://github.com/hoolulu/Loc-Gallery.git
cd Loc-Gallery

或将 Release 解压到任意目录（下文记为 <项目根目录>）。

cd <项目根目录>
pip install -r requirements.txt
# 或开发模式：pip install -e .

编辑 src/loc_gallery/config.py 中的 VIDEO_ROOT 作为首个默认库的种子路径，例如：

VIDEO_ROOT = Path(r"F:\AVV")

启动后可在设置 → 视频库中添加更多库，或使用顶栏「选择视频库」切换。也可将 config/settings.example.json 复制为 data/settings.json。

python restart.py

浏览器将自动打开 http://127.0.0.1:3456。

修改了 static/tw-input.css 或 Tailwind 类名后：

scripts\build-css.bat

提示： 服务绑定 127.0.0.1:3456，设计为本机使用。PotPlayer 等外部播放器路径请在启动后的设置页配置，勿写入公开仓库。

• 顶栏 选择视频库 下拉切换；URL 支持 ?lib= 参数
• 设置 → 视频库：管理现有库（别名、路径）、一次性添加新库（别名 + 路径 + 浏览）
• 收藏、历史、缩略图、HLS 缓存、分类元数据按库隔离；播放/缩略图等为全局设置

• HTML5 模式下，右侧播放列表可按文件名（自然排序）、标题、时间、大小等排序
• 设置中可开关 播完自动下一集、记忆播放位置（续播）
• 续播：进度写入 play_history.json；再次打开从上次位置继续（≥15 秒且距结尾 ≥45 秒）；直连与 HLS 均支持
• HTML5 直传读盘：/api/stream 按 256KB 分块推送，播放缓冲接近视频码率，退出后尽快停止读盘（详见 CHANGELOG 3.0.0）
• HLS 切片：每段 30 秒；播放器暂停时挂起 ffmpeg，继续播放时恢复
• 追剧建议：筛选到目标文件夹后，每页选「全部」，列表排序选「文件名 A→Z（自然）」

1. 启动服务后，左侧选择分类，下方可展开子目录树
2. 顶栏搜索框支持标题、文件名、分类关键词
3. 点击卡片播放；悬停 ♥ 收藏、📁 管理专辑
4. ♥ 我的收藏 / ⏱ 最近播放 / 📁 我的专辑 切换顶栏视图
5. 格式下拉筛选特殊封装；可修复项右键「修复为标准 MP4」

• 顶栏 📁 我的专辑：新建、编辑、删除专辑；点击进入专辑详情
• 加入专辑：右键菜单、批量栏、播放器按钮；勾选对话框支持新建并加入
• 本页生成专辑：浏览页工具栏，将当前页视频一次性加入新专辑
• 专辑详情：播放全部、视频数/总时长、右键「设为专辑封面」
• 数据按库隔离：data/libraries/{id}/albums.json；删视频自动从专辑移除
• 升级含专辑功能的版本后须重启服务（restart.py），否则 /api/albums 返回 404

• 顶栏进度条显示全库 / 当前页 / 队列状态
• 默认仅按需生成当前浏览页；可在设置中开启「后台补全全库」
• 可暂停队列、重试失败项、清理孤儿缓存

在设置中选择：

播放策略自动缓存，常见场景：

「批量」模式下可多选，执行删除（回收站）、移动、批量收藏、加入专辑、修复 MP4。

在设置面板中统一保存至 data/settings.json（完整列表见 PRD.md §4.10）：

cd <项目根目录>
$env:PYTHONPATH = "<项目根目录>\src"
python -m uvicorn loc_gallery.server:app --host 127.0.0.1 --port 3456 --reload

# 部分测试需先启动服务
python tests\test_auto_new_video.py
# 伪装格式测试需本机样本，不内置路径：
# $env:LOC_GALLERY_DISGUISED_SAMPLE = "D:\path\to\sample.mp4"
python tests\test_disguised_pipe.py
python -m pytest tests\test_file_stability.py
python -m unittest tests.test_album_store tests.test_album_api tests.test_multi_library -v
python scripts/test_album_e2e.py   # 需已启动服务

本项目设计为纯本地、单用户使用。分享代码或打包给他人时，请注意：

源码中不应出现：

• Windows 用户名（如 C:\Users\...）
• 本机软件安装路径（PotPlayer 等请在设置里配置，不要写进 config.py）
• 真实视频文件名（测试脚本通过环境变量传入样本）

视频库路径 VIDEO_ROOT（如 F:\AVV） 仅保留在你本机的 config.py 中即可，无需为了分享而修改——对方克隆后会改成自己的路径。

.gitignore 已默认忽略 data/ 与 server.log。若初始化 Git 仓库，请勿将上述运行时文件加入版本库。

1. 视频库放哪？项目放哪？

• 视频库：在设置 → 视频库管理中配置（支持 Windows 文件夹选择器）；config.py 的 VIDEO_ROOT 仅作首次迁移默认种子
• 项目：任意目录均可；扫描时会自动忽略 Loc-Gallery / loc-gallery 等项目自身目录名

2. 下载中的视频为什么之前会显示缩略图失败？

文件仍在写入时 size/mtime 持续变化，ffmpeg 抽帧会失败。现在会等文件稳定后再索引和生成缩略图；已误标的失败状态会自动重置。

3. 外部删除了视频，收藏和历史还在吗？

不会。文件删除触发库刷新后，会自动从当前库的 favorites.json、play_history.json 与 albums.json 中移除对应条目。

4. 点击「我的专辑」报 Not Found？

说明后端仍是旧进程。运行 restart.py 或在设置页「重启服务」，并 Ctrl+F5 强刷页面。

5. 多个视频库的数据存在哪？

data/libraries.json 登记库列表；每库数据在 data/libraries/{library_id}/（收藏、历史、专辑、缩略图、HLS 缓存等）。全局设置在 data/settings.json。

6. 能暴露到局域网或公网吗？

不建议。服务无认证，设计为 127.0.0.1 本机使用。若改 HOST 请自行评估风险。

7. 伪装 MPEG-TS 是什么？

部分文件扩展名为 .mp4，文件头却是 PNG 魔数，偏移后为 MPEG-TS 流。探测后使用 -f mpegts 切片，详见 PRD 附录。

8. HLS 缓存占多少磁盘？

默认上限 5GB（LRU 淘汰）。2.1.0 起每段 30 秒（旧版 6 秒），同样时长影片产生的 .ts 文件更少。已有 6 秒缓存会在升级后自动作废并重新切片。

9. 续播进度存在哪？

data/libraries/{library_id}/play_history.json 的 position_sec 字段；HTML5 直连与 HLS 均支持。HLS 边切边播时，若目标位置尚未切片完成，可能需要等待缓冲。

常见问题：

• 端口 3456 被占用 → 再运行一次 restart.py（会先停旧进程）
• 缩略图全失败 → 检查 ffmpeg -version 是否在 PATH 中
• 播放黑屏 → 查看播放策略是否为 unsupported，或等待 HLS 切片完成

1. 主要为 Windows 环境优化
2. 单用户本地，无认证
3. 大库首次打开当前页时，缩略图按需生成，可能有短暂等待
4. H.264 转码播放 CPU 占用较高

私有项目，仅供个人使用。

Loc Gallery — 本地视频，浏览器里看。

讨论与交流 → LINUX.DO 社区