# Playback 公共 API

mp_harmony_playback.h 是上层唯一稳定契约，提供 PlaybackRequest、PlaybackState、Track、MediaInfo、PlaybackMetrics 和 PlaybackError 模型别名。PlaybackRequest 只携带 URL、标题、起始位置、User-Agent、Referer、Cookie、任意 HTTP headers、字幕源、语言偏好、轨道选择、速度和超时。空值或负值按头文件注释表示未设置。

公开控制命令：Play、Pause、TogglePause、SeekAbsolute、SeekRelative、SeekPercent、Stop、SetSpeed、SetVolume、Mute、SetAudioEnabled、SelectAudioTrack、SelectSubtitleTrack、DisableSubtitle、AddSubtitle、RemoveSubtitle、SetSubtitleDelay、SetSubtitleScale、SetSubtitlePosition、SetAssOverride、GetTracks、GetMediaInfo、GetNetworkInfo、GetPlaybackState。

所有控制入口串行化；请求中的字符串在调用返回前复制到 mpv 所需的临时节点，调用者可以立即释放输入内存。session id 随每次 load 增长，旧 playlist event 不得改变新会话状态。

Playback Lab 的 C++ 外壳只做 NAPI/渲染适配，所有请求、控制和状态快照均委托上述 C API；渲染器使用私有句柄桥接，不进入公共 ABI。

当前 OHOS 构建未启用 iconv，外挂字幕 encoding 只接受 UTF-8/UTF8；其他编码通过稳定 SUBTITLE 错误拒绝。

起播 `start_position_ms` 在 `MPV_EVENT_FILE_LOADED` 后执行 exact seek，避免异步 load 竞态；`title` 映射到 `force-media-title`。MediaInfo 同时保留历史 `width`/`height`/`color_space` 字段，并提供 `video_width`/`video_height`/`color_matrix` 别名。NetworkInfo 的 `range_supported` 为 -1/0/1（未知/未观察到 206/观察到 206），`seek_result` 为最近一次 seek 的 `ok` 或脱敏错误。