Playcount & Rating

底层 API 完整参考：Playcount API · Metadata / Rating API · Titleformat API（可用 %play_count%、%rating% 等字段）

rating.set

设置曲目评分。优先使用 foo_playcount 上下文菜单，不可用时回退到写入文件 RATING 标签。

参数	类型	必填	描述
`path`	string	✗	音频文件路径（支持 `path\|subsong:N`）。省略时按 handler 规则对当前播放曲目操作
`rating`	number	✓	`0`-`5`，`0`=取消评分
`cueIndex`	number	✗	CUE 子曲目索引（优先级高于路径中的 `\|subsong:N`）

依赖说明

需要安装 foo_playcount 插件才能获得 stats 后端评分。

运行时权威：src/api/MetadataApi.cpp（rating.set）。

获取曲目评分。优先从 foo_playcount 读取（%rating% titleformat），不可用时回退读取文件 RATING 标签。

参数	类型	必填	描述
`path`	string	✓	音频文件路径（支持 `path\|subsong:N`）
`cueIndex`	number	✗	CUE 子曲目索引

返回值:

json

{
  "success": true,
  "path": "C:\\Music\\song.flac",
  "rating": 4,
  "storage": "stats"
}

字段	类型	描述
`rating`	number	`0`-`5`，`0`=未评分
`storage`	string	`"stats"`（来自 foo_playcount）或 `"file"`（来自文件标签）

运行时权威：src/api/MetadataApi.cpp（rating.get）。

获取播放统计信息（来自 foo_playcount）。详细参数和返回值见 Playcount API。

playcount.get 的别名，参数和返回值完全相同。见 Playcount API。

获取媒体库整体播放统计。详见 Playcount API。

已注册的占位接口。需要 path，但始终返回 success: false，并提示改用 rating.set 处理评分；不会修改播放次数。