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 使用（播放、字幕注入、暂停/恢复、续播）：

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 含开发者本机绝对路径，不适合作为其他环境的通用启动脚本。

首次连接

1. 启动 StreamPath。
2. 输入完整的 WebDAV 根地址，例如 http://192.168.2.124:5244/dav。
3. 输入用户名和密码并连接。
4. 连接成功后配置会写入 stream_path_config.json，下次启动自动连接。

右上角的断开连接只结束当前内存连接并返回登录页，不会删除已保存的账号配置。

浏览与排序

文件操作

• 单击目录进入下一级。
• 单击“返回上级目录”或面包屑返回指定层级。
• 单击视频或 STRM 启动播放。
• 普通文件和字幕文件目前只显示，不提供下载或预览操作。
• 右上角刷新按钮和下拉刷新会强制请求网络；失败时保留最后一次成功结果。

排序规则

浏览页始终保持“返回上级、目录、文件”三个分组，只改变组内顺序。

• 按名称：使用自然排序，E2 排在 E10 前。
• 按时间：正序为从早到晚，倒序为从晚到早；显示到同一分钟的条目再按名称排序，缺少时间的条目放在最后。
• 按体积：只排序普通文件，目录不计算总体积。纯目录页面会禁用该选项；已选中的体积参数不会因此被改写。

名称排序支持剧集编号、数字分段、全角数字、前导零、中文序数、罗马数字季名等常见格式。对于 视频名 - 2012、视频名 - 2013 这类名称，末尾由空格、横线或下划线分隔的数字也会参与排序；名称前后都有显式数字时，优先使用开头数字。

右上角临时排序和滚动位置只保存在内存中。设置页中的默认排序方式和方向会持久化，并在下次启动时生效。

播放与播放列表

单击可播放条目后，StreamPath 会收集当前目录的全部视频和有效 STRM，按后台自然名称正序创建播放列表，并从所选条目开始播放。浏览页临时切换到时间或体积排序不会改变播放列表顺序。

STRM 文件应包含一个可解析的媒体地址，可以是同源的绝对 HTTP/HTTPS URL，也可以是相对于 WebDAV 根地址的路径。为避免把认证信息发送给第三方，解析后的地址必须与当前 WebDAV 服务器同源。无效、跨源或读取失败的 STRM 会从本次播放列表中排除；所选 STRM 无法解析时会显示错误提示。

mpv 模式下还会提供：

• 播放列表与当前集标题。
• Basic 认证请求头。
• 播放进度保存和续播。
• 每个会话独立的状态、命令和临时脚本。
• 软件内暂停、恢复和关闭对应 MPV。

外挂字幕

字幕匹配必须同时满足：

1. 字幕与视频或 STRM 在同一个 WebDAV 来源。
2. 字幕与媒体条目位于完全相同的父目录。
3. 名称、季号和集号通过匹配规则。

支持的字幕扩展名为 .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。

播放器参数模板支持：

mpv 的字幕注入由 Lua 脚本完成，因此启动参数中的 {subfile} 不会作为 mpv 的 --sub-file 生效入口。非 mpv 播放器仍可使用该占位符。

默认 mpv 模板为：

--sub-file={subfile}
{url}
--start={start}

数据目录

源码目录内运行或从标准 Flutter build/... 产物运行时，数据通常位于项目根目录的 stream_path_data/。若项目根不可写，则回退到系统应用支持目录；脱离标准构建目录运行时，根目录定位还可能使用当前工作目录。

主要数据：

配置文件中的密码为明文，适合受信任的单机环境，不应把真实配置提交到版本控制或共享给他人。

旧版 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就好了