StreamPath
StreamPath 是一个面向 Windows 桌面的 WebDAV 媒体浏览器。它负责浏览远程目录、组织播放列表、匹配同目录字幕、调用外部播放器，并保存播放进度与继续播放记录。
项目默认针对 mpv 做完整增强；其他外部播放器可以播放直链，但不一定支持播放列表、字幕脚本、状态同步和进度回写等能力。
开发与维护说明见 PROJECT.md。
主要功能
- WebDAV
PROPFIND Depth: 1目录浏览，支持 Basic 认证。 - Hive 目录缓存、后台刷新和并发请求合并。
- 中文长路径缓存键摘要，避免 Hive 255 字符键限制导致目录为空。
- 名称、修改时间、文件体积排序，以及正序、倒序切换。
- 按目录与排序组合记忆滚动位置，软件重启后清除。
- 视频和 STRM 播放；STRM 内容会先解析为真实媒体地址。
- 同目录自然名称播放列表，从所选条目开始播放并自动切集。
- 严格限制在同源、同级目录内匹配外挂字幕。
- 外挂字幕“自动注入”和“自动选择”两个独立开关。
- 最多两个独立播放会话，分别跟踪对应 MPV 进程和播放状态。
- 播放进度、继续播放记录、暂停/恢复与定向关闭播放器。
- Windows 11 剪贴板历史右键菜单和 Win+V 粘贴兼容处理。
环境要求
- Flutter：使用支持
pubspec.yaml中 Dart SDK^3.12.2的版本。 - 桌面平台：Windows 10/11。
- WebDAV 服务：支持
PROPFIND，当前认证方式为 Basic Authentication。 - 推荐播放器：mpv。
Windows 开发环境还需要启用 Flutter Windows Desktop 工具链。
已测试的 MPV 版本
以下 64 位 MPV 构建均已实测可正常配合 StreamPath 使用（播放、字幕注入、暂停/恢复、续播）：
| 版本 | 构建 |
|---|---|
| 0.34.0 | mpv-0.34.0-x86_64 |
| 0.41.0 | mpv-v0.41.0-x86_64-pc-windows-msvc |
| 0.41.0-460-g2f6561947 | mpv-config 版（built on Apr 14 2026，libplacebo v7.362.0，FFmpeg N-123957） |
| lazy 260510 | mpv-lazy-20260510-noVS |
| shinchiro 260610 | mpv-x86_64-20260610-git-304426c |
32 位 MPV 不适用：实测无法正常播放签名链接，启动后立即闪退，请使用 64 位构建。
运行与构建
在项目根目录安装依赖：
flutter pub get
Windows 开发运行：
flutter run -d windows
Windows 构建（统一使用 Debug 模式，产物位于 build\windows\x64\runner\Debug\）：
flutter build windows --debug
当前 build.ps1 只包含 Windows 开发运行命令。run-d.ps1 含开发者本机绝对路径，不适合作为其他环境的通用启动脚本。
首次连接
- 启动 StreamPath。
- 输入完整的 WebDAV 根地址，例如
http://192.168.2.124:5244/dav。 - 输入用户名和密码并连接。
- 连接成功后配置会写入
stream_path_config.json，下次启动自动连接。
右上角的断开连接只结束当前内存连接并返回登录页，不会删除已保存的账号配置。
浏览与排序
文件操作
- 单击目录进入下一级。
- 单击“返回上级目录”或面包屑返回指定层级。
- 单击视频或 STRM 启动播放。
- 普通文件和字幕文件目前只显示，不提供下载或预览操作。
- 右上角刷新按钮和下拉刷新会强制请求网络；失败时保留最后一次成功结果。
排序规则
浏览页始终保持“返回上级、目录、文件”三个分组，只改变组内顺序。
- 按名称：使用自然排序，
E2排在E10前。 - 按时间：正序为从早到晚，倒序为从晚到早；显示到同一分钟的条目再按名称排序，缺少时间的条目放在最后。
- 按体积：只排序普通文件，目录不计算总体积。纯目录页面会禁用该选项；已选中的体积参数不会因此被改写。
名称排序支持剧集编号、数字分段、全角数字、前导零、中文序数、罗马数字季名等常见格式。对于 视频名 - 2012、视频名 - 2013 这类名称，末尾由空格、横线或下划线分隔的数字也会参与排序；名称前后都有显式数字时，优先使用开头数字。
右上角临时排序和滚动位置只保存在内存中。设置页中的默认排序方式和方向会持久化，并在下次启动时生效。
播放与播放列表
单击可播放条目后，StreamPath 会收集当前目录的全部视频和有效 STRM，按后台自然名称正序创建播放列表，并从所选条目开始播放。浏览页临时切换到时间或体积排序不会改变播放列表顺序。
STRM 文件应包含一个可解析的媒体地址，可以是同源的绝对 HTTP/HTTPS URL，也可以是相对于 WebDAV 根地址的路径。为避免把认证信息发送给第三方，解析后的地址必须与当前 WebDAV 服务器同源。无效、跨源或读取失败的 STRM 会从本次播放列表中排除；所选 STRM 无法解析时会显示错误提示。
mpv 模式下还会提供：
- 播放列表与当前集标题。
- Basic 认证请求头。
- 播放进度保存和续播。
- 每个会话独立的状态、命令和临时脚本。
- 软件内暂停、恢复和关闭对应 MPV。
外挂字幕
字幕匹配必须同时满足：
- 字幕与视频或 STRM 在同一个 WebDAV 来源。
- 字幕与媒体条目位于完全相同的父目录。
- 名称、季号和集号通过匹配规则。
支持的字幕扩展名为 .srt、.ass、.vtt、.ssa、.sub、.sup、.idx、.smi。匹配规则会识别 S01E01、1x01、E01、EP01、第01集、纯数字集号，以及常见语言和字幕属性后缀。
设置页提供两个开关：
- 自动注入匹配的外挂字幕：搜索同目录字幕并加入 MPV 字幕轨道。
- 自动选择已注入的外挂字幕：注入后切换到外挂字幕；关闭时保留注入前的内封字幕或无字幕状态。
自动选择依赖自动注入。关闭自动注入后，自动选择项会变灰且不生效。多集播放时，每次自动或手动切集都会根据当前 playlist-pos 注入该集对应字幕；关闭自动选择不会关闭逐集注入。
自动注入开启时，StreamPath 会向 mpv 添加 --sub-auto=no，避免 mpv 配置中的字幕搜索路径加载其他目录的字幕。
继续播放栏
浏览页底部最多保留两个播放会话，新会话显示在上方，较早的会话显示在下方。每个会话独立保存：
- 当前目录和文件名。
- 播放列表与当前位置。
- MPV PID、IPC 标识、状态文件和命令文件。
- 正在打开、正在播放、已暂停或继续播放状态。
播放栏支持：
- 点击暂停或恢复对应 MPV。
- 播放器退出后继续播放。
- 删除按钮或右键菜单删除记录并关闭对应播放器。
- 播放位置已满时阻止第三个会话并显示提示。
新启动的 MPV 在写出首个有效播放状态前会进入启动保护期，底栏保持“继续播放”。StreamPath 每秒探测一次对应进程；超过配置等待时间仍未激活时，会定向终止该会话进程并清除底栏。
直接关闭 MPV 后，未播放完成的会话会稳定切换为“继续播放”。仅当 MPV 已退出且最后上报进度达到 99%，或播放列表明确结束时，该会话才会隐藏；MPV 仍在运行时不会因达到 99% 提前隐藏。
播放进度
播放进度按媒体 URL 存入 SQLite。重新播放时，若时长已知且距离片尾不足一分钟，则视为已看完并从头开始；时长未知不会自动判定为已看完。
mpv 使用独立的 watch_later 目录保存原生进度，播放器退出后 StreamPath 再将结果同步到自己的进度库。
设置与配置
设置页可修改：
- 播放器名称、可执行文件和参数模板。
- 隐藏文件后缀。
- 默认排序方式与排序方向。
- WebDAV 地址、用户名和密码。
- 外挂字幕自动注入和自动选择。
- 自动续播。
配置文件还支持手工修改 playerStartupTimeoutSeconds，用于控制 MPV 启动保护的最长等待秒数。默认值为 60，允许范围为 5 到 3600。
播放器参数模板支持：
| 占位符 | 含义 |
|---|---|
{url} |
媒体地址 |
{subfile} |
匹配到的字幕地址，主要用于非 mpv 播放器 |
{start} |
续播秒数 |
mpv 的字幕注入由 Lua 脚本完成，因此启动参数中的 {subfile} 不会作为 mpv 的 --sub-file 生效入口。非 mpv 播放器仍可使用该占位符。
默认 mpv 模板为：
--sub-file={subfile}
{url}
--start={start}
数据目录
源码目录内运行或从标准 Flutter build/... 产物运行时，数据通常位于项目根目录的 stream_path_data/。若项目根不可写，则回退到系统应用支持目录；脱离标准构建目录运行时，根目录定位还可能使用当前工作目录。
主要数据：
| 路径 | 用途 |
|---|---|
stream_path_config.json |
WebDAV、播放器、字幕开关、隐藏后缀和默认排序 |
playback_history.json |
最多两个继续播放会话 |
streampath.db |
播放进度 SQLite |
directory_cache/ |
Hive 目录缓存 |
mpv-watch-later/ |
mpv 续播记录和会话脚本 |
mpv-current-<会话>.txt |
MPV 状态上报 |
mpv-command-<会话>.txt |
暂停和恢复命令 |
clipboard_history_fix.log |
Windows 剪贴板诊断日志，仅 Debug 构建 |
配置文件中的密码为明文，适合受信任的单机环境，不应把真实配置提交到版本控制或共享给他人。
旧版 player_config.json 和 connection_config.json 会在迁移时合并到统一配置。旧字段 subtitleEnabled 会同时迁移为字幕注入和自动选择开关。
清理运行数据
保留配置并清除缓存、进度、播放历史和 MPV 临时数据：
.\cleanup.ps1
保留继续播放记录：
.\cleanup.ps1 -KeepHistory
清理脚本只适用于 PowerShell，并会同时尝试清除旧版本遗留的数据目录。
Windows 剪贴板支持
Windows 输入框右键菜单会显示最近五条应用内剪贴板历史，并提供粘贴当前剪贴板与清空历史。Windows 11 的 Win+V 合成按键兼容逻辑只在 Windows 启用。
常见问题
目录内容不完整，刷新也没有恢复
先确认 WebDAV 服务实际返回了条目。StreamPath 已对长中文 URL 使用固定长度缓存键，缓存写入异常不会阻断网络结果；刷新失败时界面会保留最后一次成功快照。必要时使用 cleanup.ps1 清除目录缓存后重试。
字幕没有注入
确认“自动注入匹配的外挂字幕”已开启，并检查字幕是否与媒体位于同源、同级目录。剧集编号冲突会被明确拒绝，例如 S01E01 不会匹配 S01E23。
字幕已注入但没有自动显示
确认“自动选择已注入的外挂字幕”已开启。该选项关闭时，外挂字幕只进入轨道列表，当前内封字幕保持不变。
无法启动播放器
在设置页填写有效的播放器命令名或可执行文件路径。命令名需要位于系统 PATH；文件路径会在保存前校验。
STRM 无法播放
确认文件内容包含一个有效地址，并且 StreamPath 能通过当前 WebDAV 账号读取该文件。绝对地址必须与当前 WebDAV 服务器同源；也可以使用基于 WebDAV 根地址补全的相对路径。
续播从头开始
时长已知且距离片尾不足一分钟的记录会被视为已看完。除此之外，检查 mpv 是否能写入 mpv-watch-later/，以及数据目录是否可写。
质量检查
flutter analyze
flutter test
当前测试覆盖目录解析与缓存、排序、字幕匹配、STRM、播放器参数、MPV 会话、进度和播放历史、配置迁移、文件列表组件及 Windows 剪贴板逻辑。
已知维护事项
- scripts/fix-cargokit-symlinks.ps1 当前包含未解决的 Git 合并冲突标记，修复前不要执行。
- run-d.ps1 使用开发者本机绝对路径，需要改为当前环境路径后才能使用。
项目地址
https://github.com/Yufuxk/StreamPath-Openlist-MPV-MPV-Openlist-
我发的第一个Github项目，要是有人能给我点点Star就好了
专辑简介
简介
基本信息
曲目列表 (Tracklist)
特典 BD 影像（Blu-ray Disc）