v56

latestSwagger 2.0Apache 2.0raw.githubusercontent.com2026-08-0616186383.8 KB
歌曲管理

通知歌曲播放事件

客户端在歌曲开始播放、播放完成或被跳过时调用此端点,后端将事件广播给已订阅播放事件的 JS 插件(通过 songloft.events.onPlayEvent 注册)。source 参数标识调用来源,如 songloft-player(官方客户端)、miot(小爱音箱插件)等。type 参数标识事件类型:play(开始播放)、finish(播放完成)、skip(用户跳过)。 副作用:当 type=play 且同时传入合法的 context_type + context_key 时,额外把该歌曲写入对应播放上下文的播放历史(见 GET /play-history),同一上下文内按歌曲去重、只保留最近 50 条。仅 type=play 会落库:finish 是同一首歌的重复信息,而 skip 上报的是上一首歌、此时上下文可能已切换,会记错归属。落库失败只记日志,不影响响应码。

post/songs/{id}/played

Path parameters

idinteger required

歌曲 ID

Query parameters

sourcestring

调用来源标识,如 songloft-player、miot

type'play' | 'finish' | 'skip'

事件类型:play、finish、skip,默认 finish

context_type'playlist' | 'artist' | 'album' | 'genre' | 'year' | 'decade' | 'language' | 'style'

播放上下文类型,仅 type=play 时生效:playlist 或分面维度(artist/album/genre/year/decade/language/style)

context_keystring

播放上下文标识,仅 type=play 时生效:playlist 传歌单 ID,分面维度传该维度取值(如歌手名)

Response

无内容