@shiqianjiang/ceru-plugin-sdk 0.2.2 → 0.2.4

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/dist/index.d.ts CHANGED
@@ -9,6 +9,8 @@ export * from './sockets.js';
9
9
  import type { SocketAPI } from './sockets.js';
10
10
  import type { createHttpClient, HttpClientOptions } from './http.js';
11
11
  export * from './music.js';
12
+ export * from './lyrics.js';
13
+ export * from './quality.js';
12
14
  export * from './permissions.js';
13
15
  export * from './services.js';
14
16
  export * from './modules.js';
@@ -79,6 +81,7 @@ export interface SearchRequest {
79
81
  kinds: string[];
80
82
  filters: JsonObject;
81
83
  cursor?: string;
84
+ /** Requested size; providers may clamp to their upstream API's supported range. */
82
85
  limit: number;
83
86
  }
84
87
  export interface MusicFault {
@@ -116,7 +119,7 @@ export interface PlaylistProvider {
116
119
  search?(request: SearchRequest, operation: OperationContext): Promise<Page<ContentEntity>>;
117
120
  categories?(operation: OperationContext): Promise<Page<ContentEntity>>;
118
121
  list?(resource: ResourceRef, cursor: string | undefined, operation: OperationContext): Promise<Page<ContentEntity>>;
119
- get?(resource: ResourceRef, cursor: string | undefined, operation: OperationContext): Promise<Page<ContentEntity>>;
122
+ get?(resource: ResourceRef, cursor: string | undefined, operation: OperationContext): Promise<import('./library.js').PlaylistTrackPage>;
120
123
  }
121
124
  export interface ChartProvider {
122
125
  list?(operation: OperationContext): Promise<Page<ContentEntity>>;
@@ -148,6 +151,8 @@ export interface PluginContext extends HostServices {
148
151
  readonly plugin: {
149
152
  id: string;
150
153
  version: string;
154
+ /** The validated installed manifest. Runtime configuration is manifest.config. */
155
+ manifest: Readonly<PluginManifest>;
151
156
  };
152
157
  /** 当前 Host 的协议版本与共享资源版本。 */
153
158
  readonly host: {
@@ -187,6 +192,9 @@ export interface PluginContext extends HostServices {
187
192
  playlistImporters: {
188
193
  register(id: string, implementation: PlaylistImporterImplementation): Disposable;
189
194
  };
195
+ lyricConverters: {
196
+ register(id: string, implementation: import('./lyrics.js').LyricConverter): Disposable;
197
+ };
190
198
  providers: {
191
199
  register(id: string, implementation: ProviderImplementation): Disposable;
192
200
  };
package/dist/index.js CHANGED
@@ -3,6 +3,8 @@ export * from './http.js';
3
3
  export * from './library.js';
4
4
  export * from './sockets.js';
5
5
  export * from './music.js';
6
+ export * from './lyrics.js';
7
+ export * from './quality.js';
6
8
  export * from './permissions.js';
7
9
  export * from './services.js';
8
10
  export * from './modules.js';
package/dist/library.d.ts CHANGED
@@ -34,9 +34,11 @@ export interface PlaylistImporterImplementation {
34
34
  value: string;
35
35
  cursor?: string;
36
36
  limit: number;
37
- }, operation: OperationContext): Promise<Page<ContentEntity> & {
38
- name?: string;
39
- }>;
37
+ }, operation: OperationContext): Promise<PlaylistTrackPage>;
38
+ }
39
+ export interface PlaylistTrackPage extends Page<ContentEntity> {
40
+ name?: string;
41
+ playlist?: import('./music.js').PlaylistMetadata;
40
42
  }
41
43
  /** Existing application library services. No plugin-owned playlist database. */
42
44
  export interface LibraryAPI {
@@ -0,0 +1,26 @@
1
+ import type { CrLyric } from './music.js';
2
+ import type { ResourceRef, OperationContext } from './index.js';
3
+ export type LyricInputFormat = 'auto' | 'lrc' | 'enhanced-lrc' | 'yrc' | 'qrc' | 'krc' | 'ttml' | 'plain';
4
+ export type LyricExportFormat = 'lrc' | 'enhanced-lrc' | 'yrc';
5
+ export interface LyricParseRequest {
6
+ track: ResourceRef;
7
+ format: LyricInputFormat;
8
+ text: string;
9
+ translation?: string;
10
+ romanization?: string;
11
+ }
12
+ export interface LyricExportRequest {
13
+ document: CrLyric;
14
+ format: LyricExportFormat;
15
+ }
16
+ export interface LyricExportResult {
17
+ format: LyricExportFormat;
18
+ text: string;
19
+ mime: 'text/plain';
20
+ extension: 'lrc' | 'yrc';
21
+ }
22
+ /** Parsing/decryption/serialization belongs to plugins, not the player or download manager. */
23
+ export interface LyricConverter {
24
+ parse(request: LyricParseRequest, operation: OperationContext): Promise<CrLyric>;
25
+ export(request: LyricExportRequest, operation: OperationContext): Promise<LyricExportResult>;
26
+ }
package/dist/lyrics.js ADDED
@@ -0,0 +1 @@
1
+ export {};
@@ -27,6 +27,8 @@ export interface ProviderDeclaration {
27
27
  id: string;
28
28
  name: string;
29
29
  protocols: string[];
30
+ /** Ordered from lowest to highest; names have no intrinsic rank. */
31
+ qualities?: string[];
30
32
  icon?: IconRef;
31
33
  connectionMode?: 'none' | 'single' | 'multiple';
32
34
  }
@@ -75,6 +77,7 @@ export interface PluginManifest {
75
77
  author?: string;
76
78
  publisher?: string;
77
79
  license?: string;
80
+ homepage?: string;
78
81
  /** Static defaults for ctx.config. Build-time @file sugar is expanded into this object. */
79
82
  config?: JsonObject;
80
83
  engines: {
@@ -91,6 +94,11 @@ export interface PluginManifest {
91
94
  surfaces?: SurfaceDeclaration[];
92
95
  };
93
96
  contributes?: {
97
+ lyricConverters?: {
98
+ id: string;
99
+ title: string;
100
+ formats: import('./lyrics.js').LyricInputFormat[];
101
+ }[];
94
102
  providers?: ProviderDeclaration[];
95
103
  /** Home tabs exist only while at least one enabled plugin contributes them. */
96
104
  homeSections?: HomeSectionContribution[];
@@ -103,6 +111,12 @@ export interface PluginManifest {
103
111
  playlistImporters?: {
104
112
  id: string;
105
113
  title: string;
114
+ providerId?: string;
115
+ examples?: {
116
+ label: string;
117
+ value: string;
118
+ }[];
119
+ instructions?: string[];
106
120
  description?: string;
107
121
  placeholder?: string;
108
122
  }[];
package/dist/music.d.ts CHANGED
@@ -1,11 +1,14 @@
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
+ romanization?: string;
4
5
  startTimeMs: number;
5
6
  endTimeMs: number;
6
7
  text: string;
7
8
  }
8
9
  export interface LyricLine {
10
+ isBackground?: boolean;
11
+ isDuet?: boolean;
9
12
  startTimeMs: number;
10
13
  endTimeMs?: number;
11
14
  text: string;
@@ -13,7 +16,8 @@ export interface LyricLine {
13
16
  romanization?: string;
14
17
  words?: LyricWord[];
15
18
  }
16
- export interface LyricsDocument {
19
+ export interface CrLyric {
20
+ format: 'crlyric';
17
21
  version: 1;
18
22
  track: ResourceRef;
19
23
  offsetMs: number;
@@ -21,6 +25,8 @@ export interface LyricsDocument {
21
25
  /** Untimed lyrics only. Empty lines + no plainText means no available lyrics. */
22
26
  plainText?: string;
23
27
  }
28
+ /** @deprecated Use CrLyric. */
29
+ export type LyricsDocument = CrLyric;
24
30
  export interface TrackMetadata {
25
31
  artists: string[];
26
32
  album?: {
package/dist/music.js CHANGED
@@ -68,12 +68,15 @@ export function assertResolveResult(value) {
68
68
  }
69
69
  export function assertLyricsDocument(value) {
70
70
  if (!record(value) ||
71
+ value.format !== 'crlyric' ||
71
72
  value.version !== 1 ||
72
73
  !Number.isFinite(value.offsetMs) ||
73
74
  !Array.isArray(value.lines) ||
74
75
  value.lines.length > 20000)
75
76
  throw new Error('Invalid lyrics document');
76
77
  assertResourceRef(value.track);
78
+ if (value.track.kind !== 'track')
79
+ throw new Error('Lyrics must reference a track');
77
80
  let previous = -1;
78
81
  for (const line of value.lines) {
79
82
  if (!record(line) ||
@@ -0,0 +1,3 @@
1
+ /** Manifest order is authoritative: first is lowest, last is highest. */
2
+ export declare function compareQualities(order: readonly string[], a: string, b: string): -1 | 0 | 1 | undefined;
3
+ export declare function selectQuality(order: readonly string[], available?: readonly string[], requested?: string): string | undefined;
@@ -0,0 +1,18 @@
1
+ /** Manifest order is authoritative: first is lowest, last is highest. */
2
+ export function compareQualities(order, a, b) {
3
+ const left = order.indexOf(a), right = order.indexOf(b);
4
+ if (left < 0 || right < 0)
5
+ return undefined;
6
+ return left === right ? 0 : left < right ? -1 : 1;
7
+ }
8
+ export function selectQuality(order, available = order, requested) {
9
+ const choices = order.filter(quality => available.includes(quality));
10
+ if (!choices.length)
11
+ return undefined;
12
+ if (!requested || !order.includes(requested))
13
+ return choices.at(-1);
14
+ if (choices.includes(requested))
15
+ return requested;
16
+ const index = order.indexOf(requested);
17
+ return choices.filter(quality => order.indexOf(quality) <= index).at(-1) ?? choices[0];
18
+ }
package/package.json CHANGED
@@ -1,126 +1,128 @@
1
- {
2
- "name": "@shiqianjiang/ceru-plugin-sdk",
3
- "version": "0.2.2",
4
- "description": "Typed authoring contracts for Ceru Music v2 single-file plugins",
5
- "type": "module",
6
- "main": "./dist/index.js",
7
- "types": "./dist/index.d.ts",
1
+ {
2
+ "name": "@shiqianjiang/ceru-plugin-sdk",
3
+ "version": "0.2.4",
4
+ "description": "Typed authoring contracts for Ceru Music v2 single-file plugins",
5
+ "type": "module",
6
+ "main": "./dist/index.js",
7
+ "types": "./dist/index.d.ts",
8
8
  "exports": {
9
- ".": {
10
- "types": "./dist/index.d.ts",
11
- "import": "./dist/index.js",
12
- "default": "./dist/index.js"
13
- },
14
- "./manifest": {
15
- "types": "./dist/manifest.d.ts",
16
- "import": "./dist/manifest.js",
17
- "default": "./dist/manifest.js"
18
- },
19
- "./catalog": {
20
- "types": "./dist/catalog.d.ts",
21
- "import": "./dist/catalog.js",
22
- "default": "./dist/catalog.js"
23
- },
24
- "./music": {
25
- "types": "./dist/music.d.ts",
26
- "import": "./dist/music.js",
27
- "default": "./dist/music.js"
28
- },
29
- "./permissions": {
30
- "types": "./dist/permissions.d.ts",
31
- "import": "./dist/permissions.js",
32
- "default": "./dist/permissions.js"
33
- },
34
- "./services": {
35
- "types": "./dist/services.d.ts",
36
- "import": "./dist/services.js",
37
- "default": "./dist/services.js"
38
- },
39
- "./modules": {
40
- "types": "./dist/modules.d.ts",
41
- "import": "./dist/modules.js",
42
- "default": "./dist/modules.js"
43
- },
44
- "./library": {
45
- "types": "./dist/library.d.ts",
46
- "import": "./dist/library.js",
47
- "default": "./dist/library.js"
48
- },
49
- "./host-library": {
50
- "types": "./dist/host-library.d.ts",
51
- "import": "./dist/host-library.js",
52
- "default": "./dist/host-library.js"
53
- },
54
- "./sockets": {
55
- "types": "./dist/sockets.d.ts",
56
- "import": "./dist/sockets.js",
57
- "default": "./dist/sockets.js"
58
- },
59
- "./http": {
60
- "types": "./dist/http.d.ts",
61
- "import": "./dist/http.js",
62
- "default": "./dist/http.js"
63
- },
64
- "./legacy-http": {
65
- "types": "./dist/legacy-http.d.ts",
66
- "import": "./dist/legacy-http.js",
67
- "default": "./dist/legacy-http.js"
68
- },
69
- "./compat/crypto": {
70
- "types": "./dist/compat/crypto.d.ts",
71
- "import": "./dist/compat/crypto.js",
72
- "default": "./dist/compat/crypto.js"
73
- },
74
- "./compat/zlib": {
75
- "types": "./dist/compat/zlib.d.ts",
76
- "import": "./dist/compat/zlib.js",
77
- "default": "./dist/compat/zlib.js"
78
- },
79
- "./compat/encoding": {
80
- "types": "./dist/compat/encoding.d.ts",
81
- "import": "./dist/compat/encoding.js",
82
- "default": "./dist/compat/encoding.js"
83
- },
84
- "./compat/format": {
85
- "types": "./dist/compat/format.d.ts",
86
- "import": "./dist/compat/format.js",
87
- "default": "./dist/compat/format.js"
88
- }
89
- },
90
- "files": [
91
- "dist",
92
- "README.md",
93
- "LICENSE"
94
- ],
95
- "license": "MIT",
96
- "dependencies": {
97
- "@types/lodash": "^4.17.25",
98
- "buffer": "^6.0.3",
99
- "crypto-js": "^4.2.0",
100
- "fflate": "^0.8.2",
101
- "json5": "^2.2.3"
102
- },
103
- "author": "澜音团队",
104
- "engines": {
105
- "node": ">=22.12.0"
106
- },
107
- "publishConfig": {
108
- "access": "public",
109
- "registry": "https://registry.npmjs.org/"
110
- },
111
- "repository": {
112
- "type": "git",
113
- "url": "git+https://github.com/CeruMusic/CeruMusic-Plugin-Cli.git",
114
- "directory": "packages/sdk"
115
- },
116
- "bugs": {
117
- "url": "https://github.com/CeruMusic/CeruMusic-Plugin-Cli/issues"
118
- },
119
- "homepage": "https://github.com/CeruMusic/CeruMusic-Plugin-Cli#readme",
120
- "keywords": [
121
- "ceru-music",
122
- "plugin",
123
- "typescript",
124
- "electron"
125
- ]
126
- }
9
+ "./quality": { "types": "./dist/quality.d.ts", "default": "./dist/quality.js" },
10
+ "./lyrics": { "types": "./dist/lyrics.d.ts", "default": "./dist/lyrics.js" },
11
+ ".": {
12
+ "types": "./dist/index.d.ts",
13
+ "import": "./dist/index.js",
14
+ "default": "./dist/index.js"
15
+ },
16
+ "./manifest": {
17
+ "types": "./dist/manifest.d.ts",
18
+ "import": "./dist/manifest.js",
19
+ "default": "./dist/manifest.js"
20
+ },
21
+ "./catalog": {
22
+ "types": "./dist/catalog.d.ts",
23
+ "import": "./dist/catalog.js",
24
+ "default": "./dist/catalog.js"
25
+ },
26
+ "./music": {
27
+ "types": "./dist/music.d.ts",
28
+ "import": "./dist/music.js",
29
+ "default": "./dist/music.js"
30
+ },
31
+ "./permissions": {
32
+ "types": "./dist/permissions.d.ts",
33
+ "import": "./dist/permissions.js",
34
+ "default": "./dist/permissions.js"
35
+ },
36
+ "./services": {
37
+ "types": "./dist/services.d.ts",
38
+ "import": "./dist/services.js",
39
+ "default": "./dist/services.js"
40
+ },
41
+ "./modules": {
42
+ "types": "./dist/modules.d.ts",
43
+ "import": "./dist/modules.js",
44
+ "default": "./dist/modules.js"
45
+ },
46
+ "./library": {
47
+ "types": "./dist/library.d.ts",
48
+ "import": "./dist/library.js",
49
+ "default": "./dist/library.js"
50
+ },
51
+ "./host-library": {
52
+ "types": "./dist/host-library.d.ts",
53
+ "import": "./dist/host-library.js",
54
+ "default": "./dist/host-library.js"
55
+ },
56
+ "./sockets": {
57
+ "types": "./dist/sockets.d.ts",
58
+ "import": "./dist/sockets.js",
59
+ "default": "./dist/sockets.js"
60
+ },
61
+ "./http": {
62
+ "types": "./dist/http.d.ts",
63
+ "import": "./dist/http.js",
64
+ "default": "./dist/http.js"
65
+ },
66
+ "./legacy-http": {
67
+ "types": "./dist/legacy-http.d.ts",
68
+ "import": "./dist/legacy-http.js",
69
+ "default": "./dist/legacy-http.js"
70
+ },
71
+ "./compat/crypto": {
72
+ "types": "./dist/compat/crypto.d.ts",
73
+ "import": "./dist/compat/crypto.js",
74
+ "default": "./dist/compat/crypto.js"
75
+ },
76
+ "./compat/zlib": {
77
+ "types": "./dist/compat/zlib.d.ts",
78
+ "import": "./dist/compat/zlib.js",
79
+ "default": "./dist/compat/zlib.js"
80
+ },
81
+ "./compat/encoding": {
82
+ "types": "./dist/compat/encoding.d.ts",
83
+ "import": "./dist/compat/encoding.js",
84
+ "default": "./dist/compat/encoding.js"
85
+ },
86
+ "./compat/format": {
87
+ "types": "./dist/compat/format.d.ts",
88
+ "import": "./dist/compat/format.js",
89
+ "default": "./dist/compat/format.js"
90
+ }
91
+ },
92
+ "files": [
93
+ "dist",
94
+ "README.md",
95
+ "LICENSE"
96
+ ],
97
+ "license": "MIT",
98
+ "dependencies": {
99
+ "@types/lodash": "^4.17.25",
100
+ "buffer": "^6.0.3",
101
+ "crypto-js": "^4.2.0",
102
+ "fflate": "^0.8.2",
103
+ "json5": "^2.2.3"
104
+ },
105
+ "author": "澜音团队",
106
+ "engines": {
107
+ "node": ">=22.12.0"
108
+ },
109
+ "publishConfig": {
110
+ "access": "public",
111
+ "registry": "https://registry.npmjs.org/"
112
+ },
113
+ "repository": {
114
+ "type": "git",
115
+ "url": "git+https://github.com/CeruMusic/CeruMusic-Plugin-Cli.git",
116
+ "directory": "packages/sdk"
117
+ },
118
+ "bugs": {
119
+ "url": "https://github.com/CeruMusic/CeruMusic-Plugin-Cli/issues"
120
+ },
121
+ "homepage": "https://github.com/CeruMusic/CeruMusic-Plugin-Cli#readme",
122
+ "keywords": [
123
+ "ceru-music",
124
+ "plugin",
125
+ "typescript",
126
+ "electron"
127
+ ]
128
+ }