@shiqianjiang/ceru-plugin-sdk 0.3.6 → 0.3.8
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/CHANGELOG.md +7 -0
- package/README.md +2 -0
- package/dist/index.d.ts +6 -1
- package/dist/lyrics.d.ts +2 -2
- package/dist/music.d.ts +15 -0
- package/dist/music.js +51 -19
- package/dist/services.d.ts +1 -0
- package/dist/services.js +13 -0
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,12 @@
|
|
|
1
1
|
# SDK 变更记录
|
|
2
2
|
|
|
3
|
+
## 0.3.7
|
|
4
|
+
|
|
5
|
+
- 公共 `scope: 'provider'` 歌曲不再要求 `pluginId`;Host 在调用用户选定的实现时才补入目标插件 ID。私有资源仍必须声明所有者。
|
|
6
|
+
- `CrLyric` 新增 TTML 同构的 `translations` / `romanizations` 子行及逐字时间轴,保留单数纯文本字段以兼容旧 Host。
|
|
7
|
+
- `LyricWord` 新增可选 `translation`,歌词断言现在严格校验主歌词和附属歌词的所有词级字段与时间顺序。
|
|
8
|
+
- `LyricExportFormat` 新增 `ttml`,逐字翻译/音译可无损导出后再次解析。
|
|
9
|
+
|
|
3
10
|
## 0.3.6
|
|
4
11
|
|
|
5
12
|
- `ResourceRef.scope: 'provider'` 标记公共平台歌曲 ID;支持 Host 按用户的播放/歌词路由选择实现。私有资源默认仍归原插件,`retargetTrackRef` 跨插件时只保留公共标识,剥离私有数据。
|
package/README.md
CHANGED
|
@@ -56,6 +56,8 @@ const icon = hostIcon('platform.tx')
|
|
|
56
56
|
|
|
57
57
|
动作需要在 Manifest 中声明。平台图标复用 Host 资源,不内嵌图片。
|
|
58
58
|
|
|
59
|
+
日志支持单条消息或消息加结构化详情:`ctx.log.info('请求完成')`、`ctx.log.info('请求完成', { status: 200 })`。详情对象由 Host 统一脱敏并序列化为同一条日志,插件不需要手动 `JSON.stringify`;过长字段会保留首尾并标记截断。`undefined` 不会被追加为额外日志参数。
|
|
60
|
+
|
|
59
61
|
CLI 并非必需。插件也可以直接写成 `exports.manifest`、`exports.activate`、`exports.surfaces` 的单个 JavaScript 文件,通过 `require('@ceru/http')` 等内置模块使用相同能力。第三方 npm 包必须在发行前打入文件。
|
|
60
62
|
|
|
61
63
|
运行配置通过 `await ctx.config.get<PluginConfig>()` 读取。配置默认值来自静态 `exports.manifest.config`,个性化发行值来自签名后的 `personalization.config`;Host 递归合并后再交给插件。`definePluginConfig()` 可为外部 TS/JS 配置保留完整字段提示。
|
package/dist/index.d.ts
CHANGED
|
@@ -31,7 +31,12 @@ export type HostLodash = Pick<LoDashStatic, (typeof LODASH_METHODS)[number]>;
|
|
|
31
31
|
export * from './manifest.js';
|
|
32
32
|
import type { JsonValue, JsonObject, MaybePromise, Disposable, PluginManifest } from './manifest.js';
|
|
33
33
|
export interface ResourceRef {
|
|
34
|
-
|
|
34
|
+
/**
|
|
35
|
+
* Owning plugin for private resources. Public provider-scoped tracks may omit
|
|
36
|
+
* this field so a playlist/search result does not pin playback to its source
|
|
37
|
+
* plugin; the Host fills it in only when invoking a selected implementation.
|
|
38
|
+
*/
|
|
39
|
+
pluginId?: string;
|
|
35
40
|
providerId: string;
|
|
36
41
|
connectionId?: string;
|
|
37
42
|
kind: string;
|
package/dist/lyrics.d.ts
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
import type { CrLyric } from './music.js';
|
|
2
2
|
import type { ResourceRef, OperationContext } from './index.js';
|
|
3
3
|
export type LyricInputFormat = 'auto' | 'lrc' | 'enhanced-lrc' | 'yrc' | 'qrc' | 'krc' | 'ttml' | 'plain';
|
|
4
|
-
export type LyricExportFormat = 'lrc' | 'enhanced-lrc' | 'yrc';
|
|
4
|
+
export type LyricExportFormat = 'lrc' | 'enhanced-lrc' | 'yrc' | 'ttml';
|
|
5
5
|
export interface LyricParseRequest {
|
|
6
6
|
track: ResourceRef;
|
|
7
7
|
format: LyricInputFormat;
|
|
@@ -17,7 +17,7 @@ export interface LyricExportResult {
|
|
|
17
17
|
format: LyricExportFormat;
|
|
18
18
|
text: string;
|
|
19
19
|
mime: 'text/plain';
|
|
20
|
-
extension: 'lrc' | 'yrc';
|
|
20
|
+
extension: 'lrc' | 'yrc' | 'ttml';
|
|
21
21
|
}
|
|
22
22
|
/** Parsing/decryption/serialization belongs to plugins, not the player or download manager. */
|
|
23
23
|
export interface LyricConverter {
|
package/dist/music.d.ts
CHANGED
|
@@ -1,11 +1,19 @@
|
|
|
1
1
|
import type { ContentEntity, ResourceRef, ResolveResult } from './index.js';
|
|
2
2
|
/** Milliseconds throughout. Platform-specific formats/decryption stay inside the plugin. */
|
|
3
3
|
export interface LyricWord {
|
|
4
|
+
/** Optional translation aligned with this timed source word. */
|
|
5
|
+
translation?: string;
|
|
4
6
|
romanization?: string;
|
|
5
7
|
startTimeMs: number;
|
|
6
8
|
endTimeMs: number;
|
|
7
9
|
text: string;
|
|
8
10
|
}
|
|
11
|
+
/** A translation or romanization, optionally preserving its own timed words. */
|
|
12
|
+
export interface LyricSubLine {
|
|
13
|
+
language?: string;
|
|
14
|
+
text: string;
|
|
15
|
+
words?: LyricWord[];
|
|
16
|
+
}
|
|
9
17
|
export interface LyricLine {
|
|
10
18
|
isBackground?: boolean;
|
|
11
19
|
isDuet?: boolean;
|
|
@@ -14,6 +22,9 @@ export interface LyricLine {
|
|
|
14
22
|
text: string;
|
|
15
23
|
translation?: string;
|
|
16
24
|
romanization?: string;
|
|
25
|
+
/** Structured TTML-style alternatives. Singular fields remain backward compatible. */
|
|
26
|
+
translations?: LyricSubLine[];
|
|
27
|
+
romanizations?: LyricSubLine[];
|
|
17
28
|
words?: LyricWord[];
|
|
18
29
|
}
|
|
19
30
|
export interface CrLyric {
|
|
@@ -28,6 +39,10 @@ export interface CrLyric {
|
|
|
28
39
|
/** @deprecated Use CrLyric. */
|
|
29
40
|
export type LyricsDocument = CrLyric;
|
|
30
41
|
export interface TrackMetadata {
|
|
42
|
+
/** Optional platform hash; not a plugin owner or routing key. */
|
|
43
|
+
hash?: string;
|
|
44
|
+
/** Original display sizes when exact bytes are unavailable. Never infer bytes from these labels. */
|
|
45
|
+
qualitySizeLabels?: Record<string, string>;
|
|
31
46
|
artists: string[];
|
|
32
47
|
album?: {
|
|
33
48
|
id?: string;
|
package/dist/music.js
CHANGED
|
@@ -1,15 +1,47 @@
|
|
|
1
1
|
const record = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
|
|
2
2
|
const text = (value, max = 4096) => typeof value === 'string' && value.length <= max;
|
|
3
3
|
const milliseconds = (value) => Number.isFinite(value) && Number(value) >= 0;
|
|
4
|
+
function assertLyricWords(value, minimumStartTimeMs) {
|
|
5
|
+
if (!Array.isArray(value) || value.length > 10000)
|
|
6
|
+
throw new Error('Invalid lyric words');
|
|
7
|
+
let lastWord = minimumStartTimeMs;
|
|
8
|
+
for (const word of value) {
|
|
9
|
+
if (!record(word) ||
|
|
10
|
+
!milliseconds(word.startTimeMs) ||
|
|
11
|
+
!milliseconds(word.endTimeMs) ||
|
|
12
|
+
word.endTimeMs < word.startTimeMs ||
|
|
13
|
+
word.startTimeMs < lastWord ||
|
|
14
|
+
!text(word.text, 65536) ||
|
|
15
|
+
(word.translation !== undefined && !text(word.translation, 65536)) ||
|
|
16
|
+
(word.romanization !== undefined && !text(word.romanization, 65536)))
|
|
17
|
+
throw new Error('Invalid lyric word');
|
|
18
|
+
lastWord = word.startTimeMs;
|
|
19
|
+
}
|
|
20
|
+
}
|
|
21
|
+
function assertLyricSubLines(value) {
|
|
22
|
+
if (!Array.isArray(value) || value.length > 16)
|
|
23
|
+
throw new Error('Invalid lyric alternatives');
|
|
24
|
+
for (const item of value) {
|
|
25
|
+
if (!record(item) ||
|
|
26
|
+
!text(item.text, 65536) ||
|
|
27
|
+
(item.language !== undefined && !text(item.language, 128)))
|
|
28
|
+
throw new Error('Invalid lyric alternative');
|
|
29
|
+
if (item.words !== undefined)
|
|
30
|
+
assertLyricWords(item.words, 0);
|
|
31
|
+
}
|
|
32
|
+
}
|
|
4
33
|
export function assertResourceRef(value) {
|
|
5
34
|
if (!record(value) ||
|
|
6
|
-
!['
|
|
35
|
+
!['providerId', 'kind', 'id'].every((key) => text(value[key], 2048) && value[key].length > 0) ||
|
|
36
|
+
(value.pluginId !== undefined && (!text(value.pluginId, 2048) || !value.pluginId)))
|
|
7
37
|
throw new Error('Invalid resource reference');
|
|
8
38
|
if (value.connectionId !== undefined && (!text(value.connectionId, 2048) || !value.connectionId))
|
|
9
39
|
throw new Error('Invalid resource connection');
|
|
10
40
|
if (value.scope !== undefined &&
|
|
11
41
|
(value.scope !== 'provider' || value.kind !== 'track' || value.connectionId !== undefined))
|
|
12
42
|
throw new Error('Provider scope requires a public track without a connection');
|
|
43
|
+
if (value.pluginId === undefined && value.scope !== 'provider')
|
|
44
|
+
throw new Error('Private resources require an owning plugin');
|
|
13
45
|
if (value.data !== undefined) {
|
|
14
46
|
if (!record(value.data))
|
|
15
47
|
throw new Error('Invalid resource private data');
|
|
@@ -56,13 +88,22 @@ export function assertContentPage(value) {
|
|
|
56
88
|
throw new Error('Track metadata must contain artists');
|
|
57
89
|
if (item.metadata.durationMs !== undefined && !milliseconds(item.metadata.durationMs))
|
|
58
90
|
throw new Error('Invalid track duration');
|
|
59
|
-
const { qualities, qualitySizes } = item.metadata;
|
|
91
|
+
const { qualities, qualitySizes, qualitySizeLabels, hash } = item.metadata;
|
|
92
|
+
if (hash !== undefined && !text(hash, 4096))
|
|
93
|
+
throw new Error('Invalid track hash');
|
|
94
|
+
if (qualitySizeLabels !== undefined &&
|
|
95
|
+
(!record(qualitySizeLabels) ||
|
|
96
|
+
Object.keys(qualitySizeLabels).length > 128 ||
|
|
97
|
+
Object.entries(qualitySizeLabels).some(([quality, label]) => !qualities?.includes(quality) || !text(label, 128))))
|
|
98
|
+
throw new Error('Invalid track quality size labels');
|
|
60
99
|
if (qualities !== undefined &&
|
|
61
|
-
(!Array.isArray(qualities) ||
|
|
100
|
+
(!Array.isArray(qualities) ||
|
|
101
|
+
qualities.length > 128 ||
|
|
62
102
|
!qualities.every((quality) => text(quality, 128) && !!quality)))
|
|
63
103
|
throw new Error('Invalid track qualities');
|
|
64
104
|
if (qualitySizes !== undefined &&
|
|
65
|
-
(!record(qualitySizes) ||
|
|
105
|
+
(!record(qualitySizes) ||
|
|
106
|
+
Object.keys(qualitySizes).length > 128 ||
|
|
66
107
|
Object.entries(qualitySizes).some(([quality, bytes]) => !qualities?.includes(quality) || !Number.isSafeInteger(bytes) || Number(bytes) <= 0)))
|
|
67
108
|
throw new Error('Invalid track quality sizes');
|
|
68
109
|
}
|
|
@@ -130,21 +171,12 @@ export function assertLyricsDocument(value) {
|
|
|
130
171
|
for (const field of ['translation', 'romanization'])
|
|
131
172
|
if (line[field] !== undefined && !text(line[field], 65536))
|
|
132
173
|
throw new Error('Invalid lyric translation');
|
|
133
|
-
if (line.
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
!milliseconds(word.startTimeMs) ||
|
|
140
|
-
!milliseconds(word.endTimeMs) ||
|
|
141
|
-
word.endTimeMs < word.startTimeMs ||
|
|
142
|
-
word.startTimeMs < lastWord ||
|
|
143
|
-
!text(word.text, 65536))
|
|
144
|
-
throw new Error('Invalid lyric word');
|
|
145
|
-
lastWord = word.startTimeMs;
|
|
146
|
-
}
|
|
147
|
-
}
|
|
174
|
+
if (line.translations !== undefined)
|
|
175
|
+
assertLyricSubLines(line.translations);
|
|
176
|
+
if (line.romanizations !== undefined)
|
|
177
|
+
assertLyricSubLines(line.romanizations);
|
|
178
|
+
if (line.words !== undefined)
|
|
179
|
+
assertLyricWords(line.words, line.startTimeMs);
|
|
148
180
|
}
|
|
149
181
|
if (value.plainText !== undefined && !text(value.plainText, 1048576))
|
|
150
182
|
throw new Error('Invalid plain lyrics');
|
package/dist/services.d.ts
CHANGED
|
@@ -119,6 +119,7 @@ export interface HostServiceEvents {
|
|
|
119
119
|
keys: string[];
|
|
120
120
|
};
|
|
121
121
|
}
|
|
122
|
+
export declare const HOST_SERVICE_EVENT_NAMES: readonly ["account.changed", "library.changed", "player.changed", "queue.changed", "lyrics.changed", "downloads.changed", "settings.changed", "theme.changed", "rooms.changed", "devices.changed", "permissions.changed"];
|
|
122
123
|
/** Contract first: availability must be checked before using services not connected by this Host. */
|
|
123
124
|
export interface HostServices {
|
|
124
125
|
capabilities: {
|
package/dist/services.js
CHANGED
|
@@ -1,3 +1,16 @@
|
|
|
1
|
+
export const HOST_SERVICE_EVENT_NAMES = [
|
|
2
|
+
'account.changed',
|
|
3
|
+
'library.changed',
|
|
4
|
+
'player.changed',
|
|
5
|
+
'queue.changed',
|
|
6
|
+
'lyrics.changed',
|
|
7
|
+
'downloads.changed',
|
|
8
|
+
'settings.changed',
|
|
9
|
+
'theme.changed',
|
|
10
|
+
'rooms.changed',
|
|
11
|
+
'devices.changed',
|
|
12
|
+
'permissions.changed',
|
|
13
|
+
];
|
|
1
14
|
/** Explicit allowlist for future Core routing; never forward arbitrary IPC channel names. */
|
|
2
15
|
export const HOST_SERVICE_METHODS = {
|
|
3
16
|
capabilities: ['list', 'get'],
|