feat(ffmpeg): implement dynamic FFmpeg download system with runtime management (#155)

* feat(ffmpeg): implement dynamic FFmpeg download system with runtime management

- Remove static FFmpeg bundling from build configuration
- Add FFmpegDownloadService for cross-platform binary management
- Implement automatic platform detection (Windows/macOS/Linux, x64/ARM64)
- Add IPC channels for download progress monitoring and control
- Integrate download service with existing FFmpegService architecture
- Update build scripts to remove prebuild FFmpeg requirements
- Add comprehensive test coverage for download functionality

Changes:
- electron-builder.yml: Remove extraResources FFmpeg bundling
- package.json: Remove prebuild FFmpeg download from release scripts
- FFmpegDownloadService.ts: New service with download/extract/management capabilities
- FFmpegService.ts: Enhanced with download service integration and fallback logic
- IpcChannel.ts: Add 9 new channels for download operations
- ipc.ts: Register download service handlers for renderer communication
- preload/index.ts: Expose download APIs to renderer process
- useVideoFileSelect.ts: Updated to work with dynamic FFmpeg detection

This implementation enables on-demand FFmpeg installation, reducing app bundle
size by ~200MB while maintaining cross-platform compatibility and user experience.
The system gracefully falls back to bundled → downloaded → system FFmpeg.

* feat(settings): implement FFmpeg settings UI with download management

- Add new FFmpegSettings component with status indicator and download controls
- Remove deprecated FFmpeg build plugin from electron.vite.config.ts
- Enhance IndicatorLight component with proper CSS-in-JS animation syntax
- Add comprehensive i18n support for FFmpeg management (en-us, zh-cn)
- Remove box-shadow from ant-btn components for cleaner UI appearance
- Integrate FFmpeg settings into main SettingsPage navigation

Changes:
- FFmpegSettings.tsx: Complete UI implementation with download progress, path validation, and status management
- electron.vite.config.ts: Remove build-time FFmpeg download plugin (shift to runtime approach)
- IndicatorLight.tsx: Fix styled-components animation with proper css helper
- i18n locales: Add 61 new translation keys for FFmpeg settings UI
- ant.scss: Remove button shadows for consistent design system
- SettingsPage.tsx: Add FFmpeg settings tab integration

This implements the frontend interface for the dynamic FFmpeg download system,
providing users with a comprehensive management UI for FFmpeg installation,
status monitoring, and path configuration.

* feat(ffmpeg): implement FFmpeg guidance dialog for enhanced user experience

Add comprehensive FFmpeg download guidance system that transforms technical errors
into user-friendly guidance with seamless navigation to settings and auto-download.

**Components Added:**
- FFmpegDownloadPrompt: Full-featured guidance dialog with benefits, effort info, and actions
- Comprehensive internationalization support (zh-CN, en-US)

**Hook Enhancements:**
- useVideoFileSelect: Extended with FFmpeg prompt state management
- Replaced technical error throwing with guided dialog display
- Enhanced error detection for FFmpeg missing scenarios

**Integration Updates:**
- HomePage: State management for prompt visibility and component integration
- EmptyState/VideoAddButton: Bidirectional state communication with parent
- HeaderNavbar: Props forwarding for prompt handler

**Features:**
- Benefits explanation (compatibility, performance, reliability)
- Installation effort communication
- Auto-navigation to settings with download trigger
- Seamless integration with existing video file selection workflow
- Graceful error handling with user-centric messaging

**Technical Details:**
- Styled-components with theme variables and CSS custom properties
- Modal-based UI with responsive design and accessibility
- State management across component hierarchy
- URL parameter-based auto-download triggering
- Comprehensive TypeScript interfaces

Transforms "视频处理组件未安装" technical errors into guided user experience
that educates users about FFmpeg benefits and provides immediate resolution path.

* test: fix FFmpegService mock for dynamic download system

- Add getDownloadService method to FFmpegService mock
- Include all FFmpegDownloadService interface methods in mock
- Fix 43 failing test cases caused by missing mock method
- All 554 test cases now pass successfully

Resolves test failures introduced by FFmpeg dynamic download system implementation.

* test: fix cross-platform FFmpeg executable name test

- Update test to handle platform-specific executable names (ffmpeg vs ffmpeg.exe)
- Fix Windows CI test failure where test expected 'ffmpeg' but got 'ffmpeg.exe'
- Test now correctly validates system FFmpeg fallback behavior on all platforms
- Maintains test coverage while supporting cross-platform compatibility

Resolves Windows CI test failure in FFmpegService integration tests.

Author: mkdir700

electron-builder.yml

@@ -46,11 +46,6 @@ files:
 asarUnpack:
   - resources/**
   - '**/*.{metal,exp,lib}'
-extraResources:
-  - from: resources/ffmpeg
-    to: ffmpeg
-    filter:
-      - '**/*'
 copyright: Copyright © 2025 EchoPlayer
 win:
   executableName: EchoPlayer

electron.vite.config.ts

@@ -2,92 +2,17 @@ import fs from 'node:fs'
 import path from 'node:path'
 
 import react from '@vitejs/plugin-react-swc'
-import { spawn } from 'child_process'
 import { CodeInspectorPlugin } from 'code-inspector-plugin'
 import { defineConfig, externalizeDepsPlugin } from 'electron-vite'
 import { resolve } from 'path'
 
 const isDev = process.env.NODE_ENV === 'development'
 const isProd = process.env.NODE_ENV === 'production'
 
-// FFmpeg 下载插件
-function ffmpegDownloadPlugin() {
-  return {
-    name: 'ffmpeg-download',
-    async buildStart() {
-      // 只在生产构建时下载 FFmpeg
-      if (!isProd) return
-
-      // 根据构建目标决定下载哪个平台
-      const targetPlatform = process.env.BUILD_TARGET_PLATFORM || process.platform
-      const targetArch = process.env.BUILD_TARGET_ARCH || process.arch
-
-      // 检查是否已存在，避免重复下载
-      const ffmpegPath = path.resolve(
-        'resources/ffmpeg',
-        `${targetPlatform}-${targetArch}`,
-        targetPlatform === 'win32' ? 'ffmpeg.exe' : 'ffmpeg'
-      )
-
-      if (fs.existsSync(ffmpegPath)) {
-        console.log(`FFmpeg already exists for ${targetPlatform}-${targetArch}`)
-        return
-      }
-
-      console.log(`Downloading FFmpeg for ${targetPlatform}-${targetArch}...`)
-
-      try {
-        await new Promise<void>((resolve, reject) => {
-          // 在不同环境中使用不同的命令来确保兼容性
-          let command: string
-          let args: string[]
-
-          if (process.platform === 'win32') {
-            // Windows 环境：使用 npm run 调用脚本，更可靠
-            command = 'npm'
-            args = ['run', 'ffmpeg:download']
-          } else {
-            // Unix 环境：直接使用 tsx
-            command = 'tsx'
-            args = ['scripts/download-ffmpeg.ts', 'platform', targetPlatform, targetArch]
-          }
-
-          const downloadScript = spawn(command, args, {
-            stdio: 'inherit',
-            shell: process.platform === 'win32',
-            env: {
-              ...process.env,
-              BUILD_TARGET_PLATFORM: targetPlatform,
-              BUILD_TARGET_ARCH: targetArch
-            }
-          })
-
-          downloadScript.on('close', (code) => {
-            if (code === 0) {
-              console.log('FFmpeg Downloaded successfully')
-              resolve()
-            } else {
-              reject(new Error(`FFmpeg Download failed with exit code: ${code}`))
-            }
-          })
-
-          downloadScript.on('error', (error) => {
-            reject(error)
-          })
-        })
-      } catch (error) {
-        console.error('FFmpeg Download failed:', error)
-        throw new Error(`Failed to download FFmpeg for ${targetPlatform}-${targetArch}: ${error}`)
-      }
-    }
-  }
-}
-
 export default defineConfig({
   main: {
     plugins: [
       externalizeDepsPlugin(),
-      ffmpegDownloadPlugin(),
       {
         name: 'copy-files',
         generateBundle() {
@@ -125,41 +50,6 @@ export default defineConfig({
               }
             }
           }
-
-          // 复制 FFmpeg 文件到构建目录
-          const ffmpegResourcesDir = path.resolve('resources/ffmpeg')
-          if (fs.existsSync(ffmpegResourcesDir)) {
-            const outResourcesDir = path.resolve('out/resources/ffmpeg')
-
-            try {
-              // 确保输出目录存在
-              fs.mkdirSync(outResourcesDir, { recursive: true })
-
-              // 复制整个 ffmpeg 目录
-              const copyDirectoryRecursive = (src: string, dest: string) => {
-                if (!fs.existsSync(src)) return
-
-                fs.mkdirSync(dest, { recursive: true })
-                const items = fs.readdirSync(src)
-
-                for (const item of items) {
-                  const srcPath = path.join(src, item)
-                  const destPath = path.join(dest, item)
-
-                  if (fs.statSync(srcPath).isDirectory()) {
-                    copyDirectoryRecursive(srcPath, destPath)
-                  } else {
-                    fs.copyFileSync(srcPath, destPath)
-                  }
-                }
-              }
-
-              copyDirectoryRecursive(ffmpegResourcesDir, outResourcesDir)
-              console.log('FFmpeg files copied successfully')
-            } catch (error) {
-              console.warn('Failed to copy FFmpeg files:', error)
-            }
-          }
         }
       }
     ],

package.json

@@ -48,10 +48,10 @@
     "version:prerelease": "tsx scripts/version-manager.ts prerelease",
     "version:beta": "tsx scripts/version-manager.ts minor beta",
     "version:beta-patch": "tsx scripts/version-manager.ts patch beta",
-    "release": "npm run ffmpeg:download-all && npm run build:release && electron-builder --publish onTagOrDraft",
-    "release:all": "npm run ffmpeg:download-all && npm run build:release && electron-builder --publish always",
-    "release:never": "npm run ffmpeg:download-all && npm run build:release && electron-builder --publish never",
-    "release:draft": "npm run ffmpeg:download-all && npm run build:release && electron-builder --publish onTagOrDraft",
+    "release": "npm run build:release && electron-builder --publish onTagOrDraft",
+    "release:all": "npm run build:release && electron-builder --publish always",
+    "release:never": "npm run build:release && electron-builder --publish never",
+    "release:draft": "npm run build:release && electron-builder --publish onTagOrDraft",
     "migrate": "tsx src/main/db/migration-cli.ts",
     "migrate:up": "npm run migrate up",
     "migrate:down": "npm run migrate down",
@@ -71,9 +71,7 @@
     "ffmpeg:download": "tsx scripts/download-ffmpeg.ts current",
     "ffmpeg:download-all": "tsx scripts/download-ffmpeg.ts all",
     "ffmpeg:clean": "tsx scripts/download-ffmpeg.ts clean",
-    "ffmpeg:test": "tsx scripts/test-ffmpeg-integration.ts",
-    "prebuild": "npm run ffmpeg:download",
-    "prebuild:release": "echo 'FFmpeg already downloaded by release script'"
+    "ffmpeg:test": "tsx scripts/test-ffmpeg-integration.ts"
   },
   "dependencies": {
     "@ant-design/icons": "^6.0.1",

packages/shared/IpcChannel.ts

@@ -77,6 +77,18 @@ export enum IpcChannel {
   Ffmpeg_GetVideoInfo = 'ffmpeg:get-video-info',
   Ffmpeg_Warmup = 'ffmpeg:warmup',
   Ffmpeg_GetWarmupStatus = 'ffmpeg:get-warmup-status',
+  Ffmpeg_GetInfo = 'ffmpeg:get-info',
+  Ffmpeg_AutoDetectAndDownload = 'ffmpeg:auto-detect-and-download',
+
+  // FFmpeg 下载相关 IPC 通道 / FFmpeg download related IPC channels
+  FfmpegDownload_CheckExists = 'ffmpeg-download:check-exists',
+  FfmpegDownload_GetVersion = 'ffmpeg-download:get-version',
+  FfmpegDownload_Download = 'ffmpeg-download:download',
+  FfmpegDownload_GetProgress = 'ffmpeg-download:get-progress',
+  FfmpegDownload_Cancel = 'ffmpeg-download:cancel',
+  FfmpegDownload_Remove = 'ffmpeg-download:remove',
+  FfmpegDownload_GetAllVersions = 'ffmpeg-download:get-all-versions',
+  FfmpegDownload_CleanupTemp = 'ffmpeg-download:cleanup-temp',
 
   // MediaInfo 相关 IPC 通道 / MediaInfo related IPC channels
   MediaInfo_CheckExists = 'mediainfo:check-exists',

src/main/__tests__/ipc.database.test.ts

@@ -166,7 +166,17 @@ vi.mock('../services/FFmpegService', () => ({
     getVideoInfo: vi.fn(),
     transcodeVideo: vi.fn(),
     cancelTranscode: vi.fn(),
-    getFFmpegPath: vi.fn()
+    getFFmpegPath: vi.fn(),
+    getDownloadService: vi.fn(() => ({
+      checkFFmpegExists: vi.fn(),
+      getFFmpegVersion: vi.fn(),
+      downloadFFmpeg: vi.fn(),
+      getDownloadProgress: vi.fn(),
+      cancelDownload: vi.fn(),
+      removeFFmpeg: vi.fn(),
+      getAllSupportedVersions: vi.fn(),
+      cleanupTempFiles: vi.fn()
+    }))
   }))
 }))
 

src/main/ipc.ts

@@ -474,6 +474,51 @@ export function registerIpc(mainWindow: BrowserWindow, app: Electron.App) {
   ipcMain.handle(IpcChannel.Ffmpeg_GetWarmupStatus, async () => {
     return FFmpegService.getWarmupStatus()
   })
+  ipcMain.handle(IpcChannel.Ffmpeg_GetInfo, async () => {
+    return ffmpegService.getFFmpegInfo()
+  })
+  ipcMain.handle(IpcChannel.Ffmpeg_AutoDetectAndDownload, async () => {
+    return await ffmpegService.autoDetectAndDownload()
+  })
+
+  // FFmpeg 下载服务
+  const ffmpegDownloadService = ffmpegService.getDownloadService()
+  ipcMain.handle(
+    IpcChannel.FfmpegDownload_CheckExists,
+    async (_, platform?: string, arch?: string) => {
+      return ffmpegDownloadService.checkFFmpegExists(platform as any, arch as any)
+    }
+  )
+  ipcMain.handle(
+    IpcChannel.FfmpegDownload_GetVersion,
+    async (_, platform?: string, arch?: string) => {
+      return ffmpegDownloadService.getFFmpegVersion(platform as any, arch as any)
+    }
+  )
+  ipcMain.handle(
+    IpcChannel.FfmpegDownload_Download,
+    async (_, platform?: string, arch?: string) => {
+      return await ffmpegDownloadService.downloadFFmpeg(platform as any, arch as any)
+    }
+  )
+  ipcMain.handle(
+    IpcChannel.FfmpegDownload_GetProgress,
+    async (_, platform?: string, arch?: string) => {
+      return ffmpegDownloadService.getDownloadProgress(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)
+  })
+  ipcMain.handle(IpcChannel.FfmpegDownload_Remove, async (_, platform?: string, arch?: string) => {
+    return ffmpegDownloadService.removeFFmpeg(platform as any, arch as any)
+  })
+  ipcMain.handle(IpcChannel.FfmpegDownload_GetAllVersions, async () => {
+    return ffmpegDownloadService.getAllSupportedVersions()
+  })
+  ipcMain.handle(IpcChannel.FfmpegDownload_CleanupTemp, async () => {
+    return ffmpegDownloadService.cleanupTempFiles()
+  })
 
   // MediaParser (Remotion)
   ipcMain.handle(IpcChannel.MediaInfo_CheckExists, async () => {