SMPlayer

一个 Emby 媒体服务器跨平台客户端。

目前主要面向 Windows / macOS

主要功能

• Emby 媒体库浏览：主页、媒体库、详情、搜索、收藏、播放记录、最近添加。
• 播放器：倍速、音轨 / 字幕切换、字幕样式、画面比例、选集、全屏、桌面画中画。
• 弹幕：兼容弹弹 play / danmu_api 风格 API，支持多源、自动匹配、手动搜索、过滤和样式调整。
• 多服务器：可添加多个 Emby 服务器，支持本地备份 / 导入配置。
• 扩展功能：可选 TMDB 详情 / 发现页、Trakt scrobble 和应用内更新。

技术栈

Flutter、Riverpod、Dio / Retrofit、fvp / libmdk、media_kit / mpv、media3 / ExoPlayer + FFmpeg（Android）、canvas_danmaku。

播放引擎

播放器内置三个可切换的解码 / 渲染引擎，可在"设置 → 播放设置 → 播放引擎"中选择：

引擎	适用平台	解码路径	说明
fvp (libmdk)	Windows / macOS / Android	平台硬解 + libmdk 软解兜底	auto 模式的主引擎；杜比视界 / ProRes 优先走它
mpv (media_kit)	Windows / macOS / Android	mpv / libmpv	兼容性次引擎；桌面 auto 模式备选
media3 (ExoPlayer + FFmpeg)	Android only	MediaCodec 硬解视频 + FFmpeg 软解音频	专为补 Android 高规格音轨（DTS / TrueHD / EAC3）；需自编译 AAR，见 plugins/media3_engine/README.md 与 scripts/build_media3_ffmpeg.sh

auto 模式在 Android 上默认 fvp、桌面默认 mpv；遇 DV / ProRes 强制 fvp。media3 仅在用户手动选中时启用，且桌面平台不会展示该选项（运行时也有路由层守卫降级到 mpv）。

下载

前往 GitHub Releases 页面下载发布版本（需自行配置仓库地址）。

当前自动发布流程主要提供 Windows x64 安装包。macOS 和 Android 可按下方开发说明自行构建。

项目结构

• lib/core - 合约、领域用例、仓储端口、存储和 Emby API 适配器。
• lib/features - 首页、媒体库、详情、播放、搜索、收藏、设置等功能页面。
• lib/providers - Riverpod 状态和依赖注入。
• lib/shared - 可复用组件、主题和映射工具。
• macos, windows - Flutter 桌面平台外壳。
• android - Flutter Android 平台外壳。
• installer/, scripts/ - Windows Inno Setup 脚本和开发 / 发布辅助脚本。
• test - Flutter 测试。

开发

Script entry (package.json, npm-style)

If you prefer npm run <task> over remembering each Flutter/PowerShell invocation, a thin package.json maps familiar names onto the existing scripts. It is private (no publish, no node_modules needed) — npm is only used as a task runner; the single source of truth stays in scripts/*.ps1.

npm run dev              # -> scripts/dev.ps1 run   (Windows smart run)
npm run dev:macos        # -> flutter run -d macos
npm run gen              # -> build_runner build --delete-conflicting-outputs
npm run watch            # -> build_runner watch  --delete-conflicting-outputs
npm run build:windows    # -> flutter build windows --release
npm run build:macos      # -> flutter build macos --release
npm run build:apk        # -> flutter build apk --release
npm run test             # -> flutter test
npm run analyze          # -> flutter analyze
npm run clean            # -> flutter clean
npm run pub              # -> flutter pub get
npm run doctor           # -> flutter doctor -v
npm run installer        # -> scripts/dev.ps1 installer  (Windows .exe)
npm run dmg              # -> scripts/build_dmg.sh        (macOS .dmg)

Pass-through args use the npm -- separator; everything after it is forwarded to the underlying script. To force pub get and run in release mode:

npm run dev -- -Force -FlutterArgs --release   # -> scripts/dev.ps1 run -Force -FlutterArgs --release

dev/installer shell out to PowerShell (Windows); dmg needs bash (macOS). The rest are plain Flutter CLI calls and work on any platform.

Windows — unified entry (scripts/dev.ps1)

One-click subcommand dispatcher. Delegates to dev-run.ps1 / build-installer.ps1 and wraps common Flutter tasks. On Windows, run prepares the project-pinned fvp/libmdk SDK and clears FVP_DEPS_LATEST, so local development never silently switches to a nightly dependency.

# Smart dev run (skips `pub get` when unchanged)
powershell -ExecutionPolicy Bypass -File scripts\dev.ps1 run

# Force a clean re-download of the project-pinned fvp/mdk-sdk:
powershell -ExecutionPolicy Bypass -File scripts\dev.ps1 run -RefreshFvpDeps

# Build .exe installer (Inno Setup 6 required, see below)
powershell -ExecutionPolicy Bypass -File scripts\dev.ps1 installer
powershell -ExecutionPolicy Bypass -File scripts\dev.ps1 installer -SkipFlutterBuild
powershell -ExecutionPolicy Bypass -File scripts\dev.ps1 installer -Version 1.0.1

# Other shortcuts
scripts\dev.ps1 build       # flutter build windows --release
scripts\dev.ps1 gen         # dart run build_runner build --delete-conflicting-outputs
scripts\dev.ps1 clean       # flutter clean
scripts\dev.ps1 pub         # flutter pub get
scripts\dev.ps1 analyze     # flutter analyze
scripts\dev.ps1 doctor      # flutter doctor -v
scripts\dev.ps1 help        # full subcommand list

Pass-through args:

• dev.ps1 run -Force -FlutterArgs --release → forces pub get and runs Flutter in release mode.
• dev.ps1 run -Device macos → choose a different target.
• dev.ps1 run -RefreshFvpDeps → deletes the cached SDK/archive and re-downloads the project-pinned fvp/MDK version.

Avoid using this for daily Windows development:

$env:FVP_DEPS_LATEST=1; flutter run -d windows

Use scripts\dev.ps1 run instead; it also skips pub get when dependencies are unchanged.

macOS / Android

Use the Flutter CLI directly:

flutter pub get
flutter run -d macos        # macOS
npm run dev:android         # Android (auto-detect emulator or device)
flutter build macos         # macOS bundle
npm run build:apk           # Android APK with project-pinned MDK
./scripts/build_dmg.sh      # macOS .dmg packaging

Android 构建前置 — Media3 FFmpeg decoder AAR：Android 端的 media3 引擎依赖 自编译的 media3-decoder-ffmpeg-1.10.1-arm64.aar。仓库默认不提交该二进制， 因此首次构建 Android 之前需要运行 scripts/build_media3_ffmpeg.sh 生成产物 （NDK r26b、~30–60 分钟）。AAR 缺失时 plugin 的 preBuild 会 fail-fast 抛出 包含恢复指令的错误。仅构建 Windows / macOS 桌面端时无需此步骤。详见 plugins/media3_engine/README.md。

Windows Installer (.exe)

Produces build/installer/smplayer-setup-<version>-x64.exe via Inno Setup 6.

Prerequisite (one-time) — install Inno Setup:

winget install -e --id JRSoftware.InnoSetup

Build:

scripts\dev.ps1 installer                     # full pipeline (flutter build + ISCC)
scripts\dev.ps1 installer -SkipFlutterBuild   # reuse existing build/ artifacts

Layout:

installer/
├── sm_emby.iss                 Inno Setup script (DV/HDR engine DLLs + flutter_assets)
└── lang/ChineseSimplified.isl  Bundled language file (avoids relying on system ISL)

The installer is unsigned — first launch triggers Windows SmartScreen ("More info → Run anyway"). Add SignTool= to sm_emby.iss once a .pfx certificate is available.

Validation

flutter analyze

Code generation

@freezed / @JsonSerializable / @RestApi annotations require regenerating part files after changes:

dart run build_runner build --delete-conflicting-outputs
# or
scripts\dev.ps1 gen

Generated *.g.dart / *.freezed.dart files must be committed (marked linguist-generated=true so GitHub diffs collapse them).