Dev2alpha by mkdir700 · Pull Request #208 · mkdir700/EchoPlayer

mkdir700 · 2025-10-12T13:05:38Z

Summary by CodeRabbit

新功能
- 增加 FFprobe 管理与下载、UV 安装器与镜像选择、Python 虚拟环境管理
- 引入内置媒体服务器（启动/停止/重启/健康检查），开机自动尝试启动
- 设置页新增 FFprobe/FFmpeg/媒体服务器面板；播放器在需转码时弹出安装提示
- 扩展预加载与 IPC 接口；支持媒体服务器动态端口与播放列表 URL 解析
文档
- 新增 docs 子模块；移除 FFmpeg 集成文档
测试
- 新增 UV 引导器测试；更新 FFmpeg/IPC 相关测试
杂务/构建
- 重构打包包含规则；更新 macOS FFmpeg 版本；新增忽略规则与子模块更新

* feat(media-server): implement runtime runtime management system - add UV bootstrapper with cross-platform install, caching, progress, validation - manage Python venv lifecycle, dependency installs, cleanup, and phased progress - introduce MediaServerService with lifecycle control, health checks, and port management - extend FFmpeg service to handle FFprobe with unified downloads and version updates - build settings UI sections for media server and plugins with real-time status - wire up 38 IPC channels covering UV, venv, FFmpeg/FFprobe, and server control - update build configs, add ffprobe download script, auto-start server, and bump backend ref * test: Update tests * test(main): mock electron app for ipc handlers * Update src/renderer/src/pages/settings/FFprobeSection.tsx Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Apply suggestion from @coderabbitai[bot] Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * refactor(types): extract common Platform and Arch types to shared package - Create packages/shared/types/system.ts with Platform and Arch type definitions - Remove duplicate type definitions from FFmpegDownloadService - Remove duplicate type definitions from UvBootstrapperService - Import shared types from @shared/types/system in both services This change improves code maintainability by centralizing common system type definitions. * fix(media-server): clear port and notify frontend on process exit Ensure media server port is properly cleared and frontend is notified when the process stops or crashes to prevent stale port usage. Changes: - Update notifyPortChanged signature to accept number | null - Clear this.port to null in both normal stop and crash exit handlers - Notify frontend with null port when server stops - Update SessionService listener to handle null port notifications - Add appropriate logging for port clearing events This prevents the frontend from continuing to use expired ports after the media server has stopped, requiring manual app restart. * fix(settings): prevent setTimeout memory leak in MediaServerSection Fix potential memory leak and unmounted component state update in MediaServerSection by properly managing setTimeout lifecycle: - Add successTimeoutRef to store timeout handle - Clear timeout in effect cleanup on component unmount - Clear timeout before creating new one in handleInstall - Clear timeout in error handler to prevent orphaned timers - Set ref to null after clearing to maintain clean state This prevents "Can't perform a React state update on an unmounted component" warnings and ensures proper cleanup of async operations. Co-Authored-By: Claude <noreply@anthropic.com> * fix(media-server): improve status display during installation and startup - Add 'starting' status immediately after installation completes - Move fetchServerInfo() to finally block to ensure status refresh - Prevent confusing 'stopped' status display during startup process * fix(python-venv): preserve final install progress state for callers Remove finally block that immediately clears installProgress, preventing callers from reading final "completed" or "error" state. Instead: - Clear installProgress at start of new installation - Preserve final state after completion/error for caller consumption - Remove unnecessary finally block cleanup This ensures MediaServerSection and other callers can reliably read the final installation state. Co-Authored-By: Claude <noreply@anthropic.com> * refactor(types): centralize media server types to shared package - Create shared types module for Media Server and Python Venv - Add media-server.ts with MediaServerInfo, MediaServerStatus, PythonVenvInfo, and InstallProgress types - Remove duplicate type definitions from MediaServerService, PythonVenvService, and MediaServerSection - Update imports to use @shared/types across main and renderer processes - Maintain backward compatibility by re-exporting types from service files - All type checks passing

… videos (#205) * feat(player): add media server recommendation prompt for incompatible videos When a video format is incompatible and Media Server is not installed, show a friendly prompt recommending installation. Features: - Automatic incompatibility detection with codec checking - Smart navigation to Media Server section in settings - Smooth scroll and highlight animation for better UX - Auto-trigger installation with one click - Dark mode compatible icon styling - i18n support (English and Chinese) Implementation: - Created MediaServerRecommendationPrompt component - Enhanced PlayerPage with Media Server check logic - Updated PluginsSettings with URL parameter handling - Added ref forwarding to MediaServerSection - Implemented pulse animation for visual feedback - Fixed styled-components v4+ keyframes interpolation 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * Update src/renderer/src/pages/settings/MediaServerSection.tsx Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * refactor(MediaServerRecommendationPrompt): replace hardcoded pixel values with design system spacing tokens - Replace hardcoded 48px with SPACING.XXL for IconWrapper dimensions - Replace hardcoded 32px with SPACING.XL for BenefitIcon dimensions - Replace hardcoded 2px with SPACING.XXS for BenefitIcon margin-top - Improve consistency with design system architecture - Enhance maintainability and cross-theme compatibility Changes: - IconWrapper: width/height 48px → ${SPACING.XXL}px - BenefitIcon: width/height 32px → ${SPACING.XL}px, margin-top 2px → ${SPACING.XXS}px This refactor eliminates magic numbers in styled components, ensuring better alignment with the project's design system tokens and simplifying future theme adjustments * refactor(MediaServerSection): fix ref handling with proper destructuring pattern - Replace incorrect ref prop with proper ref destructuring and renaming - Import React namespace for ref type annotations - Rename destructured ref to forwardedRef for clarity - Update useImperativeHandle to use forwardedRef instead of direct ref prop - Add displayName for better debugging experience Changes: - Import React namespace in addition to named hooks - Destructure ref as forwardedRef from props using rest pattern - Extract other props (onDependencyReady, triggerInstall, onInstallTriggered) from props object - Update useImperativeHandle first parameter to use forwardedRef - Add MediaServerSection.displayName = 'MediaServerSection' This refactoring addresses the incorrect pattern of accepting ref as a regular prop, which violates React's ref handling conventions. The new pattern properly destructures and renames the ref while maintaining full functionality. --------- Co-authored-by: Claude <noreply@anthropic.com> Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>

Replace static "加载中..." text with an animated sliding progress bar that provides better visual feedback during video loading. Changes: - Add LoadingBarContainer and LoadingBarProgress styled components - Implement sliding animation using CSS keyframes (1.5s ease-in-out) - Update LoadingContainer to use flex column layout with gap - Use Ant Design CSS variables for theme compatibility 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude <noreply@anthropic.com>

…#207) This update brings the following enhancements to the backend: ## New Features ### HLS Window Preloading with Configurable Strategy - **Automatic Background Preloading**: Automatically preload previous N windows in the background when accessing HLS files - **Configurable Preload Count**: Add `preload_previous_windows` configuration option (default: 1, min: 0) - **Non-blocking Execution**: Preload tasks run in background without blocking user requests - **Smart Cache Detection**: Skip already-cached windows to optimize resource usage - **Priority Management**: Low priority (3) for preload tasks to avoid impacting active user requests - **Performance Metrics**: Returns (queued_count, cached_count) metrics for monitoring ## Technical Changes ### API Layer (`src/app/api/`) - **deps.py**: Add PreloadStrategy dependency injection provider (`get_preload_strategy`) - **v1/jit.py**: Auto-trigger preload on window access with `asyncio.create_task` ### Configuration (`src/app/config/`) - **manager.py**: Add `preload_previous_windows` setting (default: 1, min: 0) - **schemas.py**: Add `preload_previous_windows` field to TranscodeConfig ### Service Layer (`src/app/services/`) - **preload_strategy.py**: Implement `preload_previous_windows` method with: - Cache key validation to avoid redundant transcoding - Window ID calculation for previous windows - Low-priority task queuing - Comprehensive error handling and logging ## Benefits - **Improved User Experience**: Proactively loads likely-needed segments for smoother playback - **Performance Optimization**: Maintains performance for active requests through priority management - **Resource Efficiency**: Smart cache detection prevents unnecessary transcoding - **Flexibility**: Configurable preload count allows tuning based on use case (0 to disable) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude <noreply@anthropic.com>

coderabbitai · 2025-10-12T13:05:47Z

Walkthrough

本次变更新增并集成了 FFprobe 下载与管理、UV 引导器、Python 虚拟环境与媒体服务器运行服务；扩展 IPC 通道与 preload API；在设置页新增 FFprobe/媒体服务器管理区块与联动安装流程；播放器在转码前检查媒体服务器；更新打包/构建过滤；添加文档子模块并移除旧 FFmpeg 文档。

Changes

Cohort / File(s)	Summary
仓库元数据与子模块 `/.gitignore`, `/.gitmodules`, `/backend`, `/docs`, `/docs/FFmpeg-Integration.md`	新增忽略项`resources/ffprobe/`与`.ffprobe-cache`；新增`docs`子模块；更新`backend`、`docs`子模块指针；移除旧版 FFmpeg 集成文档。
打包与构建 `/electron-builder.yml`, `/electron.vite.config.ts`, `/scripts/download-ffmpeg.ts`	electron-builder 从排除清单改为最小化包含清单；Vite 资源拷贝排除逻辑改为基于 Dirent 的目录/文件规则；macOS FFmpeg 下载 URL 升级到 8.0。
FFprobe 下载脚本 `/scripts/download-ffprobe.ts`	新增 FFprobe 下载器：按平台/架构下载、缓存、解压、定位可执行文件、权限设定；提供 CLI：current/all/clean/platform。导出类 `FFprobeDownloader`。
FFmpeg/FFprobe 服务扩展 `/src/main/services/FFmpegDownloadService.ts`	在现有 FFmpeg 基础上新增 FFprobe 全流程 API（路径/存在性/版本/下载/移除/进度/取消）；统一镜像与回退逻辑；方法签名加入二选一的 `binaryType`。
UV 引导器服务 `/src/main/services/UvBootstrapperService.ts`, `/src/main/services/__tests__/UvBootstrapperService.test.ts`	新增 UV 版本注册、下载/解压/缓存、系统检测、镜像测速与选择、依赖安装与执行封装；进度与取消支持；提供单例 `uvBootstrapperService`；新增完整测试套件。
Python 虚拟环境服务 `/src/main/services/PythonVenvService.ts`	新增 Python venv 管理：项目路径探测、创建 venv、安装/重装依赖、移除、进度跟踪；与 UV/镜像联动；提供单例 `pythonVenvService`。
媒体服务器服务 `/src/main/services/MediaServerService.ts`	新增媒体服务器进程管理：启动/停止/重启、端口探测与变更通知、健康检查、环境变量组装（含 FFmpeg/FFprobe）、状态获取；提供单例 `mediaServerService` 与配置类型。
主进程集成与 IPC `/src/main/index.ts`, `/src/main/ipc.ts`, `/packages/shared/IpcChannel.ts`	应用就绪时尝试根据 venv 状态启动媒体服务器；新增 FFprobe/UV/PythonVenv/MediaServer 多组 IPC 通道与处理器。
共享类型 `/packages/shared/types/index.ts`, `/packages/shared/types/media-server.ts`, `/packages/shared/types/system.ts`	新增系统/媒体服务器/Python venv 相关类型与集中导出索引。
Preload 公共 API `/src/preload/index.ts`	新增 ffprobe、uv、pythonVenv、mediaServer 四组 API（查询、下载/安装、进度、控制）。
渲染层设置页 `/src/renderer/src/pages/settings/FFprobeSection.tsx`, `/src/renderer/src/pages/settings/FFmpegSection.tsx`, `/src/renderer/src/pages/settings/MediaServerSection.tsx`, `/src/renderer/src/pages/settings/PluginsSettings.tsx`, `/src/renderer/src/pages/settings/SettingsPage.tsx`	新增 FFprobe 与媒体服务器设置区块；FFmpeg 区块扩展下载/进度 UI；新增插件设置聚合页并在路由中替代旧组件；支持自动滚动与自动安装触发。
播放器与提示组件 `/src/renderer/src/pages/player/PlayerPage.tsx`, `/src/renderer/src/components/MediaServerRecommendationPrompt.tsx`, `/src/renderer/src/components/index.ts`	播放前检查媒体服务器可用性；不可用时展示安装建议弹窗并使用原始源；新增加载进度条；新增并导出提示组件。
本地化 `/src/renderer/src/i18n/locales/en-us.json`, `/src/renderer/src/i18n/locales/zh-cn.json`	新增媒体服务器提示与 FFprobe/安装相关文案；调整部分 FFmpeg 按钮文案。
Session 动态端口 `/src/renderer/src/services/SessionService.ts`	引入媒体服务器端口变更监听；动态解析 API Base URL；新增获取播放列表 URL 与端口重置方法。
测试与基础设施 `/src/main/__tests__/ipc.database.test.ts`, `/src/main/services/__tests__/FFmpegDownloadService.test.ts`	Electron 模块集中化 mock；FFmpeg 测试更新以适配“latest”与新签名。

Sequence Diagram(s)

sequenceDiagram
  autonumber
  actor User as Renderer UI
  participant Preload as Preload API
  participant Main as Main Process (IPC)
  participant UV as UvBootstrapperService
  participant Venv as PythonVenvService
  participant MS as MediaServerService
  participant Bin as FFmpeg/FFprobe Service

  User->>Preload: mediaServer.start(config?)
  Preload->>Main: IpcChannel.MediaServer_Start
  Main->>Venv: checkVenvInfo()
  alt venv exists
    Main->>UV: checkUvInstallation()
    Main->>Bin: getFFmpeg/FFprobePath()
    Main->>MS: start(config)
    MS-->>Main: started/failed
  else venv missing
    Main-->>Preload: false (not started)
  end
  Main-->>Preload: result
  Preload-->>User: success/failure

  note over MS,User: 端口变化
  MS-->>Main: PortChanged
  Main-->>Preload: IpcChannel.MediaServer_PortChanged
  Preload-->>User: 更新端口

sequenceDiagram
  autonumber
  actor Viewer as PlayerPage
  participant Preload as Preload API
  participant Main as Main Process
  participant Venv as PythonVenvService
  participant Sess as SessionService (renderer)

  Viewer->>Preload: pythonVenv.checkInfo()
  Preload->>Main: IpcChannel.PythonVenv_CheckInfo
  Main->>Venv: checkVenvInfo()
  Venv-->>Main: info(exists: bool)
  Main-->>Preload: info
  Preload-->>Viewer: info

  alt venv exists
    Viewer->>Sess: create playback session
    Sess-->>Viewer: playlist URL (动态端口)
  else
    Viewer-->>Viewer: 展示安装建议弹窗
    Viewer-->>Viewer: 使用原始源
  end

Estimated code review effort

🎯 5 (Critical) | ⏱️ ~150 minutes

Possibly related PRs

feat(media-server): implement runtime runtime management system #204: 同样涉及 FFprobe/UV/PythonVenv/媒体服务器与 IPC/预加载/设置页的集成，代码层面高度重合。
feat(player): add media server recommendation prompt for incompatible videos #205: 引入 MediaServerRecommendationPrompt 及对应的 PlayerPage、PluginsSettings、MediaServerSection 与 i18n 改动，改动面与本 PR 相同。
feat(ffmpeg): add China mirror support for FFmpeg downloads #164: 在 FFmpegDownloadService 中增加国内/全球镜像选择与回退逻辑，本 PR在此基础上扩展至 FFprobe 并统一下载流程。

Poem

（=^·^=）/
代码田里风嗖嗖，UV 来把路径修；
兔子挥锄建虚拟，FFprobe 亦加油。
媒服起航端口变，播放器把路由；
一键安装云上奏，胡萝卜般顺手收。

Pre-merge checks and finishing touches

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Title Check	❓ Inconclusive	“Dev2alpha” 作为标题过于简略且不描述此次合并的主要改动内容，不足以让同事快速了解 PR 的核心变更。	请将标题修改为概括 PR 主要改动的简洁句子，例如“新增 FFprobe、UV、Python 虚拟环境和 MediaServer 支持并重构文档与构建配置”。

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

✨ Finishing touches

📝 Generate docstrings

🧪 Generate unit tests (beta)

Create PR with unit tests
Post copyable unit tests in a comment
Commit unit tests in branch dev2alpha

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

coderabbitai

Actionable comments posted: 13

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (7)

src/main/ipc.ts (1)
508-515: 修复 FFmpeg 下载进度/取消的参数传递

FFmpegDownloadService 的 getDownloadProgress 与 cancelDownload 现在都要求第一个参数传入资源标识（参见 FFmpegDownloadService.test.ts 中的调用）。当前 IPC handler 仍沿用旧签名，把 platform 当成首参传进去，会让渲染进程查询/取消进度时直接命中错误分支，导致进度查询永远失败。请同步更新成新签名。
   ipcMain.handle(
     IpcChannel.FfmpegDownload_GetProgress,
     async (_, platform?: string, arch?: string) => {
-      return ffmpegDownloadService.getDownloadProgress(platform as any, arch as any)
+      return ffmpegDownloadService.getDownloadProgress('ffmpeg', platform as any, arch as any)
     }
   )
   ipcMain.handle(IpcChannel.FfmpegDownload_Cancel, async (_, platform?: string, arch?: string) => {
-    return ffmpegDownloadService.cancelDownload(platform as any, arch as any)
+    return ffmpegDownloadService.cancelDownload('ffmpeg', platform as any, arch as any)
   })
src/main/services/FFmpegDownloadService.ts (4)
300-317: 隐私与合规风险：启动时调用 ipinfo.io 进行地区探测，且失败时默认为中国镜像

未经用户同意对外部服务发起请求（泄露 IP、UA 等）存在合规/隐私风险。

探测失败默认切换中国镜像，可能影响非中国用户的可用性和性能。

建议：

提供显式开关与用户同意（首次运行弹窗或设置项），默认无需外呼；

将失败时的默认策略改为“全球镜像”；

缓存用户选择，避免每次启动外呼。

可调整失败回退：
-      logger.warn('无法检测用户地区，使用默认镜像源', { error })
-      this.useChinaMirror = true // 检测失败时默认使用中国镜像源
+      logger.warn('无法检测用户地区，回退到全球镜像源', { error })
+      this.useChinaMirror = false // 失败回退到全球镜像
Also applies to: 321-342

1-7: 缺少下载完整性校验（SHA256 等），存在供应链风险

当前未对下载包进行校验（文件可能被篡改/中间人攻击）。请至少支持可选 SHA256 校验，并在失败时拒绝安装。

示例实现思路（简化）：
// 追加：计算文件 sha256
private async verifySha256(filePath: string, expected?: string): Promise<boolean> {
  if (!expected) return true
  const crypto = await import('node:crypto')
  const hash = crypto.createHash('sha256')
  const stream = fs.createReadStream(filePath)
  return await new Promise((resolve, reject) => {
    stream.on('data', (d) => hash.update(d))
    stream.on('end', () => resolve(hash.digest('hex').toLowerCase() === expected.toLowerCase()))
    stream.on('error', reject)
  })
}
在 download 后、extract 前调用：
-      await this.extractFile(downloadPath, tempDir)
+      const ok = await this.verifySha256(downloadPath, version.sha256)
+      if (!ok) {
+        throw new Error('校验失败：SHA256 不匹配')
+      }
+      await this.extractFile(downloadPath, tempDir)
并在版本配置中按需填充 sha256。

Also applies to: 626-697

337-341: 地区探测失败默认返回 'CN' 会误判，建议返回 'ZZ'/空并走全球镜像

当前默认 CN 会强行使用中国镜像，非预期。建议失败返回空值并让 detectRegionAndSetMirror 设 useChinaMirror=false。
-      return 'CN' // 默认返回 CN
+      return '' // 失败返回空，外层回退到全球镜像
961-989: 依赖外部解压工具（unzip/tar），需处理缺失场景或在日志中明确提示

在部分 Linux 发行版/最简环境中可能缺少 unzip/tar。建议：

捕获 ENOENT 并在日志中提示安装依赖；

或引入纯 JS 解压库作为后备。

Also applies to: 991-1005
src/preload/index.ts (2)

209-218: getProgress 返回类型过于宽泛，建议与主进程统一（DownloadProgress）

为提升类型安全，建议将 ffmpeg/ffprobe 的 getProgress 返回值改为共享的 DownloadProgress 类型（可将类型上移到 @shared/types 并复用）。

示例：

在 packages/shared 下新增 DownloadProgress 定义；

此处声明为 Promise<DownloadProgress | null>。

Also applies to: 236-248

664-671: 遵循统一日志规范，避免直接使用 console

按项目规范应统一使用 loggerService。若在 preload 无法直接复用，可通过 ipc 向主进程记录，或封装一个 preload 侧 logger 代理。

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 8f8e102 and 1be3e15.

📒 Files selected for processing (34)

.gitignore (1 hunks)
.gitmodules (1 hunks)
backend (1 hunks)
docs (1 hunks)
docs/FFmpeg-Integration.md (0 hunks)
electron-builder.yml (1 hunks)
electron.vite.config.ts (2 hunks)
packages/shared/IpcChannel.ts (1 hunks)
packages/shared/types/index.ts (1 hunks)
packages/shared/types/media-server.ts (1 hunks)
packages/shared/types/system.ts (1 hunks)
scripts/download-ffmpeg.ts (1 hunks)
scripts/download-ffprobe.ts (1 hunks)
src/main/__tests__/ipc.database.test.ts (2 hunks)
src/main/index.ts (2 hunks)
src/main/ipc.ts (2 hunks)
src/main/services/FFmpegDownloadService.ts (23 hunks)
src/main/services/MediaServerService.ts (1 hunks)
src/main/services/PythonVenvService.ts (1 hunks)
src/main/services/UvBootstrapperService.ts (1 hunks)
src/main/services/__tests__/FFmpegDownloadService.test.ts (6 hunks)
src/main/services/__tests__/UvBootstrapperService.test.ts (1 hunks)
src/preload/index.ts (2 hunks)
src/renderer/src/components/MediaServerRecommendationPrompt.tsx (1 hunks)
src/renderer/src/components/index.ts (1 hunks)
src/renderer/src/i18n/locales/en-us.json (1 hunks)
src/renderer/src/i18n/locales/zh-cn.json (3 hunks)
src/renderer/src/pages/player/PlayerPage.tsx (6 hunks)
src/renderer/src/pages/settings/FFmpegSection.tsx (1 hunks)
src/renderer/src/pages/settings/FFprobeSection.tsx (1 hunks)
src/renderer/src/pages/settings/MediaServerSection.tsx (1 hunks)
src/renderer/src/pages/settings/PluginsSettings.tsx (1 hunks)
src/renderer/src/pages/settings/SettingsPage.tsx (2 hunks)
src/renderer/src/services/SessionService.ts (5 hunks)

💤 Files with no reviewable changes (1)

docs/FFmpeg-Integration.md

🧰 Additional context used

📓 Path-based instructions (5)

src/renderer/src/**/*.{ts,tsx,scss,css}