feat(flutter): add cross-platform system media controls

[mom0ka27]

Summary

为 Erika Flutter 插件补充跨平台系统媒体信息发布、远程播放控制和可选后台播放支持。

本次改动覆盖 iOS、Android、macOS、Windows 和 HarmonyOS，并统一通过 ErikaMediaMetadata 向系统媒体中心发布标题、作者、专辑和封面。

Changes

Flutter API

• 新增 ErikaMediaMetadata：
  • title
  • artist
  • album
  • artwork
• open() 支持传入媒体元数据。
• 新增 setMediaMetadata()，允许播放期间更新系统媒体信息。
• 新增 allowBackgroundPlayback 播放器创建选项。
• 后台播放默认关闭，保持现有应用行为和资源策略。

iOS

• 接入 MPNowPlayingInfoCenter 和 MPRemoteCommandCenter。
• 在控制中心和锁屏界面发布媒体元数据、封面、播放状态、时长和进度。
• 支持系统播放、暂停、切换播放状态和 seek。
• 接入 AVAudioSession interruption。
• 增加后台 audio-only presenter tick。
• App 进入后台时暂停视频解码，仅继续音频供给。
• App 返回前台时重建失效的 VideoToolbox decoder
• 由 Rust worker 发布实际暂停位置，再发布 paused 状态，避免控制中心进度归零或回退。

Android

• 接入平台 MediaSession、MediaMetadata 和 PlaybackState。
• 增加媒体通知以及锁屏、蓝牙耳机和系统媒体面板控制。
• 支持系统播放、暂停、停止和 seek。
• allowBackgroundPlayback: true 时启动 mediaPlayback 前台 Service。
• 后台通过 JNI audio-only tick 继续音频，不执行完整视频渲染 tick。
• 增加前台 Service、Android 13+ 通知权限和 Android 14+ media playback 权限声明。
• 增加 Android 媒体状态映射单元测试。

macOS

• 接入 Now Playing 和 Remote Command Center。
• 发布标题、作者、专辑、封面、播放状态和时间线。
• 支持系统播放、暂停、停止、切换播放状态和 seek。
• 链接 MediaPlayer.framework。
• 将 podspec Swift 版本调整为 5.7，以匹配插件使用的 Swift 语法。

Windows

• 接入 System Media Transport Controls（SMTC）。
• 发布媒体元数据、封面、播放状态、倍速和时间线。
• 支持系统播放、暂停和 seek。
• 将系统媒体回调安全切换至插件 UI 线程。
• 增加 C++/WinRT 和 SMTC 所需系统库链接。

HarmonyOS

• 接入 AVSession。
• 发布媒体元数据、封面、播放状态、位置、时长和倍速。
• 支持系统播放、暂停、停止和 seek。
• 增加 Native NAPI TypeScript 类型声明。
• 移除 CMake 对固定 Rust 1.93.0 toolchain 的硬编码要求。

Documentation

• 同步更新中文、英文和日文 README。
• 补充各平台系统媒体能力、后台播放行为和宿主配置说明。
• 补充 Android POST_NOTIFICATIONS 运行时权限要求。

Background Playback

后台播放保持显式 opt-in：

final player = ErikaPlayer(
  allowBackgroundPlayback: true,
);

final artwork = await rootBundle.load('assets/cover.jpg');

await player.open(
  mediaUrl,
  metadata: ErikaMediaMetadata(
    title: 'Title',
    artist: 'Artist',
    album: 'Album',
    artwork: artwork.buffer.asUint8List(),
  ),
);

await player.play();

allowBackgroundPlayback 是播放器创建选项，native player 创建后不能动态修改。

iOS 宿主还需要启用：

• Background Modes > Audio, AirPlay, and Picture in Picture
• 或在 Info.plist 的 UIBackgroundModes 中加入 audio

Android 宿主需要根据产品流程请求 Android 13+ 的 POST_NOTIFICATIONS 运行时权限。

Compatibility

• allowBackgroundPlayback 默认为 false。
• 未传入 ErikaMediaMetadata 时，现有播放 API 保持兼容。
• artwork 必须是完整编码的图片字节，例如 JPEG 或 PNG，而不是原始像素数据。
• 多播放器场景下，最近开始播放的播放器成为当前系统媒体会话目标。

Validation

• cargo fmt --all -- --check
• cargo test -p erika --lib — 395 passed
• cargo test -p erika_capi — 27 passed
• flutter analyze
• flutter test — 41 passed
• macOS Swift syntax parsing
• macOS podspec validation
• git diff --check

Platform Validation Notes

• Windows SMTC 最终编译仍需在 Windows + MSVC 环境验证。
• HarmonyOS AVSession 和 ArkTS 构建仍需在 DevEco/Hvigor 环境验证。
• Android 原生 Kotlin/Service 集成仍建议在带 Android Gradle wrapper 的宿主应用或 CI 中执行最终构建与设备测试。

[Shinokawa]

@codex review

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 174fbf5d0f

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".