admin1
186 lines
7.8 KiB
Markdown
186 lines
7.8 KiB
Markdown
# 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`.
|
||
|
||
```sh
|
||
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:
|
||
|
||
```sh
|
||
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.
|
||
|
||
```powershell
|
||
# 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:
|
||
|
||
```powershell
|
||
$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:
|
||
|
||
```sh
|
||
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:
|
||
|
||
```powershell
|
||
winget install -e --id JRSoftware.InnoSetup
|
||
```
|
||
|
||
**Build:**
|
||
|
||
```powershell
|
||
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
|
||
|
||
```sh
|
||
flutter analyze
|
||
```
|
||
|
||
## Code generation
|
||
|
||
`@freezed` / `@JsonSerializable` / `@RestApi` annotations require regenerating part files after changes:
|
||
|
||
```sh
|
||
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).
|