v0.9.0

v0.9.0 Release Notes

新特性：硬件加速转码

概述

新增 FFmpeg 硬件加速编码支持，视频转码可自动利用 GPU 完成，大幅提升转码速度并降低 CPU 占用。
启动时自动探测可用硬件编码器，无需手动配置即可生效；不可用时无感回退到原有软件编码。

支持的硬件编码器

编码器	平台	说明
h264_nvenc	Windows / Linux	NVIDIA GPU
h264_qsv	Windows / Linux / macOS	Intel Quick Sync
h264_amf	Windows	AMD AMF
h264_vaapi	Linux	VA-API
h264_videotoolbox	macOS	Apple VideoToolbox

配置项

config.json 新增 playback.video.encoding 字段：

{
  "playback": {
    "video": {
      "encoding": {
        "hwAccel": "auto",
        "maxJobs": 0
      }
    }
  }
}

• hwAccel — 硬件加速模式（默认 "auto"）
  • auto：启动时自动探测最佳编码器
  • nvenc / qsv / amf / vaapi / videotoolbox：强制指定
  • none：禁用硬件加速，始终使用 libx264
• maxJobs — 最大并发转码数（默认 0 即自动：软件 2 路，硬件 4 路）

兼容性

• 旧版 config.json 升级时 ApplyDefaults() 自动补全 encoding 字段并回写磁盘
• 无硬件编码器的环境行为与 v0.8.x 完全一致（libx264 fast preset）
• 运行时硬件编码失败自动标记禁用，后续请求无感切回软件编码

变更文件

新增

• internal/media/hwaccel.go — 硬件加速探测、缓存、参数生成、运行时回退
• internal/media/hwaccel_test.go — 探测逻辑单元测试（11 个用例）

修改

• internal/media/transcoder.go — 视频编码参数委托 BuildVideoArgs() 统一出口；新增 SetTranscodeLimit() 支持动态并发上限
• internal/media/transcoder_test.go — 补充 SetTranscodeLimit 测试
• internal/config/config.go — 新增 TranscodeConfig 结构体及 PlaybackVideoConfig.Encoding 字段；Default() 和 ApplyDefaults() 补全默认值
• internal/config/validate.go — 新增 validateTranscodeConfig() 验证 HWAccel 白名单和 MaxJobs 非负
• internal/config/validate_test.go — 补充 7 个验证测试用例
• cmd/msp/main.go — 启动时调用 initHWAccel() 探测硬件并设置并发上限
• config.example.json — 补充 encoding 字段
• docs/CONFIG_EXAMPLE.md — 补充 encoding 配置说明（含各模式注释）
• docs/API_REFERENCE.md — 配置响应示例展开 playback.video.encoding

验证

• go vet ./... ✅
• go test ./internal/media/... ✅（全部通过，含硬件探测）
• go test ./internal/config/... ✅（全部通过，含新验证用例）
• go build ./cmd/msp ✅

影响评估

• 不引入新外部依赖，仅依赖系统已有的 FFmpeg
• 不改动 API 协议，仅扩展配置 schema（向后兼容）
• 对无硬件加速的环境零影响，行为与 v0.8.x 完全一致

v0.8.12

v0.8.12 Release Notes

核心修复

1) 播放策略精修（家庭场景）

• 预转码策略收敛为仅 AVI/WMV 容器触发，避免 MP4 等常见可直连格式被误判。
• 继续保持“直连优先 -> 失败回退转码”的低侵入链路。

2) 播放器稳定性增强

• 媒体错误回调增加全链路兜底，避免异常二次抛出导致播放器状态污染。
• 转码回退切源逻辑增加实例守卫：Plyr 不可用时自动降级到原生 <video>/<audio>。
• 修复智能拖动分支中的变量作用域问题，避免潜在运行时错误。

3) WMV 兼容补强

• 前端 MIME 映射补全：.wmv -> video/x-ms-wmv。
• 预转码日志与行为描述统一，便于排障。

验证

• go test ./...
• go vet ./...
• golangci-lint v2 run（0 issues）
• pnpm -C web run build

影响评估

• 不引入新依赖，不改动 API 协议。
• 仅优化播放判定与错误兜底路径，对已有正常直连场景保持兼容。

v0.8.11

MSP v0.8.11 变更说明

概述

v0.8.11 聚焦播放器兼容性与稳定性，目标是在家庭局域网场景下做到：

• 兼容格式优先直连，不无谓转码
• 不兼容格式自动兜底，减少“能播却报错”与“该转不转”两类问题
• 变更低侵入，保持现有配置与接口稳定

核心策略

本版本采用“探测感知 + 直连优先 + 单次回退”的播放决策：

1. 直连优先

• 默认先走原始流直连播放。

2. 预转码触发（仅高风险）

• 对 AVI/WMV 容器直接预转码，避免浏览器下载弹窗或硬失败。
• 对 probe 探测出的高风险编码组合预转码：
  • 视频：HEVC/H.265、VC-1、WMV3、MPEG-2
  • 音频：AC-3、E-AC-3、DTS、TrueHD

3. 失败回退（单次）

• 直连失败时先做一次带新 ts 参数的同源重试（处理瞬时错误）。
• 若仍失败且配置开启了转码，自动切换转码流。

问题修复

• 修复播放器错误处理中的变量遮蔽问题，消除前端运行时异常：
  • TypeError: c is not a function
• 增加媒体切换阶段的空 src 错误保护，避免误报“永久播放失败”。

WMV 支持补全

• 扫描分类补全：.wmv 归类为 video
• 响应头补全：.wmv -> video/x-ms-wmv

兼容性与风险

• 配置项无新增，无破坏性变更。
• 常见 MP4(H.264/AAC) 不会因为开启转码而默认走转码。
• 仅在高风险编码或真实失败时才触发转码，CPU 使用更可控。

验证

• 前端构建：pnpm -C web build 通过
• 后端测试：go test ./... 通过

涉及文件

• web/src/modules/player.js
• web/src/modules/api.js
• internal/media/scanner.go
• internal/handler/handlers.go
• internal/media/scanner_test.go
• internal/handler/handler_test.go

v0.8.10

MSP v0.8.10 变更说明

概述

本版本是一次低侵入、安全优先的后端稳健性优化，重点解决以下问题：

• 多个 API 端点缺少请求体大小限制，存在内存消耗风险
• 媒体列表 limit 参数语义不准确，可能误导客户端状态
• 字幕转码路径对超大文本文件缺少保护
• PIN 登录会话 Cookie 在 HTTPS 代理场景下未自动启用 Secure

本次改动仅涉及 internal/handler，不更改路由结构，不引入新依赖，不调整业务模型。

变更目标

• 在不影响既有可用性的前提下，提升接口抗滥用能力
• 保持 API 主体语义和调用方式稳定
• 通过可验证测试覆盖关键行为边界

详细变更

1. 统一 JSON 请求体限流（1 MiB）

新增统一解码入口并用于关键 POST 接口：

• HandleConfig
• HandleShares
• HandlePrefs
• HandleProgress（POST）
• HandleLog
• HandlePIN

实现要点：

• 使用标准库 http.MaxBytesReader，不重复造轮子
• 限制值固定为 1 MiB（常量 defaultJSONBodyLimit）
• 超限返回 413 Request Entity Too Large
• 非超限解析错误维持 400 语义

收益：

• 避免异常大请求体直接进入 JSON 解码导致内存压力
• 行为统一，后续维护成本更低

2. 修复 limit 截断标记语义

优化函数 applyLimit：

• 之前：limit > 0 即统一标记 Limited=true
• 现在：仅在任一媒体集合实际发生截断时标记 Limited=true

收益：

• 消除“未截断却标记已截断”的误导
• 让前端状态展示与真实数据保持一致

3. 字幕转换增加大文件保护（8 MiB）

在 serveSRT 与 serveASS 增加文件大小检查：

• 超过 8 MiB（常量 maxSubtitleConvertSize）直接返回 413
• 保留原有转换逻辑（SrtToVtt / AssToVtt）不变

收益：

• 降低 io.ReadAll 面对异常字幕文件时的内存风险
• 变更面小，不影响常规字幕场景

4. 家庭局域网模式下移除 HTTPS 推断逻辑

调整内容：

• PIN 会话 Cookie 固定 Secure=false
• 不再依据 TLS 或 X-Forwarded-Proto 动态切换
• 客户端 IP 固定从 RemoteAddr 提取，不再信任 X-Forwarded-For / X-Real-IP

收益：

• 行为更符合家庭局域网直连场景
• 配置与运行路径更简单，可预测性更高

影响评估

兼容性

• 路由：无变化
• 请求参数：无变化
• 响应结构：主体保持兼容
• 新增状态码：部分超限场景会由 400 提升为 413

性能

• 正常流量开销可忽略（一次限长包装与分支判定）
• 在恶意/异常流量下可明显降低内存消耗风险

风险控制

• 仅修改 handler 层
• 全部采用 Go 标准库能力
• 不涉及并发模型与数据库结构变更

测试与验证

新增测试文件：

• internal/handler/handlers_safety_test.go

新增覆盖点：

• applyLimit 仅在真实截断时返回 true 且设置 Limited=true
• PIN 会话 Cookie 在家庭模式下固定非 Secure
• HandlePIN 对超大请求体返回 413
• serveSRT 对超大字幕文件返回 413

回归验证：

• 执行 go test ./... 全量通过

涉及文件

• internal/handler/handlers.go
• internal/handler/handlers_safety_test.go

结论

v0.8.10 在保持现有功能与调用方式稳定的前提下，完成了四项关键稳健性提升。改动聚焦、可验证、可回溯，适合直接进入常规发布流程。

v0.8.9

MSP v0.8.9 发布说明

代码质量修复

v0.8.9 专注于修复 golangci-lint 检测到的代码质量问题，提升代码健壮性和安全性。

修复内容

• 错误处理完善: 修复 test 文件中未检查的错误返回值（errcheck）

  • pin_test.go: 6 处 resp.Body.Close() 错误检查
  • pin_test.go: 1 处 os.RemoveAll() 错误检查

• 安全权限修复: 修复文件操作权限过于宽松的问题（gosec）

  • scanner_test.go: 3 处 os.MkdirAll 权限 0755 → 0750
  • scanner_test.go: 15 处 os.WriteFile 权限 0644 → 0600
  • transcoder_test.go: 3 处 os.WriteFile 权限 0644 → 0600

• 代码简化优化:

  • scanner.go: 简化 ClassifyExt 函数，移除复杂的长度分支逻辑，降低圈复杂度
  • transcoder.go: 应用 De Morgan 定律简化条件表达式
  • server.go: 删除未使用的 sessionTimer 字段
  • server.go: 修复 for i := range 8 为 for i := 0; i < 8; i++

技术改进

• 所有 golangci-lint 检测问题已清零
• 测试文件安全性提升
• 代码可维护性改善

v0.8.7 - Code Quality Refactor

MSP v0.8.7 发布说明

🛠️ 维护性更新 (Maintenance Release)

v0.8.7 作为常规维护版本，主要聚焦于系统稳定性与底层优化，确保服务长期运行的可靠性。

更新内容

• 底层优化：例行代码清理与性能微调
• 稳定性提升：持续改进异常处理边界场景
• 依赖更新：同步上游安全补丁

兼容性

• 无破坏性改动
• 配置文件向下兼容

升级指南

1. 下载最新二进制文件
2. 替换旧版本可执行文件
3. 前端资源已内嵌，无需额外操作

v0.8.6

MSP v0.8.6 发布说明

🧹 代码质量重构 (Refactor & Maintainability)

v0.8.6 以内部重构为主：围绕媒体扫描、入库、响应构建与部分 API Handler 逻辑做了结构化拆分，降低圈复杂度并提升可维护性。

兼容性

• 无破坏性改动

升级指南

1. 下载最新二进制文件。
2. 前端资源已内嵌，无需额外操作。

v0.8.5

MSP v0.8.5 发布说明

🎨 UI 细节打磨 & 播放体验优化 (Polished UI & Better Player)

v0.8.5 专注于提升视觉的一致性与播放器的稳定性，让整体体验更加细腻优雅。

1. UI 优雅升级 (UI Refinement)

• 圆角美学：视频播放器与预览图片彻底告别直角，统一采用全局圆角设计，视觉更加柔和，与整体 Material Design 风格完美融合。
• 列表对齐：修复了无文件名（仅有图标）的列表项高度与其他项不一致的问题，列表布局更加整齐。
• 控件微调：优化了输入框 (Input) 与按钮 (Button) 的样式，特别是在暗黑模式 (Dark Mode) 下的色彩表现，质感显著提升。

2. 播放器增强 (Player Enhancements)

• Tooltip 完美显示：通过重构容器 CSS，以非侵入式的方式解决了 Plyr 进度条提示气泡被播放器边框遮挡的问题。
• 稳定性修复：修复了在快速切换视频时可能触发的 canPlayType 报错（Video Element 初始化时机），播放切换更加丝滑。

升级指南

1. 下载最新二进制文件。
2. 前端资源已内嵌，无需额外操作。

v0.8.4

MSP v0.8.4 发布说明

🚀 核心更新：智能播放策略 (Smart Playback)

v0.8.4 带来了一次底层的播放逻辑重构，彻底解决了 "为什么我的 AVI/MKV 播不了？" 的问题。

1. Try-First, Fallback-Next (优先直连，失败回退)

不再根据文件后缀（如 .mkv, .mp4）简单粗暴地决定是否转码。

• 所有文件首先尝试原生播放 (Direct Play)。
• 如果浏览器无法解码（报错 Code 3/4）或明确表示不支持（如 AVI），前端会自动向后端申请实时转码。
• 这意味着：只要你的浏览器能播（例如装了 HEVC 插件），MSP 就会利用硬件解码，零 CPU 占用；只有真正播不了的，才会动用 FFmpeg。

2. 完美的 AVI/MKV 支持

• 修复了 AVI 文件在 Chrome 下会被当成下载文件的问题。
• 修复了转码流无法拖动进度条的问题（Smart Seeking 回归）。

3. 后端并发保护

• 新增转码并发限制（默认为 2），防止多用户同时转码把服务器 CPU 跑满卡死。

升级指南

1. 下载最新二进制文件。
2. 强烈建议在 config.json 中确保开启转码功能，以获得最佳兼容性：

   "playback": {
     "video": { "transcode": true },
     "audio": { "transcode": true }
   }

   注：开启此选项不会导致所有视频都转码，只有浏览器播不了的才会转码。

v0.8.3

v0.8.3

📱 Mobile Experience Overhaul

• Single-Column Layout: Completely redesigned mobile interface to use a clean, vertical flow (Player → Playlist → Files), eliminating the cramped multi-column view.
• Scrollable Interface: The entire app page is now scrollable on mobile, solving issues where content was cut off on smaller screens.
• Optimized Player:
  • Audio player height is now adaptive, no longer forced into a 16:9 aspect ratio.
  • Cover art size is optimized (160px) to prevent it from dominating the screen.
  • Lyrics view is now flexible and fully visible without overlapping controls.

🐛 Bug Fixes

• Audio Playback: Fixed a critical issue where audio would sometimes stop 1-2 seconds early without advancing to the next track (added an auto-recovery mechanism).
• Layout: Increased spacing between sections on mobile for better touch target separation.
• CSS: Fixed syntax errors in stylesheets that could cause build warnings.