@shiqianjiang/ceru-plugin-sdk 0.2.3 → 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>>;
@@ -189,6 +192,9 @@ export interface PluginContext extends HostServices {
189
192
  playlistImporters: {
190
193
  register(id: string, implementation: PlaylistImporterImplementation): Disposable;
191
194
  };
195
+ lyricConverters: {
196
+ register(id: string, implementation: import('./lyrics.js').LyricConverter): Disposable;
197
+ };
192
198
  providers: {
193
199
  register(id: string, implementation: ProviderImplementation): Disposable;
194
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,7 @@ 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. */
30
31
  qualities?: string[];
31
32
  icon?: IconRef;
32
33
  connectionMode?: 'none' | 'single' | 'multiple';
@@ -93,6 +94,11 @@ export interface PluginManifest {
93
94
  surfaces?: SurfaceDeclaration[];
94
95
  };
95
96
  contributes?: {
97
+ lyricConverters?: {
98
+ id: string;
99
+ title: string;
100
+ formats: import('./lyrics.js').LyricInputFormat[];
101
+ }[];
96
102
  providers?: ProviderDeclaration[];
97
103
  /** Home tabs exist only while at least one enabled plugin contributes them. */
98
104
  homeSections?: HomeSectionContribution[];
@@ -105,6 +111,12 @@ export interface PluginManifest {
105
111
  playlistImporters?: {
106
112
  id: string;
107
113
  title: string;
114
+ providerId?: string;
115
+ examples?: {
116
+ label: string;
117
+ value: string;
118
+ }[];
119
+ instructions?: string[];
108
120
  description?: string;
109
121
  placeholder?: string;
110
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.3",
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
+ }