/* meow_ui_media.h — App 侧媒体会话封装（SDK 公共件；FRAMEWORK_DESIGN 附录 B / D1）。
 *
 * 让框架/第三方播放类 App 以 SDK 标准上报实时元数据（MSG_META）并接收控制（MSG_PLAYCTL）。
 * 声明 MF_PLAYBACK 的 App 首次上报 → launcher 注册为媒体源（最近活跃=当前源）；通知中心
 * 媒体卡片 / 主界面 Now Playing 页据此显示与控制。
 *
 * 连接管理（best-effort）：懒连（首次 meta/注册回调时 connect）+ 断线重连（下次上报时重试）；
 * launcher 不在 → 优雅静默降级，绝不崩。帧格式/负载复用 launcher 共享 meow_ipc.h（同一份）。
 *
 * 命名：launcher 侧已占用 meow_media_*（meow_media.c），SDK 侧统一 meow_ui_media_* 前缀，
 * 避免两态同符号在 launcher（链 meow_ui.a + meow_media.c）出现重复定义。
 */
#ifndef MEOW_UI_MEDIA_H
#define MEOW_UI_MEDIA_H

#include <stdint.h>

#ifdef __cplusplus
extern "C" {
#endif

/* 播放控制回调：cmd 1=播放 2=暂停 3=上一首 4=下一首 5=seek（seek_ms 为毫秒）6=播放/暂停切换
 * （toggle：物理播放/暂停键 164 恒发 6，由媒体源按自身当前态翻转——源是状态权威）。 */
typedef void (*meow_media_playctl_fn)(int cmd, int64_t seek_ms);

/* 指定 app_id（NULL=env MEOW_LOG_APP，缺省 "app"）。幂等，首次调用生效。 */
void meow_ui_media_init(const char *app_id);

/* 注册播放控制回调并启动后台接收线程（懒起；重复调用幂等）。
 * 线程：连接（HELLO+MF_PLAYBACK 注册为媒体源）→ poll 读 launcher 下发 MSG_PLAYCTL → 调 cb。 */
void meow_ui_media_on_playctl(meow_media_playctl_fn cb);

/* 上报实时元数据/进度/状态（state：0=停止 1=播放 2=暂停 3=缓冲）。
 * artwork/lyric 非空 → 自动置 MF_ART/MF_COVER/MF_LYRIC 标志；封面/歌词路径或 MeowOS 槽位。
 * best-effort：无 socket/launcher 不在 → 静默降级（打日志不崩）。 */
void meow_ui_media_meta(uint32_t state, uint32_t pos_ms, uint32_t dur_ms,
                        const char *title, const char *artist, const char *album,
                        const char *artwork, const char *lyric);

/* 停止后台接收线程并断开连接（App 退出时调；幂等）。 */
void meow_ui_media_stop(void);

/* 物理媒体键 → 系统语义（SDK 输入层调用；App 前台也生效）。
 * code：164=播放/暂停（恒发 cmd=6 toggle，源侧翻转）、165/19=上一曲、163=下一曲。
 * 本 App 注册过 playctl 回调（媒体源）→ 本地直接回调 cb(cmd,seek_ms)；
 * 否则经 IPC 发 MSG_PLAYCTL 给 launcher 转发到最近活跃媒体会话。非媒体键/无源静默。
 * best-effort：无 launcher/socket → 优雅降级，绝不崩。 */
void meow_ui_media_sys_key(int code);

#ifdef __cplusplus
}
#endif
#endif /* MEOW_UI_MEDIA_H */