StreamPath
[image: 1786015969686-icon.png]
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就好了
