README.md

# 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).