@songloft/client-sdk 2.21.0 → 2.23.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,201 @@
1
+ Apache License
2
+ Version 2.0, January 2004
3
+ http://www.apache.org/licenses/
4
+
5
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
6
+
7
+ 1. Definitions.
8
+
9
+ "License" shall mean the terms and conditions for use, reproduction,
10
+ and distribution as defined by Sections 1 through 9 of this document.
11
+
12
+ "Licensor" shall mean the copyright owner or entity authorized by
13
+ the copyright owner that is granting the License.
14
+
15
+ "Legal Entity" shall mean the union of the acting entity and all
16
+ other entities that control, are controlled by, or are under common
17
+ control with that entity. For the purposes of this definition,
18
+ "control" means (i) the power, direct or indirect, to cause the
19
+ direction or management of such entity, whether by contract or
20
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
21
+ outstanding shares, or (iii) beneficial ownership of such entity.
22
+
23
+ "You" (or "Your") shall mean an individual or Legal Entity
24
+ exercising permissions granted by this License.
25
+
26
+ "Source" form shall mean the preferred form for making modifications,
27
+ including but not limited to software source code, documentation
28
+ source, and configuration files.
29
+
30
+ "Object" form shall mean any form resulting from mechanical
31
+ transformation or translation of a Source form, including but
32
+ not limited to compiled object code, generated documentation,
33
+ and conversions to other media types.
34
+
35
+ "Work" shall mean the work of authorship, whether in Source or
36
+ Object form, made available under the License, as indicated by a
37
+ copyright notice that is included in or attached to the work
38
+ (an example is provided in the Appendix below).
39
+
40
+ "Derivative Works" shall mean any work, whether in Source or Object
41
+ form, that is based on (or derived from) the Work and for which the
42
+ editorial revisions, annotations, elaborations, or other modifications
43
+ represent, as a whole, an original work of authorship. For the purposes
44
+ of this License, Derivative Works shall not include works that remain
45
+ separable from, or merely link (or bind by name) to the interfaces of,
46
+ the Work and Derivative Works thereof.
47
+
48
+ "Contribution" shall mean any work of authorship, including
49
+ the original version of the Work and any modifications or additions
50
+ to that Work or Derivative Works thereof, that is intentionally
51
+ submitted to Licensor for inclusion in the Work by the copyright owner
52
+ or by an individual or Legal Entity authorized to submit on behalf of
53
+ the copyright owner. For the purposes of this definition, "submitted"
54
+ means any form of electronic, verbal, or written communication sent
55
+ to the Licensor or its representatives, including but not limited to
56
+ communication on electronic mailing lists, source code control systems,
57
+ and issue tracking systems that are managed by, or on behalf of, the
58
+ Licensor for the purpose of discussing and improving the Work, but
59
+ excluding communication that is conspicuously marked or otherwise
60
+ designated in writing by the copyright owner as "Not a Contribution."
61
+
62
+ "Contributor" shall mean Licensor and any individual or Legal Entity
63
+ on behalf of whom a Contribution has been received by Licensor and
64
+ subsequently incorporated within the Work.
65
+
66
+ 2. Grant of Copyright License. Subject to the terms and conditions of
67
+ this License, each Contributor hereby grants to You a perpetual,
68
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
69
+ copyright license to reproduce, prepare Derivative Works of,
70
+ publicly display, publicly perform, sublicense, and distribute the
71
+ Work and such Derivative Works in Source or Object form.
72
+
73
+ 3. Grant of Patent License. Subject to the terms and conditions of
74
+ this License, each Contributor hereby grants to You a perpetual,
75
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
76
+ (except as stated in this section) patent license to make, have made,
77
+ use, offer to sell, sell, import, and otherwise transfer the Work,
78
+ where such license applies only to those patent claims licensable
79
+ by such Contributor that are necessarily infringed by their
80
+ Contribution(s) alone or by combination of their Contribution(s)
81
+ with the Work to which such Contribution(s) was submitted. If You
82
+ institute patent litigation against any entity (including a
83
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
84
+ or a Contribution incorporated within the Work constitutes direct
85
+ or contributory patent infringement, then any patent licenses
86
+ granted to You under this License for that Work shall terminate
87
+ as of the date such litigation is filed.
88
+
89
+ 4. Redistribution. You may reproduce and distribute copies of the
90
+ Work or Derivative Works thereof in any medium, with or without
91
+ modifications, and in Source or Object form, provided that You
92
+ meet the following conditions:
93
+
94
+ (a) You must give any other recipients of the Work or
95
+ Derivative Works a copy of this License; and
96
+
97
+ (b) You must cause any modified files to carry prominent notices
98
+ stating that You changed the files; and
99
+
100
+ (c) You must retain, in the Source form of any Derivative Works
101
+ that You distribute, all copyright, patent, trademark, and
102
+ attribution notices from the Source form of the Work,
103
+ excluding those notices that do not pertain to any part of
104
+ the Derivative Works; and
105
+
106
+ (d) If the Work includes a "NOTICE" text file as part of its
107
+ distribution, then any Derivative Works that You distribute must
108
+ include a readable copy of the attribution notices contained
109
+ within such NOTICE file, excluding those notices that do not
110
+ pertain to any part of the Derivative Works, in at least one
111
+ of the following places: within a NOTICE text file distributed
112
+ as part of the Derivative Works; within the Source form or
113
+ documentation, if provided along with the Derivative Works; or,
114
+ within a display generated by the Derivative Works, if and
115
+ wherever such third-party notices normally appear. The contents
116
+ of the NOTICE file are for informational purposes only and
117
+ do not modify the License. You may add Your own attribution
118
+ notices within Derivative Works that You distribute, alongside
119
+ or as an addendum to the NOTICE text from the Work, provided
120
+ that such additional attribution notices cannot be construed
121
+ as modifying the License.
122
+
123
+ You may add Your own copyright statement to Your modifications and
124
+ may provide additional or different license terms and conditions
125
+ for use, reproduction, or distribution of Your modifications, or
126
+ for any such Derivative Works as a whole, provided Your use,
127
+ reproduction, and distribution of the Work otherwise complies with
128
+ the conditions stated in this License.
129
+
130
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
131
+ any Contribution intentionally submitted for inclusion in the Work
132
+ by You to the Licensor shall be under the terms and conditions of
133
+ this License, without any additional terms or conditions.
134
+ Notwithstanding the above, nothing herein shall supersede or modify
135
+ the terms of any separate license agreement you may have executed
136
+ with Licensor regarding such Contributions.
137
+
138
+ 6. Trademarks. This License does not grant permission to use the trade
139
+ names, trademarks, service marks, or product names of the Licensor,
140
+ except as required for reasonable and customary use in describing the
141
+ origin of the Work and reproducing the content of the NOTICE file.
142
+
143
+ 7. Disclaimer of Warranty. Unless required by applicable law or
144
+ agreed to in writing, Licensor provides the Work (and each
145
+ Contributor provides its Contributions) on an "AS IS" BASIS,
146
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
147
+ implied, including, without limitation, any warranties or conditions
148
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
149
+ PARTICULAR PURPOSE. You are solely responsible for determining the
150
+ appropriateness of using or redistributing the Work and assume any
151
+ risks associated with Your exercise of permissions under this License.
152
+
153
+ 8. Limitation of Liability. In no event and under no legal theory,
154
+ whether in tort (including negligence), contract, or otherwise,
155
+ unless required by applicable law (such as deliberate and grossly
156
+ negligent acts) or agreed to in writing, shall any Contributor be
157
+ liable to You for damages, including any direct, indirect, special,
158
+ incidental, or consequential damages of any character arising as a
159
+ result of this License or out of the use or inability to use the
160
+ Work (including but not limited to damages for loss of goodwill,
161
+ work stoppage, computer failure or malfunction, or any and all
162
+ other commercial damages or losses), even if such Contributor
163
+ has been advised of the possibility of such damages.
164
+
165
+ 9. Accepting Warranty or Additional Liability. While redistributing
166
+ the Work or Derivative Works thereof, You may choose to offer,
167
+ and charge a fee for, acceptance of support, warranty, indemnity,
168
+ or other liability obligations and/or rights consistent with this
169
+ License. However, in accepting such obligations, You may act only
170
+ on Your own behalf and on Your sole responsibility, not on behalf
171
+ of any other Contributor, and only if You agree to indemnify,
172
+ defend, and hold each Contributor harmless for any liability
173
+ incurred by, or claims asserted against, such Contributor by reason
174
+ of your accepting any such warranty or additional liability.
175
+
176
+ END OF TERMS AND CONDITIONS
177
+
178
+ APPENDIX: How to apply the Apache License to your work.
179
+
180
+ To apply the Apache License to your work, attach the following
181
+ boilerplate notice, with the fields enclosed by brackets "[]"
182
+ replaced with your own identifying information. (Don't include
183
+ the brackets!) The text should be enclosed in the appropriate
184
+ comment syntax for the file format. We also recommend that a
185
+ file or class name and description of purpose be included on the
186
+ same "printed page" as the copyright notice for easier
187
+ identification within third-party archives.
188
+
189
+ Copyright [yyyy] [name of copyright owner]
190
+
191
+ Licensed under the Apache License, Version 2.0 (the "License");
192
+ you may not use this file except in compliance with the License.
193
+ You may obtain a copy of the License at
194
+
195
+ http://www.apache.org/licenses/LICENSE-2.0
196
+
197
+ Unless required by applicable law or agreed to in writing, software
198
+ distributed under the License is distributed on an "AS IS" BASIS,
199
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
200
+ See the License for the specific language governing permissions and
201
+ limitations under the License.
package/README.md CHANGED
@@ -94,6 +94,10 @@ if (isClient()) {
94
94
 
95
95
  完整类型见包内 `.d.ts`(`ClientSong` / `ClientPlayerState` / `HostInfo` / `PlayMode` 等)。
96
96
 
97
+ ### 播放音效
98
+
99
+ 通过 `host.getInfo().capabilities` 判断宿主是否提供 `player.audioEffects`。插件发起播放后,用 `player.getAudioEffects()` 读取 `playbackId` 和 `supported`。按宿主报告的预设调用 `player.applyAudioEffects({ playbackId, effects: { equalizer: { preset: 'vocal' } } })`。调用 `player.clearAudioEffects({ playbackId })` 恢复用户设置,当前歌曲继续播放。见 [宿主接口文档](https://github.com/songloft-org/songloft-player-lynx/blob/main/docs/reference/plugin-client-sdk.md#插件播放音效)。
100
+
97
101
  ### `favorite`
98
102
 
99
103
  收藏状态同步。插件自己改完收藏(如直接 POST `/playlists/1/songs`)后**必须**调一次——服务端数据是对的,但 Flutter 侧曲库的红心读的是 `FavoriteNotifier` 的内存缓存,不会自动跟着变。
package/dist/index.cjs CHANGED
@@ -48,6 +48,11 @@ function requireHost() {
48
48
  }
49
49
  var player = {
50
50
  getState: () => requirePlayer().getState(),
51
+ getAudioEffects: () => invokeHost("player", "getAudioEffects"),
52
+ applyAudioEffects: ({ playbackId, effects }) => invokeHost("player", "applyAudioEffects", { playbackId, effects }),
53
+ clearAudioEffects: async ({ playbackId }) => {
54
+ await invokeHost("player", "clearAudioEffects", { playbackId });
55
+ },
51
56
  setQueue: (ids, options) => requirePlayer().setQueue(ids, options),
52
57
  addToQueue: (ids) => requirePlayer().addToQueue(ids),
53
58
  insertToQueue: (index, id) => requirePlayer().insertToQueue(index, id),
@@ -1 +1 @@
1
- {"version":3,"sources":["../src/index.ts"],"sourcesContent":["// @songloft/client-sdk — 客户端 SDK\n//\n// 让「在 Songloft Flutter 客户端 webview 中打开的插件页面」调用宿主客户端能力\n// (改写正在播放队列、控制播放、订阅播放状态等)。\n//\n// 架构:运行时能力由宿主注入到 `window.SongloftPlugin`(common.js + Flutter 宿主)。\n// 传输由 common.js 按宿主环境自动选择,插件无需关心:\n// - native 客户端 + 系统 WebView → flutter_inappwebview.callHandler\n// - Web 端插件页(Tab 内嵌页与首页/全屏页均在宿主 iframe 内)→ postMessage\n// 本包是**类型层 + 便捷封装**,所有调用都委托给注入的全局对象,因此:\n// - native 客户端 webview 插件页、Web 端 iframe 内嵌插件页内有效;\n// - 仅当用户通过「在浏览器中打开」将插件页在独立新标签打开(无宿主父窗口)、\n// 或宿主版本过旧时,`isClient()` / `host.isAvailable()` 返回 false,调用会抛出明确错误,请先 feature-detect。\n//\n// 用法:\n// import { player, host, isClient } from '@songloft/client-sdk';\n// if (isClient()) {\n// await player.setQueue([101, 102], { startIndex: 0 });\n// player.onStateChange((s) => console.log(s.current_index));\n// }\n//\n// 免构建的 vanilla 插件可直接用注入的全局对象:\n// window.SongloftPlugin.player.setQueue([101, 102]);\n\n// ===== 数据模型 =====\n\n/** 播放模式(与宿主一致)。 */\nexport type PlayMode = 'order' | 'loop' | 'single' | 'random' | 'singlePlay';\n\n/**\n * 队列中的歌曲对象(宿主返回值,字段为 snake_case,与后端 JSON 一致)。\n * 只列出常用字段;宿主可能返回更多字段。\n */\nexport interface ClientSong {\n id: number;\n type: 'local' | 'remote' | 'radio';\n title: string;\n artist?: string;\n album?: string;\n duration?: number;\n url?: string;\n cover_url?: string;\n lyric_url?: string;\n is_live?: boolean;\n [key: string]: unknown;\n}\n\n/** 播放器状态快照(`player.getState()` / `onStateChange` 回调)。 */\nexport interface ClientPlayerState {\n /** 正在播放队列 */\n queue: ClientSong[];\n /** 当前歌曲在队列中的下标;无歌曲时为 -1 */\n current_index: number;\n /** 当前歌曲;无歌曲时为 null */\n current_song: ClientSong | null;\n is_playing: boolean;\n /** 当前播放进度(秒) */\n current_time: number;\n /** 当前歌曲总时长(秒) */\n duration: number;\n /** 音量 0-100 */\n volume: number;\n play_mode: PlayMode;\n /** 队列来源的服务端歌单 id(如有) */\n source_playlist_id?: number | null;\n}\n\n/** 宿主信息与能力协商结果(`host.getInfo()`)。 */\nexport interface HostInfo {\n /** 客户端应用版本,如 \"2.12.0\" */\n version: string;\n /** 运行平台:android / ios / macos / windows / linux / web */\n platform: string;\n /** 宿主支持的能力命名空间,如 [\"player\"],用于向前兼容的能力协商 */\n capabilities: string[];\n}\n\n/** `setQueue` 的可选参数。 */\nexport interface SetQueueOptions {\n /** 从队列的哪一首开始播放,默认 0 */\n startIndex?: number;\n /** 标记队列来源的服务端歌单 id(可选,仅用于 UI 展示归属) */\n sourcePlaylistId?: number;\n}\n\n// ===== 注入的全局对象类型(window.SongloftPlugin) =====\n\n/** 宿主客户端能力:播放器命名空间。 */\nexport interface SongloftPluginPlayer {\n /** 获取当前播放器状态快照 */\n getState(): Promise<ClientPlayerState>;\n /** 用歌曲 id 列表替换整个正在播放队列并开始播放 */\n setQueue(ids: number[], options?: SetQueueOptions): Promise<void>;\n /** 追加歌曲到队列末尾(去重,不改变当前播放) */\n addToQueue(ids: number[]): Promise<void>;\n /** 在队列指定位置插入一首歌(不触发播放) */\n insertToQueue(index: number, id: number): Promise<void>;\n /** 移除队列中指定下标的歌曲 */\n removeFromQueue(index: number): Promise<void>;\n /** 重排队列 */\n reorderQueue(oldIndex: number, newIndex: number): Promise<void>;\n /** 清空队列 */\n clearQueue(): Promise<void>;\n /** 播放:传 id 则播放该歌曲(不在队列则追加),不传则恢复播放 */\n play(id?: number): Promise<void>;\n /** 暂停 */\n pause(): Promise<void>;\n /** 播放/暂停切换 */\n togglePlay(): Promise<void>;\n /** 下一首 */\n next(): Promise<void>;\n /** 上一首 */\n prev(): Promise<void>;\n /** 跳转到指定进度(秒) */\n seek(seconds: number): Promise<void>;\n /** 设置音量 0-100 */\n setVolume(volume: number): Promise<void>;\n /** 设置播放模式 */\n setPlayMode(mode: PlayMode): Promise<void>;\n /** 直接播放服务端歌单(按歌单 id) */\n playPlaylistById(playlistId: number): Promise<void>;\n /**\n * 订阅播放状态变更。返回取消订阅函数。\n * 注意:状态推送经过节流,`current_time` 可能不是每秒更新。\n */\n onStateChange(handler: (state: ClientPlayerState) => void): () => void;\n}\n\n/** 宿主客户端能力:host 命名空间。 */\nexport interface SongloftPluginHost {\n /** 同步 feature-detect:当前是否运行在支持原生桥接的 Songloft 客户端 webview 内 */\n isAvailable(): boolean;\n /** 获取宿主信息与能力列表 */\n getInfo(): Promise<HostInfo>;\n}\n\n/** 宿主客户端能力:favorite 命名空间。 */\nexport interface SongloftPluginFavorite {\n /**\n * 通知宿主刷新收藏状态缓存。\n *\n * 插件自己改完收藏(如直接 POST `/playlists/1/songs`)后必须调一次:服务端\n * 数据是对的,但 Flutter 侧曲库的红心读的是 `FavoriteNotifier` 的内存缓存,\n * 不会自动跟着变。\n *\n * **能带参就带参**——带参是增量更新,宿主只改这一首的归属;不带参是全量重载,\n * 曲库上千首时是一次完整的往返。\n *\n * @param songId 歌曲 ID;省略则全量重载\n * @param isFavorited 操作后的收藏态;省略则全量重载\n */\n refresh(songId?: number, isFavorited?: boolean): Promise<void>;\n}\n\n/**\n * 注入到页面的 `window.SongloftPlugin` 全局对象。\n * 由主程序 common.js 注入到所有插件 HTML 页面。此处仅声明本 SDK 依赖的成员,\n * 现有的 apiGet/apiPost/getTheme 等成员见插件开发指南。\n *\n * ⚠️ **这份声明必须与 `common.js` 末尾那个对象字面量保持一致**,它才是公开成员的\n * 唯一真实来源。别在插件里另手写一份宿主 API 声明:曾经有插件自己声明了\n * `invokeHost?`(当时它只存在于内部句柄 `window.__SongloftInternal`),于是\n * `SongloftPlugin?.invokeHost?.(...)` 通过 TS 编译、运行时被可选调用静默吞掉,\n * 整个功能一个字节都没发出去(songloft-org/songloft-plugin-miot#86)。\n */\nexport interface SongloftPluginGlobal {\n host?: SongloftPluginHost;\n player?: SongloftPluginPlayer;\n favorite?: SongloftPluginFavorite;\n /**\n * 通用宿主调用出口。`host` / `player` / `favorite` / `getCookies` 都是它的\n * typed wrapper;公开它是为了让插件能触达尚未被 wrapper 覆盖的 namespace\n * (宿主分发表在客户端侧,可能比服务端那份 common.js 更新)。\n *\n * ⚠️ 没有 wrapper 那层类型约束,`ns` / `method` 拼错只会在运行时 reject。\n * 有对应 wrapper 时优先用 wrapper。\n */\n invokeHost?(ns: string, method: string, params?: Record<string, unknown>): Promise<unknown>;\n /**\n * 读取宿主 WebView Cookie Store 中指定 origin 的 Cookie。\n * 原生层读取,不受浏览器同源策略 / HttpOnly 限制。\n *\n * 仅原生客户端(Android/iOS/macOS/Windows/Linux)可用,Web 端调用会 reject。\n *\n * @param origin 目标站点 origin,例如 \"https://example.com\"(含协议 + 主机 + 端口)\n * @returns name → value 映射;该 origin 无 Cookie 时返回空对象 {}\n */\n getCookies?(origin: string): Promise<Record<string, string>>;\n // 现有成员(主题 / API 工具)——保留为可选,避免与旧宿主冲突。\n getTheme?(): 'light' | 'dark';\n onThemeChange?(cb: (theme: 'light' | 'dark') => void): void;\n apiGet?(path: string): Promise<unknown>;\n apiPost?(path: string, body: unknown): Promise<unknown>;\n apiPut?(path: string, body: unknown): Promise<unknown>;\n apiDelete?(path: string): Promise<unknown>;\n [key: string]: unknown;\n}\n\ndeclare global {\n interface Window {\n SongloftPlugin?: SongloftPluginGlobal;\n }\n}\n\n// ===== 便捷封装(委托注入的全局对象) =====\n\nconst NOT_AVAILABLE_MSG =\n '[@songloft/client-sdk] 宿主客户端桥接不可用:请确保插件页在 Songloft 客户端(非 Web)的 webview 中打开,且客户端版本支持客户端 SDK。可用 isClient() 预先检测。';\n\nfunction getGlobal(): SongloftPluginGlobal | undefined {\n return typeof window !== 'undefined' ? window.SongloftPlugin : undefined;\n}\n\n/**\n * 是否运行在支持原生桥接的 Songloft 客户端 webview 内。\n * 调用任何 player/host 方法前建议先检测。\n */\nexport function isClient(): boolean {\n const g = getGlobal();\n return !!(g && g.host && typeof g.host.isAvailable === 'function' && g.host.isAvailable());\n}\n\nfunction requirePlayer(): SongloftPluginPlayer {\n const g = getGlobal();\n if (!g || !g.player) throw new Error(NOT_AVAILABLE_MSG);\n return g.player;\n}\n\nfunction requireHost(): SongloftPluginHost {\n const g = getGlobal();\n if (!g || !g.host) throw new Error(NOT_AVAILABLE_MSG);\n return g.host;\n}\n\n/** 播放器控制。所有方法委托注入的 `window.SongloftPlugin.player`。 */\nexport const player: SongloftPluginPlayer = {\n getState: () => requirePlayer().getState(),\n setQueue: (ids, options) => requirePlayer().setQueue(ids, options),\n addToQueue: (ids) => requirePlayer().addToQueue(ids),\n insertToQueue: (index, id) => requirePlayer().insertToQueue(index, id),\n removeFromQueue: (index) => requirePlayer().removeFromQueue(index),\n reorderQueue: (oldIndex, newIndex) => requirePlayer().reorderQueue(oldIndex, newIndex),\n clearQueue: () => requirePlayer().clearQueue(),\n play: (id) => requirePlayer().play(id),\n pause: () => requirePlayer().pause(),\n togglePlay: () => requirePlayer().togglePlay(),\n next: () => requirePlayer().next(),\n prev: () => requirePlayer().prev(),\n seek: (seconds) => requirePlayer().seek(seconds),\n setVolume: (volume) => requirePlayer().setVolume(volume),\n setPlayMode: (mode) => requirePlayer().setPlayMode(mode),\n playPlaylistById: (playlistId) => requirePlayer().playPlaylistById(playlistId),\n onStateChange: (handler) => requirePlayer().onStateChange(handler),\n};\n\n/** 宿主信息与能力协商。委托注入的 `window.SongloftPlugin.host`。 */\nexport const host: SongloftPluginHost = {\n isAvailable: () => isClient(),\n getInfo: () => requireHost().getInfo(),\n};\n\nfunction requireFavorite(): SongloftPluginFavorite {\n const g = getGlobal();\n if (!g || !g.favorite) throw new Error(NOT_AVAILABLE_MSG);\n return g.favorite;\n}\n\n/** 收藏状态同步。委托注入的 `window.SongloftPlugin.favorite`。 */\nexport const favorite: SongloftPluginFavorite = {\n refresh: (songId, isFavorited) => requireFavorite().refresh(songId, isFavorited),\n};\n\n/**\n * 读取宿主 WebView Cookie Store 中指定 origin 的 Cookie。\n * 仅原生客户端可用,Web 端调用会 reject。\n *\n * @param origin 目标站点 origin,例如 \"https://example.com\"\n * @returns name → value 映射\n */\nexport function getCookies(origin: string): Promise<Record<string, string>> {\n const g = getGlobal();\n if (!g || typeof g.getCookies !== 'function') {\n return Promise.reject(new Error('getCookies is not available on this platform (requires native client)'));\n }\n return g.getCookies(origin);\n}\n\n/**\n * 通用宿主调用。上面的 `player` / `host` / `favorite` / `getCookies` 都是它的\n * typed wrapper —— **有 wrapper 时优先用 wrapper**,这里没有那层类型约束,\n * `ns` / `method` 拼错只会在运行时 reject。\n *\n * 留这个出口是因为宿主分发表在客户端侧,可能比服务端那份 `common.js` 更新,\n * 插件需要能触达尚未被 wrapper 覆盖的 namespace。\n *\n * @param ns 命名空间,如 \"favorite\"\n * @param method 方法名,如 \"refresh\"\n * @param params 参数对象,可省略\n */\nexport function invokeHost(\n ns: string,\n method: string,\n params?: Record<string, unknown>,\n): Promise<unknown> {\n const g = getGlobal();\n if (!g || typeof g.invokeHost !== 'function') {\n return Promise.reject(new Error(NOT_AVAILABLE_MSG));\n }\n return g.invokeHost(ns, method, params);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AA8MA,IAAM,oBACJ;AAEF,SAAS,YAA8C;AACrD,SAAO,OAAO,WAAW,cAAc,OAAO,iBAAiB;AACjE;AAMO,SAAS,WAAoB;AAClC,QAAM,IAAI,UAAU;AACpB,SAAO,CAAC,EAAE,KAAK,EAAE,QAAQ,OAAO,EAAE,KAAK,gBAAgB,cAAc,EAAE,KAAK,YAAY;AAC1F;AAEA,SAAS,gBAAsC;AAC7C,QAAM,IAAI,UAAU;AACpB,MAAI,CAAC,KAAK,CAAC,EAAE,OAAQ,OAAM,IAAI,MAAM,iBAAiB;AACtD,SAAO,EAAE;AACX;AAEA,SAAS,cAAkC;AACzC,QAAM,IAAI,UAAU;AACpB,MAAI,CAAC,KAAK,CAAC,EAAE,KAAM,OAAM,IAAI,MAAM,iBAAiB;AACpD,SAAO,EAAE;AACX;AAGO,IAAM,SAA+B;AAAA,EAC1C,UAAU,MAAM,cAAc,EAAE,SAAS;AAAA,EACzC,UAAU,CAAC,KAAK,YAAY,cAAc,EAAE,SAAS,KAAK,OAAO;AAAA,EACjE,YAAY,CAAC,QAAQ,cAAc,EAAE,WAAW,GAAG;AAAA,EACnD,eAAe,CAAC,OAAO,OAAO,cAAc,EAAE,cAAc,OAAO,EAAE;AAAA,EACrE,iBAAiB,CAAC,UAAU,cAAc,EAAE,gBAAgB,KAAK;AAAA,EACjE,cAAc,CAAC,UAAU,aAAa,cAAc,EAAE,aAAa,UAAU,QAAQ;AAAA,EACrF,YAAY,MAAM,cAAc,EAAE,WAAW;AAAA,EAC7C,MAAM,CAAC,OAAO,cAAc,EAAE,KAAK,EAAE;AAAA,EACrC,OAAO,MAAM,cAAc,EAAE,MAAM;AAAA,EACnC,YAAY,MAAM,cAAc,EAAE,WAAW;AAAA,EAC7C,MAAM,MAAM,cAAc,EAAE,KAAK;AAAA,EACjC,MAAM,MAAM,cAAc,EAAE,KAAK;AAAA,EACjC,MAAM,CAAC,YAAY,cAAc,EAAE,KAAK,OAAO;AAAA,EAC/C,WAAW,CAAC,WAAW,cAAc,EAAE,UAAU,MAAM;AAAA,EACvD,aAAa,CAAC,SAAS,cAAc,EAAE,YAAY,IAAI;AAAA,EACvD,kBAAkB,CAAC,eAAe,cAAc,EAAE,iBAAiB,UAAU;AAAA,EAC7E,eAAe,CAAC,YAAY,cAAc,EAAE,cAAc,OAAO;AACnE;AAGO,IAAM,OAA2B;AAAA,EACtC,aAAa,MAAM,SAAS;AAAA,EAC5B,SAAS,MAAM,YAAY,EAAE,QAAQ;AACvC;AAEA,SAAS,kBAA0C;AACjD,QAAM,IAAI,UAAU;AACpB,MAAI,CAAC,KAAK,CAAC,EAAE,SAAU,OAAM,IAAI,MAAM,iBAAiB;AACxD,SAAO,EAAE;AACX;AAGO,IAAM,WAAmC;AAAA,EAC9C,SAAS,CAAC,QAAQ,gBAAgB,gBAAgB,EAAE,QAAQ,QAAQ,WAAW;AACjF;AASO,SAAS,WAAW,QAAiD;AAC1E,QAAM,IAAI,UAAU;AACpB,MAAI,CAAC,KAAK,OAAO,EAAE,eAAe,YAAY;AAC5C,WAAO,QAAQ,OAAO,IAAI,MAAM,uEAAuE,CAAC;AAAA,EAC1G;AACA,SAAO,EAAE,WAAW,MAAM;AAC5B;AAcO,SAAS,WACd,IACA,QACA,QACkB;AAClB,QAAM,IAAI,UAAU;AACpB,MAAI,CAAC,KAAK,OAAO,EAAE,eAAe,YAAY;AAC5C,WAAO,QAAQ,OAAO,IAAI,MAAM,iBAAiB,CAAC;AAAA,EACpD;AACA,SAAO,EAAE,WAAW,IAAI,QAAQ,MAAM;AACxC;","names":[]}
1
+ {"version":3,"sources":["../src/index.ts"],"sourcesContent":["// @songloft/client-sdk — 客户端 SDK\n//\n// 让「在 Songloft Flutter 客户端 webview 中打开的插件页面」调用宿主客户端能力\n// (改写正在播放队列、控制播放、订阅播放状态等)。\n//\n// 架构:运行时能力由宿主注入到 `window.SongloftPlugin`(common.js + Flutter 宿主)。\n// 传输由 common.js 按宿主环境自动选择,插件无需关心:\n// - native 客户端 + 系统 WebView → flutter_inappwebview.callHandler\n// - Web 端插件页(Tab 内嵌页与首页/全屏页均在宿主 iframe 内)→ postMessage\n// 本包是**类型层 + 便捷封装**,所有调用都委托给注入的全局对象,因此:\n// - native 客户端 webview 插件页、Web 端 iframe 内嵌插件页内有效;\n// - 仅当用户通过「在浏览器中打开」将插件页在独立新标签打开(无宿主父窗口)、\n// 或宿主版本过旧时,`isClient()` / `host.isAvailable()` 返回 false,调用会抛出明确错误,请先 feature-detect。\n//\n// 用法:\n// import { player, host, isClient } from '@songloft/client-sdk';\n// if (isClient()) {\n// await player.setQueue([101, 102], { startIndex: 0 });\n// player.onStateChange((s) => console.log(s.current_index));\n// }\n//\n// 免构建的 vanilla 插件可直接用注入的全局对象:\n// window.SongloftPlugin.player.setQueue([101, 102]);\n\n// ===== 数据模型 =====\n\n/** 播放模式(与宿主一致)。 */\nexport type PlayMode = 'order' | 'loop' | 'single' | 'random' | 'singlePlay';\n\n/**\n * 队列中的歌曲对象(宿主返回值,字段为 snake_case,与后端 JSON 一致)。\n * 只列出常用字段;宿主可能返回更多字段。\n */\nexport interface ClientSong {\n id: number;\n type: 'local' | 'remote' | 'radio';\n title: string;\n artist?: string;\n album?: string;\n duration?: number;\n url?: string;\n cover_url?: string;\n lyric_url?: string;\n is_live?: boolean;\n [key: string]: unknown;\n}\n\n/** 播放器状态快照(`player.getState()` / `onStateChange` 回调)。 */\nexport interface ClientPlayerState {\n /** 正在播放队列 */\n queue: ClientSong[];\n /** 当前歌曲在队列中的下标;无歌曲时为 -1 */\n current_index: number;\n /** 当前歌曲;无歌曲时为 null */\n current_song: ClientSong | null;\n is_playing: boolean;\n /** 当前播放进度(秒) */\n current_time: number;\n /** 当前歌曲总时长(秒) */\n duration: number;\n /** 音量 0-100 */\n volume: number;\n play_mode: PlayMode;\n /** 队列来源的服务端歌单 id(如有) */\n source_playlist_id?: number | null;\n}\n\n/** 宿主信息与能力协商结果(`host.getInfo()`)。 */\nexport interface HostInfo {\n /** 客户端应用版本,如 \"2.12.0\" */\n version: string;\n /** 运行平台:android / ios / macos / windows / linux / web */\n platform: string;\n /** 宿主支持的能力命名空间,如 [\"player\"],用于向前兼容的能力协商 */\n capabilities: string[];\n}\n\n/** `setQueue` 的可选参数。 */\nexport interface SetQueueOptions {\n /** 从队列的哪一首开始播放,默认 0 */\n startIndex?: number;\n /** 标记队列来源的服务端歌单 id(可选,仅用于 UI 展示归属) */\n sourcePlaylistId?: number;\n}\n\n/** Temporary host audio effects for a plugin's playback session. */\nexport interface PlaybackAudioEffects {\n equalizer?: { preset: string };\n reverb?: { preset: string };\n}\n\nexport interface PlaybackAudioEffectsState {\n playbackId: string | null;\n supported: {\n equalizer?: { presets: string[] };\n reverb?: { presets: string[] };\n };\n applied: PlaybackAudioEffects | null;\n}\n\nexport interface ApplyPlaybackAudioEffectsOptions {\n playbackId: string;\n effects: PlaybackAudioEffects;\n}\n\n// ===== 注入的全局对象类型(window.SongloftPlugin) =====\n\n/** 宿主客户端能力:播放器命名空间。 */\nexport interface SongloftPluginPlayer {\n /** 获取当前播放器状态快照 */\n getState(): Promise<ClientPlayerState>;\n /** Query the output's supported effects and this plugin's current playback session. */\n getAudioEffects(): Promise<PlaybackAudioEffectsState>;\n /** Replace the temporary effects for this plugin's playback session. */\n applyAudioEffects(options: ApplyPlaybackAudioEffectsOptions): Promise<PlaybackAudioEffects | null>;\n /** Restore the user's effects for this plugin's playback session. */\n clearAudioEffects(options: { playbackId: string }): Promise<void>;\n /** 用歌曲 id 列表替换整个正在播放队列并开始播放 */\n setQueue(ids: number[], options?: SetQueueOptions): Promise<void>;\n /** 追加歌曲到队列末尾(去重,不改变当前播放) */\n addToQueue(ids: number[]): Promise<void>;\n /** 在队列指定位置插入一首歌(不触发播放) */\n insertToQueue(index: number, id: number): Promise<void>;\n /** 移除队列中指定下标的歌曲 */\n removeFromQueue(index: number): Promise<void>;\n /** 重排队列 */\n reorderQueue(oldIndex: number, newIndex: number): Promise<void>;\n /** 清空队列 */\n clearQueue(): Promise<void>;\n /** 播放:传 id 则播放该歌曲(不在队列则追加),不传则恢复播放 */\n play(id?: number): Promise<void>;\n /** 暂停 */\n pause(): Promise<void>;\n /** 播放/暂停切换 */\n togglePlay(): Promise<void>;\n /** 下一首 */\n next(): Promise<void>;\n /** 上一首 */\n prev(): Promise<void>;\n /** 跳转到指定进度(秒) */\n seek(seconds: number): Promise<void>;\n /** 设置音量 0-100 */\n setVolume(volume: number): Promise<void>;\n /** 设置播放模式 */\n setPlayMode(mode: PlayMode): Promise<void>;\n /** 直接播放服务端歌单(按歌单 id) */\n playPlaylistById(playlistId: number): Promise<void>;\n /**\n * 订阅播放状态变更。返回取消订阅函数。\n * 注意:状态推送经过节流,`current_time` 可能不是每秒更新。\n */\n onStateChange(handler: (state: ClientPlayerState) => void): () => void;\n}\n\n/** 宿主客户端能力:host 命名空间。 */\nexport interface SongloftPluginHost {\n /** 同步 feature-detect:当前是否运行在支持原生桥接的 Songloft 客户端 webview 内 */\n isAvailable(): boolean;\n /** 获取宿主信息与能力列表 */\n getInfo(): Promise<HostInfo>;\n}\n\n/** 宿主客户端能力:favorite 命名空间。 */\nexport interface SongloftPluginFavorite {\n /**\n * 通知宿主刷新收藏状态缓存。\n *\n * 插件自己改完收藏(如直接 POST `/playlists/1/songs`)后必须调一次:服务端\n * 数据是对的,但 Flutter 侧曲库的红心读的是 `FavoriteNotifier` 的内存缓存,\n * 不会自动跟着变。\n *\n * **能带参就带参**——带参是增量更新,宿主只改这一首的归属;不带参是全量重载,\n * 曲库上千首时是一次完整的往返。\n *\n * @param songId 歌曲 ID;省略则全量重载\n * @param isFavorited 操作后的收藏态;省略则全量重载\n */\n refresh(songId?: number, isFavorited?: boolean): Promise<void>;\n}\n\n/**\n * 注入到页面的 `window.SongloftPlugin` 全局对象。\n * 由主程序 common.js 注入到所有插件 HTML 页面。此处仅声明本 SDK 依赖的成员,\n * 现有的 apiGet/apiPost/getTheme 等成员见插件开发指南。\n *\n * ⚠️ **这份声明必须与 `common.js` 末尾那个对象字面量保持一致**,它才是公开成员的\n * 唯一真实来源。别在插件里另手写一份宿主 API 声明:曾经有插件自己声明了\n * `invokeHost?`(当时它只存在于内部句柄 `window.__SongloftInternal`),于是\n * `SongloftPlugin?.invokeHost?.(...)` 通过 TS 编译、运行时被可选调用静默吞掉,\n * 整个功能一个字节都没发出去(songloft-org/songloft-plugin-miot#86)。\n */\nexport interface SongloftPluginGlobal {\n host?: SongloftPluginHost;\n player?: SongloftPluginPlayer;\n favorite?: SongloftPluginFavorite;\n /**\n * 通用宿主调用出口。`host` / `player` / `favorite` / `getCookies` 都是它的\n * typed wrapper;公开它是为了让插件能触达尚未被 wrapper 覆盖的 namespace\n * (宿主分发表在客户端侧,可能比服务端那份 common.js 更新)。\n *\n * ⚠️ 没有 wrapper 那层类型约束,`ns` / `method` 拼错只会在运行时 reject。\n * 有对应 wrapper 时优先用 wrapper。\n */\n invokeHost?(ns: string, method: string, params?: Record<string, unknown>): Promise<unknown>;\n /**\n * 读取宿主 WebView Cookie Store 中指定 origin 的 Cookie。\n * 原生层读取,不受浏览器同源策略 / HttpOnly 限制。\n *\n * 仅原生客户端(Android/iOS/macOS/Windows/Linux)可用,Web 端调用会 reject。\n *\n * @param origin 目标站点 origin,例如 \"https://example.com\"(含协议 + 主机 + 端口)\n * @returns name → value 映射;该 origin 无 Cookie 时返回空对象 {}\n */\n getCookies?(origin: string): Promise<Record<string, string>>;\n // 现有成员(主题 / API 工具)——保留为可选,避免与旧宿主冲突。\n getTheme?(): 'light' | 'dark';\n onThemeChange?(cb: (theme: 'light' | 'dark') => void): void;\n apiGet?(path: string): Promise<unknown>;\n apiPost?(path: string, body: unknown): Promise<unknown>;\n apiPut?(path: string, body: unknown): Promise<unknown>;\n apiDelete?(path: string): Promise<unknown>;\n [key: string]: unknown;\n}\n\ndeclare global {\n interface Window {\n SongloftPlugin?: SongloftPluginGlobal;\n }\n}\n\n// ===== 便捷封装(委托注入的全局对象) =====\n\nconst NOT_AVAILABLE_MSG =\n '[@songloft/client-sdk] 宿主客户端桥接不可用:请确保插件页在 Songloft 客户端(非 Web)的 webview 中打开,且客户端版本支持客户端 SDK。可用 isClient() 预先检测。';\n\nfunction getGlobal(): SongloftPluginGlobal | undefined {\n return typeof window !== 'undefined' ? window.SongloftPlugin : undefined;\n}\n\n/**\n * 是否运行在支持原生桥接的 Songloft 客户端 webview 内。\n * 调用任何 player/host 方法前建议先检测。\n */\nexport function isClient(): boolean {\n const g = getGlobal();\n return !!(g && g.host && typeof g.host.isAvailable === 'function' && g.host.isAvailable());\n}\n\nfunction requirePlayer(): SongloftPluginPlayer {\n const g = getGlobal();\n if (!g || !g.player) throw new Error(NOT_AVAILABLE_MSG);\n return g.player;\n}\n\nfunction requireHost(): SongloftPluginHost {\n const g = getGlobal();\n if (!g || !g.host) throw new Error(NOT_AVAILABLE_MSG);\n return g.host;\n}\n\n/** 播放器控制。所有方法委托注入的 `window.SongloftPlugin.player`。 */\nexport const player: SongloftPluginPlayer = {\n getState: () => requirePlayer().getState(),\n getAudioEffects: () =>\n invokeHost('player', 'getAudioEffects') as Promise<PlaybackAudioEffectsState>,\n applyAudioEffects: ({ playbackId, effects }) =>\n invokeHost('player', 'applyAudioEffects', { playbackId, effects }) as Promise<PlaybackAudioEffects | null>,\n clearAudioEffects: async ({ playbackId }) => {\n await invokeHost('player', 'clearAudioEffects', { playbackId });\n },\n setQueue: (ids, options) => requirePlayer().setQueue(ids, options),\n addToQueue: (ids) => requirePlayer().addToQueue(ids),\n insertToQueue: (index, id) => requirePlayer().insertToQueue(index, id),\n removeFromQueue: (index) => requirePlayer().removeFromQueue(index),\n reorderQueue: (oldIndex, newIndex) => requirePlayer().reorderQueue(oldIndex, newIndex),\n clearQueue: () => requirePlayer().clearQueue(),\n play: (id) => requirePlayer().play(id),\n pause: () => requirePlayer().pause(),\n togglePlay: () => requirePlayer().togglePlay(),\n next: () => requirePlayer().next(),\n prev: () => requirePlayer().prev(),\n seek: (seconds) => requirePlayer().seek(seconds),\n setVolume: (volume) => requirePlayer().setVolume(volume),\n setPlayMode: (mode) => requirePlayer().setPlayMode(mode),\n playPlaylistById: (playlistId) => requirePlayer().playPlaylistById(playlistId),\n onStateChange: (handler) => requirePlayer().onStateChange(handler),\n};\n\n/** 宿主信息与能力协商。委托注入的 `window.SongloftPlugin.host`。 */\nexport const host: SongloftPluginHost = {\n isAvailable: () => isClient(),\n getInfo: () => requireHost().getInfo(),\n};\n\nfunction requireFavorite(): SongloftPluginFavorite {\n const g = getGlobal();\n if (!g || !g.favorite) throw new Error(NOT_AVAILABLE_MSG);\n return g.favorite;\n}\n\n/** 收藏状态同步。委托注入的 `window.SongloftPlugin.favorite`。 */\nexport const favorite: SongloftPluginFavorite = {\n refresh: (songId, isFavorited) => requireFavorite().refresh(songId, isFavorited),\n};\n\n/**\n * 读取宿主 WebView Cookie Store 中指定 origin 的 Cookie。\n * 仅原生客户端可用,Web 端调用会 reject。\n *\n * @param origin 目标站点 origin,例如 \"https://example.com\"\n * @returns name → value 映射\n */\nexport function getCookies(origin: string): Promise<Record<string, string>> {\n const g = getGlobal();\n if (!g || typeof g.getCookies !== 'function') {\n return Promise.reject(new Error('getCookies is not available on this platform (requires native client)'));\n }\n return g.getCookies(origin);\n}\n\n/**\n * 通用宿主调用。上面的 `player` / `host` / `favorite` / `getCookies` 都是它的\n * typed wrapper —— **有 wrapper 时优先用 wrapper**,这里没有那层类型约束,\n * `ns` / `method` 拼错只会在运行时 reject。\n *\n * 留这个出口是因为宿主分发表在客户端侧,可能比服务端那份 `common.js` 更新,\n * 插件需要能触达尚未被 wrapper 覆盖的 namespace。\n *\n * @param ns 命名空间,如 \"favorite\"\n * @param method 方法名,如 \"refresh\"\n * @param params 参数对象,可省略\n */\nexport function invokeHost(\n ns: string,\n method: string,\n params?: Record<string, unknown>,\n): Promise<unknown> {\n const g = getGlobal();\n if (!g || typeof g.invokeHost !== 'function') {\n return Promise.reject(new Error(NOT_AVAILABLE_MSG));\n }\n return g.invokeHost(ns, method, params);\n}\n"],"mappings":"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","names":[]}
package/dist/index.d.cts CHANGED
@@ -52,10 +52,43 @@ interface SetQueueOptions {
52
52
  /** 标记队列来源的服务端歌单 id(可选,仅用于 UI 展示归属) */
53
53
  sourcePlaylistId?: number;
54
54
  }
55
+ /** Temporary host audio effects for a plugin's playback session. */
56
+ interface PlaybackAudioEffects {
57
+ equalizer?: {
58
+ preset: string;
59
+ };
60
+ reverb?: {
61
+ preset: string;
62
+ };
63
+ }
64
+ interface PlaybackAudioEffectsState {
65
+ playbackId: string | null;
66
+ supported: {
67
+ equalizer?: {
68
+ presets: string[];
69
+ };
70
+ reverb?: {
71
+ presets: string[];
72
+ };
73
+ };
74
+ applied: PlaybackAudioEffects | null;
75
+ }
76
+ interface ApplyPlaybackAudioEffectsOptions {
77
+ playbackId: string;
78
+ effects: PlaybackAudioEffects;
79
+ }
55
80
  /** 宿主客户端能力:播放器命名空间。 */
56
81
  interface SongloftPluginPlayer {
57
82
  /** 获取当前播放器状态快照 */
58
83
  getState(): Promise<ClientPlayerState>;
84
+ /** Query the output's supported effects and this plugin's current playback session. */
85
+ getAudioEffects(): Promise<PlaybackAudioEffectsState>;
86
+ /** Replace the temporary effects for this plugin's playback session. */
87
+ applyAudioEffects(options: ApplyPlaybackAudioEffectsOptions): Promise<PlaybackAudioEffects | null>;
88
+ /** Restore the user's effects for this plugin's playback session. */
89
+ clearAudioEffects(options: {
90
+ playbackId: string;
91
+ }): Promise<void>;
59
92
  /** 用歌曲 id 列表替换整个正在播放队列并开始播放 */
60
93
  setQueue(ids: number[], options?: SetQueueOptions): Promise<void>;
61
94
  /** 追加歌曲到队列末尾(去重,不改变当前播放) */
@@ -196,4 +229,4 @@ declare function getCookies(origin: string): Promise<Record<string, string>>;
196
229
  */
197
230
  declare function invokeHost(ns: string, method: string, params?: Record<string, unknown>): Promise<unknown>;
198
231
 
199
- export { type ClientPlayerState, type ClientSong, type HostInfo, type PlayMode, type SetQueueOptions, type SongloftPluginFavorite, type SongloftPluginGlobal, type SongloftPluginHost, type SongloftPluginPlayer, favorite, getCookies, host, invokeHost, isClient, player };
232
+ export { type ApplyPlaybackAudioEffectsOptions, type ClientPlayerState, type ClientSong, type HostInfo, type PlayMode, type PlaybackAudioEffects, type PlaybackAudioEffectsState, type SetQueueOptions, type SongloftPluginFavorite, type SongloftPluginGlobal, type SongloftPluginHost, type SongloftPluginPlayer, favorite, getCookies, host, invokeHost, isClient, player };
package/dist/index.d.ts CHANGED
@@ -52,10 +52,43 @@ interface SetQueueOptions {
52
52
  /** 标记队列来源的服务端歌单 id(可选,仅用于 UI 展示归属) */
53
53
  sourcePlaylistId?: number;
54
54
  }
55
+ /** Temporary host audio effects for a plugin's playback session. */
56
+ interface PlaybackAudioEffects {
57
+ equalizer?: {
58
+ preset: string;
59
+ };
60
+ reverb?: {
61
+ preset: string;
62
+ };
63
+ }
64
+ interface PlaybackAudioEffectsState {
65
+ playbackId: string | null;
66
+ supported: {
67
+ equalizer?: {
68
+ presets: string[];
69
+ };
70
+ reverb?: {
71
+ presets: string[];
72
+ };
73
+ };
74
+ applied: PlaybackAudioEffects | null;
75
+ }
76
+ interface ApplyPlaybackAudioEffectsOptions {
77
+ playbackId: string;
78
+ effects: PlaybackAudioEffects;
79
+ }
55
80
  /** 宿主客户端能力:播放器命名空间。 */
56
81
  interface SongloftPluginPlayer {
57
82
  /** 获取当前播放器状态快照 */
58
83
  getState(): Promise<ClientPlayerState>;
84
+ /** Query the output's supported effects and this plugin's current playback session. */
85
+ getAudioEffects(): Promise<PlaybackAudioEffectsState>;
86
+ /** Replace the temporary effects for this plugin's playback session. */
87
+ applyAudioEffects(options: ApplyPlaybackAudioEffectsOptions): Promise<PlaybackAudioEffects | null>;
88
+ /** Restore the user's effects for this plugin's playback session. */
89
+ clearAudioEffects(options: {
90
+ playbackId: string;
91
+ }): Promise<void>;
59
92
  /** 用歌曲 id 列表替换整个正在播放队列并开始播放 */
60
93
  setQueue(ids: number[], options?: SetQueueOptions): Promise<void>;
61
94
  /** 追加歌曲到队列末尾(去重,不改变当前播放) */
@@ -196,4 +229,4 @@ declare function getCookies(origin: string): Promise<Record<string, string>>;
196
229
  */
197
230
  declare function invokeHost(ns: string, method: string, params?: Record<string, unknown>): Promise<unknown>;
198
231
 
199
- export { type ClientPlayerState, type ClientSong, type HostInfo, type PlayMode, type SetQueueOptions, type SongloftPluginFavorite, type SongloftPluginGlobal, type SongloftPluginHost, type SongloftPluginPlayer, favorite, getCookies, host, invokeHost, isClient, player };
232
+ export { type ApplyPlaybackAudioEffectsOptions, type ClientPlayerState, type ClientSong, type HostInfo, type PlayMode, type PlaybackAudioEffects, type PlaybackAudioEffectsState, type SetQueueOptions, type SongloftPluginFavorite, type SongloftPluginGlobal, type SongloftPluginHost, type SongloftPluginPlayer, favorite, getCookies, host, invokeHost, isClient, player };
package/dist/index.js CHANGED
@@ -19,6 +19,11 @@ function requireHost() {
19
19
  }
20
20
  var player = {
21
21
  getState: () => requirePlayer().getState(),
22
+ getAudioEffects: () => invokeHost("player", "getAudioEffects"),
23
+ applyAudioEffects: ({ playbackId, effects }) => invokeHost("player", "applyAudioEffects", { playbackId, effects }),
24
+ clearAudioEffects: async ({ playbackId }) => {
25
+ await invokeHost("player", "clearAudioEffects", { playbackId });
26
+ },
22
27
  setQueue: (ids, options) => requirePlayer().setQueue(ids, options),
23
28
  addToQueue: (ids) => requirePlayer().addToQueue(ids),
24
29
  insertToQueue: (index, id) => requirePlayer().insertToQueue(index, id),
package/dist/index.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"sources":["../src/index.ts"],"sourcesContent":["// @songloft/client-sdk — 客户端 SDK\n//\n// 让「在 Songloft Flutter 客户端 webview 中打开的插件页面」调用宿主客户端能力\n// (改写正在播放队列、控制播放、订阅播放状态等)。\n//\n// 架构:运行时能力由宿主注入到 `window.SongloftPlugin`(common.js + Flutter 宿主)。\n// 传输由 common.js 按宿主环境自动选择,插件无需关心:\n// - native 客户端 + 系统 WebView → flutter_inappwebview.callHandler\n// - Web 端插件页(Tab 内嵌页与首页/全屏页均在宿主 iframe 内)→ postMessage\n// 本包是**类型层 + 便捷封装**,所有调用都委托给注入的全局对象,因此:\n// - native 客户端 webview 插件页、Web 端 iframe 内嵌插件页内有效;\n// - 仅当用户通过「在浏览器中打开」将插件页在独立新标签打开(无宿主父窗口)、\n// 或宿主版本过旧时,`isClient()` / `host.isAvailable()` 返回 false,调用会抛出明确错误,请先 feature-detect。\n//\n// 用法:\n// import { player, host, isClient } from '@songloft/client-sdk';\n// if (isClient()) {\n// await player.setQueue([101, 102], { startIndex: 0 });\n// player.onStateChange((s) => console.log(s.current_index));\n// }\n//\n// 免构建的 vanilla 插件可直接用注入的全局对象:\n// window.SongloftPlugin.player.setQueue([101, 102]);\n\n// ===== 数据模型 =====\n\n/** 播放模式(与宿主一致)。 */\nexport type PlayMode = 'order' | 'loop' | 'single' | 'random' | 'singlePlay';\n\n/**\n * 队列中的歌曲对象(宿主返回值,字段为 snake_case,与后端 JSON 一致)。\n * 只列出常用字段;宿主可能返回更多字段。\n */\nexport interface ClientSong {\n id: number;\n type: 'local' | 'remote' | 'radio';\n title: string;\n artist?: string;\n album?: string;\n duration?: number;\n url?: string;\n cover_url?: string;\n lyric_url?: string;\n is_live?: boolean;\n [key: string]: unknown;\n}\n\n/** 播放器状态快照(`player.getState()` / `onStateChange` 回调)。 */\nexport interface ClientPlayerState {\n /** 正在播放队列 */\n queue: ClientSong[];\n /** 当前歌曲在队列中的下标;无歌曲时为 -1 */\n current_index: number;\n /** 当前歌曲;无歌曲时为 null */\n current_song: ClientSong | null;\n is_playing: boolean;\n /** 当前播放进度(秒) */\n current_time: number;\n /** 当前歌曲总时长(秒) */\n duration: number;\n /** 音量 0-100 */\n volume: number;\n play_mode: PlayMode;\n /** 队列来源的服务端歌单 id(如有) */\n source_playlist_id?: number | null;\n}\n\n/** 宿主信息与能力协商结果(`host.getInfo()`)。 */\nexport interface HostInfo {\n /** 客户端应用版本,如 \"2.12.0\" */\n version: string;\n /** 运行平台:android / ios / macos / windows / linux / web */\n platform: string;\n /** 宿主支持的能力命名空间,如 [\"player\"],用于向前兼容的能力协商 */\n capabilities: string[];\n}\n\n/** `setQueue` 的可选参数。 */\nexport interface SetQueueOptions {\n /** 从队列的哪一首开始播放,默认 0 */\n startIndex?: number;\n /** 标记队列来源的服务端歌单 id(可选,仅用于 UI 展示归属) */\n sourcePlaylistId?: number;\n}\n\n// ===== 注入的全局对象类型(window.SongloftPlugin) =====\n\n/** 宿主客户端能力:播放器命名空间。 */\nexport interface SongloftPluginPlayer {\n /** 获取当前播放器状态快照 */\n getState(): Promise<ClientPlayerState>;\n /** 用歌曲 id 列表替换整个正在播放队列并开始播放 */\n setQueue(ids: number[], options?: SetQueueOptions): Promise<void>;\n /** 追加歌曲到队列末尾(去重,不改变当前播放) */\n addToQueue(ids: number[]): Promise<void>;\n /** 在队列指定位置插入一首歌(不触发播放) */\n insertToQueue(index: number, id: number): Promise<void>;\n /** 移除队列中指定下标的歌曲 */\n removeFromQueue(index: number): Promise<void>;\n /** 重排队列 */\n reorderQueue(oldIndex: number, newIndex: number): Promise<void>;\n /** 清空队列 */\n clearQueue(): Promise<void>;\n /** 播放:传 id 则播放该歌曲(不在队列则追加),不传则恢复播放 */\n play(id?: number): Promise<void>;\n /** 暂停 */\n pause(): Promise<void>;\n /** 播放/暂停切换 */\n togglePlay(): Promise<void>;\n /** 下一首 */\n next(): Promise<void>;\n /** 上一首 */\n prev(): Promise<void>;\n /** 跳转到指定进度(秒) */\n seek(seconds: number): Promise<void>;\n /** 设置音量 0-100 */\n setVolume(volume: number): Promise<void>;\n /** 设置播放模式 */\n setPlayMode(mode: PlayMode): Promise<void>;\n /** 直接播放服务端歌单(按歌单 id) */\n playPlaylistById(playlistId: number): Promise<void>;\n /**\n * 订阅播放状态变更。返回取消订阅函数。\n * 注意:状态推送经过节流,`current_time` 可能不是每秒更新。\n */\n onStateChange(handler: (state: ClientPlayerState) => void): () => void;\n}\n\n/** 宿主客户端能力:host 命名空间。 */\nexport interface SongloftPluginHost {\n /** 同步 feature-detect:当前是否运行在支持原生桥接的 Songloft 客户端 webview 内 */\n isAvailable(): boolean;\n /** 获取宿主信息与能力列表 */\n getInfo(): Promise<HostInfo>;\n}\n\n/** 宿主客户端能力:favorite 命名空间。 */\nexport interface SongloftPluginFavorite {\n /**\n * 通知宿主刷新收藏状态缓存。\n *\n * 插件自己改完收藏(如直接 POST `/playlists/1/songs`)后必须调一次:服务端\n * 数据是对的,但 Flutter 侧曲库的红心读的是 `FavoriteNotifier` 的内存缓存,\n * 不会自动跟着变。\n *\n * **能带参就带参**——带参是增量更新,宿主只改这一首的归属;不带参是全量重载,\n * 曲库上千首时是一次完整的往返。\n *\n * @param songId 歌曲 ID;省略则全量重载\n * @param isFavorited 操作后的收藏态;省略则全量重载\n */\n refresh(songId?: number, isFavorited?: boolean): Promise<void>;\n}\n\n/**\n * 注入到页面的 `window.SongloftPlugin` 全局对象。\n * 由主程序 common.js 注入到所有插件 HTML 页面。此处仅声明本 SDK 依赖的成员,\n * 现有的 apiGet/apiPost/getTheme 等成员见插件开发指南。\n *\n * ⚠️ **这份声明必须与 `common.js` 末尾那个对象字面量保持一致**,它才是公开成员的\n * 唯一真实来源。别在插件里另手写一份宿主 API 声明:曾经有插件自己声明了\n * `invokeHost?`(当时它只存在于内部句柄 `window.__SongloftInternal`),于是\n * `SongloftPlugin?.invokeHost?.(...)` 通过 TS 编译、运行时被可选调用静默吞掉,\n * 整个功能一个字节都没发出去(songloft-org/songloft-plugin-miot#86)。\n */\nexport interface SongloftPluginGlobal {\n host?: SongloftPluginHost;\n player?: SongloftPluginPlayer;\n favorite?: SongloftPluginFavorite;\n /**\n * 通用宿主调用出口。`host` / `player` / `favorite` / `getCookies` 都是它的\n * typed wrapper;公开它是为了让插件能触达尚未被 wrapper 覆盖的 namespace\n * (宿主分发表在客户端侧,可能比服务端那份 common.js 更新)。\n *\n * ⚠️ 没有 wrapper 那层类型约束,`ns` / `method` 拼错只会在运行时 reject。\n * 有对应 wrapper 时优先用 wrapper。\n */\n invokeHost?(ns: string, method: string, params?: Record<string, unknown>): Promise<unknown>;\n /**\n * 读取宿主 WebView Cookie Store 中指定 origin 的 Cookie。\n * 原生层读取,不受浏览器同源策略 / HttpOnly 限制。\n *\n * 仅原生客户端(Android/iOS/macOS/Windows/Linux)可用,Web 端调用会 reject。\n *\n * @param origin 目标站点 origin,例如 \"https://example.com\"(含协议 + 主机 + 端口)\n * @returns name → value 映射;该 origin 无 Cookie 时返回空对象 {}\n */\n getCookies?(origin: string): Promise<Record<string, string>>;\n // 现有成员(主题 / API 工具)——保留为可选,避免与旧宿主冲突。\n getTheme?(): 'light' | 'dark';\n onThemeChange?(cb: (theme: 'light' | 'dark') => void): void;\n apiGet?(path: string): Promise<unknown>;\n apiPost?(path: string, body: unknown): Promise<unknown>;\n apiPut?(path: string, body: unknown): Promise<unknown>;\n apiDelete?(path: string): Promise<unknown>;\n [key: string]: unknown;\n}\n\ndeclare global {\n interface Window {\n SongloftPlugin?: SongloftPluginGlobal;\n }\n}\n\n// ===== 便捷封装(委托注入的全局对象) =====\n\nconst NOT_AVAILABLE_MSG =\n '[@songloft/client-sdk] 宿主客户端桥接不可用:请确保插件页在 Songloft 客户端(非 Web)的 webview 中打开,且客户端版本支持客户端 SDK。可用 isClient() 预先检测。';\n\nfunction getGlobal(): SongloftPluginGlobal | undefined {\n return typeof window !== 'undefined' ? window.SongloftPlugin : undefined;\n}\n\n/**\n * 是否运行在支持原生桥接的 Songloft 客户端 webview 内。\n * 调用任何 player/host 方法前建议先检测。\n */\nexport function isClient(): boolean {\n const g = getGlobal();\n return !!(g && g.host && typeof g.host.isAvailable === 'function' && g.host.isAvailable());\n}\n\nfunction requirePlayer(): SongloftPluginPlayer {\n const g = getGlobal();\n if (!g || !g.player) throw new Error(NOT_AVAILABLE_MSG);\n return g.player;\n}\n\nfunction requireHost(): SongloftPluginHost {\n const g = getGlobal();\n if (!g || !g.host) throw new Error(NOT_AVAILABLE_MSG);\n return g.host;\n}\n\n/** 播放器控制。所有方法委托注入的 `window.SongloftPlugin.player`。 */\nexport const player: SongloftPluginPlayer = {\n getState: () => requirePlayer().getState(),\n setQueue: (ids, options) => requirePlayer().setQueue(ids, options),\n addToQueue: (ids) => requirePlayer().addToQueue(ids),\n insertToQueue: (index, id) => requirePlayer().insertToQueue(index, id),\n removeFromQueue: (index) => requirePlayer().removeFromQueue(index),\n reorderQueue: (oldIndex, newIndex) => requirePlayer().reorderQueue(oldIndex, newIndex),\n clearQueue: () => requirePlayer().clearQueue(),\n play: (id) => requirePlayer().play(id),\n pause: () => requirePlayer().pause(),\n togglePlay: () => requirePlayer().togglePlay(),\n next: () => requirePlayer().next(),\n prev: () => requirePlayer().prev(),\n seek: (seconds) => requirePlayer().seek(seconds),\n setVolume: (volume) => requirePlayer().setVolume(volume),\n setPlayMode: (mode) => requirePlayer().setPlayMode(mode),\n playPlaylistById: (playlistId) => requirePlayer().playPlaylistById(playlistId),\n onStateChange: (handler) => requirePlayer().onStateChange(handler),\n};\n\n/** 宿主信息与能力协商。委托注入的 `window.SongloftPlugin.host`。 */\nexport const host: SongloftPluginHost = {\n isAvailable: () => isClient(),\n getInfo: () => requireHost().getInfo(),\n};\n\nfunction requireFavorite(): SongloftPluginFavorite {\n const g = getGlobal();\n if (!g || !g.favorite) throw new Error(NOT_AVAILABLE_MSG);\n return g.favorite;\n}\n\n/** 收藏状态同步。委托注入的 `window.SongloftPlugin.favorite`。 */\nexport const favorite: SongloftPluginFavorite = {\n refresh: (songId, isFavorited) => requireFavorite().refresh(songId, isFavorited),\n};\n\n/**\n * 读取宿主 WebView Cookie Store 中指定 origin 的 Cookie。\n * 仅原生客户端可用,Web 端调用会 reject。\n *\n * @param origin 目标站点 origin,例如 \"https://example.com\"\n * @returns name → value 映射\n */\nexport function getCookies(origin: string): Promise<Record<string, string>> {\n const g = getGlobal();\n if (!g || typeof g.getCookies !== 'function') {\n return Promise.reject(new Error('getCookies is not available on this platform (requires native client)'));\n }\n return g.getCookies(origin);\n}\n\n/**\n * 通用宿主调用。上面的 `player` / `host` / `favorite` / `getCookies` 都是它的\n * typed wrapper —— **有 wrapper 时优先用 wrapper**,这里没有那层类型约束,\n * `ns` / `method` 拼错只会在运行时 reject。\n *\n * 留这个出口是因为宿主分发表在客户端侧,可能比服务端那份 `common.js` 更新,\n * 插件需要能触达尚未被 wrapper 覆盖的 namespace。\n *\n * @param ns 命名空间,如 \"favorite\"\n * @param method 方法名,如 \"refresh\"\n * @param params 参数对象,可省略\n */\nexport function invokeHost(\n ns: string,\n method: string,\n params?: Record<string, unknown>,\n): Promise<unknown> {\n const g = getGlobal();\n if (!g || typeof g.invokeHost !== 'function') {\n return Promise.reject(new Error(NOT_AVAILABLE_MSG));\n }\n return g.invokeHost(ns, method, params);\n}\n"],"mappings":";AA8MA,IAAM,oBACJ;AAEF,SAAS,YAA8C;AACrD,SAAO,OAAO,WAAW,cAAc,OAAO,iBAAiB;AACjE;AAMO,SAAS,WAAoB;AAClC,QAAM,IAAI,UAAU;AACpB,SAAO,CAAC,EAAE,KAAK,EAAE,QAAQ,OAAO,EAAE,KAAK,gBAAgB,cAAc,EAAE,KAAK,YAAY;AAC1F;AAEA,SAAS,gBAAsC;AAC7C,QAAM,IAAI,UAAU;AACpB,MAAI,CAAC,KAAK,CAAC,EAAE,OAAQ,OAAM,IAAI,MAAM,iBAAiB;AACtD,SAAO,EAAE;AACX;AAEA,SAAS,cAAkC;AACzC,QAAM,IAAI,UAAU;AACpB,MAAI,CAAC,KAAK,CAAC,EAAE,KAAM,OAAM,IAAI,MAAM,iBAAiB;AACpD,SAAO,EAAE;AACX;AAGO,IAAM,SAA+B;AAAA,EAC1C,UAAU,MAAM,cAAc,EAAE,SAAS;AAAA,EACzC,UAAU,CAAC,KAAK,YAAY,cAAc,EAAE,SAAS,KAAK,OAAO;AAAA,EACjE,YAAY,CAAC,QAAQ,cAAc,EAAE,WAAW,GAAG;AAAA,EACnD,eAAe,CAAC,OAAO,OAAO,cAAc,EAAE,cAAc,OAAO,EAAE;AAAA,EACrE,iBAAiB,CAAC,UAAU,cAAc,EAAE,gBAAgB,KAAK;AAAA,EACjE,cAAc,CAAC,UAAU,aAAa,cAAc,EAAE,aAAa,UAAU,QAAQ;AAAA,EACrF,YAAY,MAAM,cAAc,EAAE,WAAW;AAAA,EAC7C,MAAM,CAAC,OAAO,cAAc,EAAE,KAAK,EAAE;AAAA,EACrC,OAAO,MAAM,cAAc,EAAE,MAAM;AAAA,EACnC,YAAY,MAAM,cAAc,EAAE,WAAW;AAAA,EAC7C,MAAM,MAAM,cAAc,EAAE,KAAK;AAAA,EACjC,MAAM,MAAM,cAAc,EAAE,KAAK;AAAA,EACjC,MAAM,CAAC,YAAY,cAAc,EAAE,KAAK,OAAO;AAAA,EAC/C,WAAW,CAAC,WAAW,cAAc,EAAE,UAAU,MAAM;AAAA,EACvD,aAAa,CAAC,SAAS,cAAc,EAAE,YAAY,IAAI;AAAA,EACvD,kBAAkB,CAAC,eAAe,cAAc,EAAE,iBAAiB,UAAU;AAAA,EAC7E,eAAe,CAAC,YAAY,cAAc,EAAE,cAAc,OAAO;AACnE;AAGO,IAAM,OAA2B;AAAA,EACtC,aAAa,MAAM,SAAS;AAAA,EAC5B,SAAS,MAAM,YAAY,EAAE,QAAQ;AACvC;AAEA,SAAS,kBAA0C;AACjD,QAAM,IAAI,UAAU;AACpB,MAAI,CAAC,KAAK,CAAC,EAAE,SAAU,OAAM,IAAI,MAAM,iBAAiB;AACxD,SAAO,EAAE;AACX;AAGO,IAAM,WAAmC;AAAA,EAC9C,SAAS,CAAC,QAAQ,gBAAgB,gBAAgB,EAAE,QAAQ,QAAQ,WAAW;AACjF;AASO,SAAS,WAAW,QAAiD;AAC1E,QAAM,IAAI,UAAU;AACpB,MAAI,CAAC,KAAK,OAAO,EAAE,eAAe,YAAY;AAC5C,WAAO,QAAQ,OAAO,IAAI,MAAM,uEAAuE,CAAC;AAAA,EAC1G;AACA,SAAO,EAAE,WAAW,MAAM;AAC5B;AAcO,SAAS,WACd,IACA,QACA,QACkB;AAClB,QAAM,IAAI,UAAU;AACpB,MAAI,CAAC,KAAK,OAAO,EAAE,eAAe,YAAY;AAC5C,WAAO,QAAQ,OAAO,IAAI,MAAM,iBAAiB,CAAC;AAAA,EACpD;AACA,SAAO,EAAE,WAAW,IAAI,QAAQ,MAAM;AACxC;","names":[]}
1
+ {"version":3,"sources":["../src/index.ts"],"sourcesContent":["// @songloft/client-sdk — 客户端 SDK\n//\n// 让「在 Songloft Flutter 客户端 webview 中打开的插件页面」调用宿主客户端能力\n// (改写正在播放队列、控制播放、订阅播放状态等)。\n//\n// 架构:运行时能力由宿主注入到 `window.SongloftPlugin`(common.js + Flutter 宿主)。\n// 传输由 common.js 按宿主环境自动选择,插件无需关心:\n// - native 客户端 + 系统 WebView → flutter_inappwebview.callHandler\n// - Web 端插件页(Tab 内嵌页与首页/全屏页均在宿主 iframe 内)→ postMessage\n// 本包是**类型层 + 便捷封装**,所有调用都委托给注入的全局对象,因此:\n// - native 客户端 webview 插件页、Web 端 iframe 内嵌插件页内有效;\n// - 仅当用户通过「在浏览器中打开」将插件页在独立新标签打开(无宿主父窗口)、\n// 或宿主版本过旧时,`isClient()` / `host.isAvailable()` 返回 false,调用会抛出明确错误,请先 feature-detect。\n//\n// 用法:\n// import { player, host, isClient } from '@songloft/client-sdk';\n// if (isClient()) {\n// await player.setQueue([101, 102], { startIndex: 0 });\n// player.onStateChange((s) => console.log(s.current_index));\n// }\n//\n// 免构建的 vanilla 插件可直接用注入的全局对象:\n// window.SongloftPlugin.player.setQueue([101, 102]);\n\n// ===== 数据模型 =====\n\n/** 播放模式(与宿主一致)。 */\nexport type PlayMode = 'order' | 'loop' | 'single' | 'random' | 'singlePlay';\n\n/**\n * 队列中的歌曲对象(宿主返回值,字段为 snake_case,与后端 JSON 一致)。\n * 只列出常用字段;宿主可能返回更多字段。\n */\nexport interface ClientSong {\n id: number;\n type: 'local' | 'remote' | 'radio';\n title: string;\n artist?: string;\n album?: string;\n duration?: number;\n url?: string;\n cover_url?: string;\n lyric_url?: string;\n is_live?: boolean;\n [key: string]: unknown;\n}\n\n/** 播放器状态快照(`player.getState()` / `onStateChange` 回调)。 */\nexport interface ClientPlayerState {\n /** 正在播放队列 */\n queue: ClientSong[];\n /** 当前歌曲在队列中的下标;无歌曲时为 -1 */\n current_index: number;\n /** 当前歌曲;无歌曲时为 null */\n current_song: ClientSong | null;\n is_playing: boolean;\n /** 当前播放进度(秒) */\n current_time: number;\n /** 当前歌曲总时长(秒) */\n duration: number;\n /** 音量 0-100 */\n volume: number;\n play_mode: PlayMode;\n /** 队列来源的服务端歌单 id(如有) */\n source_playlist_id?: number | null;\n}\n\n/** 宿主信息与能力协商结果(`host.getInfo()`)。 */\nexport interface HostInfo {\n /** 客户端应用版本,如 \"2.12.0\" */\n version: string;\n /** 运行平台:android / ios / macos / windows / linux / web */\n platform: string;\n /** 宿主支持的能力命名空间,如 [\"player\"],用于向前兼容的能力协商 */\n capabilities: string[];\n}\n\n/** `setQueue` 的可选参数。 */\nexport interface SetQueueOptions {\n /** 从队列的哪一首开始播放,默认 0 */\n startIndex?: number;\n /** 标记队列来源的服务端歌单 id(可选,仅用于 UI 展示归属) */\n sourcePlaylistId?: number;\n}\n\n/** Temporary host audio effects for a plugin's playback session. */\nexport interface PlaybackAudioEffects {\n equalizer?: { preset: string };\n reverb?: { preset: string };\n}\n\nexport interface PlaybackAudioEffectsState {\n playbackId: string | null;\n supported: {\n equalizer?: { presets: string[] };\n reverb?: { presets: string[] };\n };\n applied: PlaybackAudioEffects | null;\n}\n\nexport interface ApplyPlaybackAudioEffectsOptions {\n playbackId: string;\n effects: PlaybackAudioEffects;\n}\n\n// ===== 注入的全局对象类型(window.SongloftPlugin) =====\n\n/** 宿主客户端能力:播放器命名空间。 */\nexport interface SongloftPluginPlayer {\n /** 获取当前播放器状态快照 */\n getState(): Promise<ClientPlayerState>;\n /** Query the output's supported effects and this plugin's current playback session. */\n getAudioEffects(): Promise<PlaybackAudioEffectsState>;\n /** Replace the temporary effects for this plugin's playback session. */\n applyAudioEffects(options: ApplyPlaybackAudioEffectsOptions): Promise<PlaybackAudioEffects | null>;\n /** Restore the user's effects for this plugin's playback session. */\n clearAudioEffects(options: { playbackId: string }): Promise<void>;\n /** 用歌曲 id 列表替换整个正在播放队列并开始播放 */\n setQueue(ids: number[], options?: SetQueueOptions): Promise<void>;\n /** 追加歌曲到队列末尾(去重,不改变当前播放) */\n addToQueue(ids: number[]): Promise<void>;\n /** 在队列指定位置插入一首歌(不触发播放) */\n insertToQueue(index: number, id: number): Promise<void>;\n /** 移除队列中指定下标的歌曲 */\n removeFromQueue(index: number): Promise<void>;\n /** 重排队列 */\n reorderQueue(oldIndex: number, newIndex: number): Promise<void>;\n /** 清空队列 */\n clearQueue(): Promise<void>;\n /** 播放:传 id 则播放该歌曲(不在队列则追加),不传则恢复播放 */\n play(id?: number): Promise<void>;\n /** 暂停 */\n pause(): Promise<void>;\n /** 播放/暂停切换 */\n togglePlay(): Promise<void>;\n /** 下一首 */\n next(): Promise<void>;\n /** 上一首 */\n prev(): Promise<void>;\n /** 跳转到指定进度(秒) */\n seek(seconds: number): Promise<void>;\n /** 设置音量 0-100 */\n setVolume(volume: number): Promise<void>;\n /** 设置播放模式 */\n setPlayMode(mode: PlayMode): Promise<void>;\n /** 直接播放服务端歌单(按歌单 id) */\n playPlaylistById(playlistId: number): Promise<void>;\n /**\n * 订阅播放状态变更。返回取消订阅函数。\n * 注意:状态推送经过节流,`current_time` 可能不是每秒更新。\n */\n onStateChange(handler: (state: ClientPlayerState) => void): () => void;\n}\n\n/** 宿主客户端能力:host 命名空间。 */\nexport interface SongloftPluginHost {\n /** 同步 feature-detect:当前是否运行在支持原生桥接的 Songloft 客户端 webview 内 */\n isAvailable(): boolean;\n /** 获取宿主信息与能力列表 */\n getInfo(): Promise<HostInfo>;\n}\n\n/** 宿主客户端能力:favorite 命名空间。 */\nexport interface SongloftPluginFavorite {\n /**\n * 通知宿主刷新收藏状态缓存。\n *\n * 插件自己改完收藏(如直接 POST `/playlists/1/songs`)后必须调一次:服务端\n * 数据是对的,但 Flutter 侧曲库的红心读的是 `FavoriteNotifier` 的内存缓存,\n * 不会自动跟着变。\n *\n * **能带参就带参**——带参是增量更新,宿主只改这一首的归属;不带参是全量重载,\n * 曲库上千首时是一次完整的往返。\n *\n * @param songId 歌曲 ID;省略则全量重载\n * @param isFavorited 操作后的收藏态;省略则全量重载\n */\n refresh(songId?: number, isFavorited?: boolean): Promise<void>;\n}\n\n/**\n * 注入到页面的 `window.SongloftPlugin` 全局对象。\n * 由主程序 common.js 注入到所有插件 HTML 页面。此处仅声明本 SDK 依赖的成员,\n * 现有的 apiGet/apiPost/getTheme 等成员见插件开发指南。\n *\n * ⚠️ **这份声明必须与 `common.js` 末尾那个对象字面量保持一致**,它才是公开成员的\n * 唯一真实来源。别在插件里另手写一份宿主 API 声明:曾经有插件自己声明了\n * `invokeHost?`(当时它只存在于内部句柄 `window.__SongloftInternal`),于是\n * `SongloftPlugin?.invokeHost?.(...)` 通过 TS 编译、运行时被可选调用静默吞掉,\n * 整个功能一个字节都没发出去(songloft-org/songloft-plugin-miot#86)。\n */\nexport interface SongloftPluginGlobal {\n host?: SongloftPluginHost;\n player?: SongloftPluginPlayer;\n favorite?: SongloftPluginFavorite;\n /**\n * 通用宿主调用出口。`host` / `player` / `favorite` / `getCookies` 都是它的\n * typed wrapper;公开它是为了让插件能触达尚未被 wrapper 覆盖的 namespace\n * (宿主分发表在客户端侧,可能比服务端那份 common.js 更新)。\n *\n * ⚠️ 没有 wrapper 那层类型约束,`ns` / `method` 拼错只会在运行时 reject。\n * 有对应 wrapper 时优先用 wrapper。\n */\n invokeHost?(ns: string, method: string, params?: Record<string, unknown>): Promise<unknown>;\n /**\n * 读取宿主 WebView Cookie Store 中指定 origin 的 Cookie。\n * 原生层读取,不受浏览器同源策略 / HttpOnly 限制。\n *\n * 仅原生客户端(Android/iOS/macOS/Windows/Linux)可用,Web 端调用会 reject。\n *\n * @param origin 目标站点 origin,例如 \"https://example.com\"(含协议 + 主机 + 端口)\n * @returns name → value 映射;该 origin 无 Cookie 时返回空对象 {}\n */\n getCookies?(origin: string): Promise<Record<string, string>>;\n // 现有成员(主题 / API 工具)——保留为可选,避免与旧宿主冲突。\n getTheme?(): 'light' | 'dark';\n onThemeChange?(cb: (theme: 'light' | 'dark') => void): void;\n apiGet?(path: string): Promise<unknown>;\n apiPost?(path: string, body: unknown): Promise<unknown>;\n apiPut?(path: string, body: unknown): Promise<unknown>;\n apiDelete?(path: string): Promise<unknown>;\n [key: string]: unknown;\n}\n\ndeclare global {\n interface Window {\n SongloftPlugin?: SongloftPluginGlobal;\n }\n}\n\n// ===== 便捷封装(委托注入的全局对象) =====\n\nconst NOT_AVAILABLE_MSG =\n '[@songloft/client-sdk] 宿主客户端桥接不可用:请确保插件页在 Songloft 客户端(非 Web)的 webview 中打开,且客户端版本支持客户端 SDK。可用 isClient() 预先检测。';\n\nfunction getGlobal(): SongloftPluginGlobal | undefined {\n return typeof window !== 'undefined' ? window.SongloftPlugin : undefined;\n}\n\n/**\n * 是否运行在支持原生桥接的 Songloft 客户端 webview 内。\n * 调用任何 player/host 方法前建议先检测。\n */\nexport function isClient(): boolean {\n const g = getGlobal();\n return !!(g && g.host && typeof g.host.isAvailable === 'function' && g.host.isAvailable());\n}\n\nfunction requirePlayer(): SongloftPluginPlayer {\n const g = getGlobal();\n if (!g || !g.player) throw new Error(NOT_AVAILABLE_MSG);\n return g.player;\n}\n\nfunction requireHost(): SongloftPluginHost {\n const g = getGlobal();\n if (!g || !g.host) throw new Error(NOT_AVAILABLE_MSG);\n return g.host;\n}\n\n/** 播放器控制。所有方法委托注入的 `window.SongloftPlugin.player`。 */\nexport const player: SongloftPluginPlayer = {\n getState: () => requirePlayer().getState(),\n getAudioEffects: () =>\n invokeHost('player', 'getAudioEffects') as Promise<PlaybackAudioEffectsState>,\n applyAudioEffects: ({ playbackId, effects }) =>\n invokeHost('player', 'applyAudioEffects', { playbackId, effects }) as Promise<PlaybackAudioEffects | null>,\n clearAudioEffects: async ({ playbackId }) => {\n await invokeHost('player', 'clearAudioEffects', { playbackId });\n },\n setQueue: (ids, options) => requirePlayer().setQueue(ids, options),\n addToQueue: (ids) => requirePlayer().addToQueue(ids),\n insertToQueue: (index, id) => requirePlayer().insertToQueue(index, id),\n removeFromQueue: (index) => requirePlayer().removeFromQueue(index),\n reorderQueue: (oldIndex, newIndex) => requirePlayer().reorderQueue(oldIndex, newIndex),\n clearQueue: () => requirePlayer().clearQueue(),\n play: (id) => requirePlayer().play(id),\n pause: () => requirePlayer().pause(),\n togglePlay: () => requirePlayer().togglePlay(),\n next: () => requirePlayer().next(),\n prev: () => requirePlayer().prev(),\n seek: (seconds) => requirePlayer().seek(seconds),\n setVolume: (volume) => requirePlayer().setVolume(volume),\n setPlayMode: (mode) => requirePlayer().setPlayMode(mode),\n playPlaylistById: (playlistId) => requirePlayer().playPlaylistById(playlistId),\n onStateChange: (handler) => requirePlayer().onStateChange(handler),\n};\n\n/** 宿主信息与能力协商。委托注入的 `window.SongloftPlugin.host`。 */\nexport const host: SongloftPluginHost = {\n isAvailable: () => isClient(),\n getInfo: () => requireHost().getInfo(),\n};\n\nfunction requireFavorite(): SongloftPluginFavorite {\n const g = getGlobal();\n if (!g || !g.favorite) throw new Error(NOT_AVAILABLE_MSG);\n return g.favorite;\n}\n\n/** 收藏状态同步。委托注入的 `window.SongloftPlugin.favorite`。 */\nexport const favorite: SongloftPluginFavorite = {\n refresh: (songId, isFavorited) => requireFavorite().refresh(songId, isFavorited),\n};\n\n/**\n * 读取宿主 WebView Cookie Store 中指定 origin 的 Cookie。\n * 仅原生客户端可用,Web 端调用会 reject。\n *\n * @param origin 目标站点 origin,例如 \"https://example.com\"\n * @returns name → value 映射\n */\nexport function getCookies(origin: string): Promise<Record<string, string>> {\n const g = getGlobal();\n if (!g || typeof g.getCookies !== 'function') {\n return Promise.reject(new Error('getCookies is not available on this platform (requires native client)'));\n }\n return g.getCookies(origin);\n}\n\n/**\n * 通用宿主调用。上面的 `player` / `host` / `favorite` / `getCookies` 都是它的\n * typed wrapper —— **有 wrapper 时优先用 wrapper**,这里没有那层类型约束,\n * `ns` / `method` 拼错只会在运行时 reject。\n *\n * 留这个出口是因为宿主分发表在客户端侧,可能比服务端那份 `common.js` 更新,\n * 插件需要能触达尚未被 wrapper 覆盖的 namespace。\n *\n * @param ns 命名空间,如 \"favorite\"\n * @param method 方法名,如 \"refresh\"\n * @param params 参数对象,可省略\n */\nexport function invokeHost(\n ns: string,\n method: string,\n params?: Record<string, unknown>,\n): Promise<unknown> {\n const g = getGlobal();\n if (!g || typeof g.invokeHost !== 'function') {\n return Promise.reject(new Error(NOT_AVAILABLE_MSG));\n }\n return g.invokeHost(ns, method, params);\n}\n"],"mappings":"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","names":[]}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@songloft/client-sdk",
3
- "version": "2.21.0",
3
+ "version": "2.23.0",
4
4
  "description": "Client SDK for Songloft webview plugin pages — call Flutter host APIs (player queue, etc.)",
5
5
  "type": "module",
6
6
  "exports": {