@kuriyona/cecilia 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kuriyona
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,69 @@
+# Cecilia
+
+网易云音乐 API 的非官方 TypeScript 封装。
+
+## 安装
+
+```bash
+pnpm add @kuriyona/cecilia
+```
+
+## 使用
+
+```ts
+import { getPlaylistDetail, getLyric, getSongsDetail } from '@kuriyona/cecilia'
+```
+
+### `getPlaylistDetail(id)`
+
+获取歌单详情。
+
+```ts
+const detail = await getPlaylistDetail(123)
+// {
+//   id: 123,
+//   name: '歌单名',
+//   coverImgId: 456,
+//   coverImgUrl: 'https://example.com/cover.jpg',
+//   userId: 789,
+//   createTime: 1000000,
+//   songs: [{ id: 1, addTime: 2000000 }, ...]
+// }
+```
+
+### `getLyric(id)`
+
+获取歌词。
+
+```ts
+const lyric = await getLyric(1)
+// [
+//   { time: 1.5, text: 'Hello' },
+//   { time: 5, text: 'World' },
+// ]
+```
+
+### `getSongsDetail(ids)`
+
+批量获取歌曲详情。
+
+```ts
+const songs = await getSongsDetail([1, 2])
+// [
+//   {
+//     id: 1,
+//     name: 'Song A',
+//     artists: [{ id: 10, name: 'Artist 1' }],
+//     album: { id: 100, name: 'Album A', picUrl: '...' },
+//     duration: 200000,
+//   },
+// ]
+```
+
+## 开发
+
+```bash
+pnpm test        # 运行测试
+pnpm test:watch  # 监听模式
+pnpm build       # 构建
+```

package/dist/index.cjs

@@ -0,0 +1,90 @@
+Object.defineProperties(exports, {
+	__esModule: { value: true },
+	[Symbol.toStringTag]: { value: "Module" }
+});
+//#region src/utils/mergeLyricTimelines.ts
+function mergeLyricTimelines(original, translation) {
+	const originalMap = /* @__PURE__ */ new Map();
+	for (const item of original) originalMap.set(item.time, item.text);
+	const translationMap = /* @__PURE__ */ new Map();
+	for (const item of translation) translationMap.set(item.time, item.text);
+	const allTimes = /* @__PURE__ */ new Set();
+	for (const item of original) allTimes.add(item.time);
+	for (const item of translation) allTimes.add(item.time);
+	const sortedTimes = [...allTimes].sort((a, b) => a - b);
+	const result = [];
+	let lastOriginal;
+	let lastTranslation;
+	for (const time of sortedTimes) {
+		if (originalMap.has(time)) lastOriginal = originalMap.get(time);
+		if (translationMap.has(time)) lastTranslation = translationMap.get(time);
+		result.push({
+			time,
+			text: lastOriginal ?? "",
+			...lastTranslation !== void 0 ? { translation: lastTranslation } : {}
+		});
+	}
+	return result;
+}
+//#endregion
+//#region src/index.ts
+const BASE_URL = "https://music.163.com/api/";
+const getPlaylistDetail = async (id) => {
+	const data = await (await fetch(`${BASE_URL}/v6/playlist/detail?id=${id}`)).json();
+	return {
+		id: data.playlist.id,
+		name: data.playlist.name,
+		coverImgId: data.playlist.coverImgId,
+		coverImgUrl: data.playlist.coverImgUrl,
+		userId: data.playlist.userId,
+		createTime: data.playlist.createTime,
+		songs: data.playlist.trackIds.map((t) => ({
+			id: t.id,
+			addTime: t.at
+		}))
+	};
+};
+const parseLrc = (lrc) => lrc.split("\n").filter((l) => l.startsWith("[")).map((l) => {
+	const match = l.match(/^\[(\d{2}):(\d{2}(?:\.\d{2,3})?)\](.*)/);
+	if (!match) return null;
+	const minutes = parseInt(match[1], 10);
+	const seconds = parseFloat(match[2]);
+	return {
+		time: minutes * 60 + seconds,
+		text: match[3].trim()
+	};
+}).filter((e) => e !== null);
+const getLyric = async (id) => {
+	const data = await (await fetch(`${BASE_URL}/song/lyric?id=${id}&lv=-1&tv=-1`)).json();
+	return {
+		lines: mergeLyricTimelines(parseLrc(data.lrc.lyric), data.tlyric?.lyric ? parseLrc(data.tlyric.lyric) : []),
+		...data.transUser ? { translator: data.transUser } : {}
+	};
+};
+const getSongsDetail = async (ids) => {
+	const query = JSON.stringify(ids.map((id) => ({ id })));
+	return (await (await fetch(`${BASE_URL}/v3/song/detail?c=${query}`)).json()).songs.map((s) => ({
+		id: s.id,
+		name: s.name,
+		artists: s.ar.map((a) => ({
+			id: a.id,
+			name: a.name
+		})),
+		album: {
+			id: s.al.id,
+			name: s.al.name,
+			picUrl: s.al.picUrl
+		},
+		duration: s.dt
+	}));
+};
+var src_default = {
+	getPlaylistDetail,
+	getLyric,
+	getSongsDetail
+};
+//#endregion
+exports.default = src_default;
+exports.getLyric = getLyric;
+exports.getPlaylistDetail = getPlaylistDetail;
+exports.getSongsDetail = getSongsDetail;

package/dist/index.d.cts

@@ -0,0 +1,55 @@
+//#region src/types/Lyric.d.ts
+interface Lyric {
+  lines: LyricLine[];
+  translator?: {
+    id: number;
+    nickname: string;
+  };
+}
+type LyricLine = {
+  time: number;
+  text: string;
+  translation?: string;
+};
+//#endregion
+//#region src/types/PlaylistDetail.d.ts
+interface PlaylistDetails {
+  id: number;
+  name: string;
+  coverImgId: number;
+  coverImgUrl: string;
+  userId: number;
+  createTime: number;
+  songs: {
+    id: number;
+    addTime: number;
+  }[];
+}
+//#endregion
+//#region src/types/SongDetails.d.ts
+type SongDetail = {
+  id: number;
+  name: string;
+  artists: {
+    id: number;
+    name: string;
+  }[];
+  album: {
+    id: number;
+    name: string;
+    picUrl: string;
+  };
+  duration: number;
+};
+//#endregion
+//#region src/index.d.ts
+declare const getPlaylistDetail: (id: number) => Promise<PlaylistDetails>;
+declare const getLyric: (id: number) => Promise<Lyric>;
+declare const getSongsDetail: (ids: number[]) => Promise<SongDetail[]>;
+declare const _default: {
+  getPlaylistDetail: (id: number) => Promise<PlaylistDetails>;
+  getLyric: (id: number) => Promise<Lyric>;
+  getSongsDetail: (ids: number[]) => Promise<SongDetail[]>;
+};
+//#endregion
+export { _default as default, getLyric, getPlaylistDetail, getSongsDetail };

package/dist/index.d.mts

@@ -0,0 +1,55 @@
+//#region src/types/Lyric.d.ts
+interface Lyric {
+  lines: LyricLine[];
+  translator?: {
+    id: number;
+    nickname: string;
+  };
+}
+type LyricLine = {
+  time: number;
+  text: string;
+  translation?: string;
+};
+//#endregion
+//#region src/types/PlaylistDetail.d.ts
+interface PlaylistDetails {
+  id: number;
+  name: string;
+  coverImgId: number;
+  coverImgUrl: string;
+  userId: number;
+  createTime: number;
+  songs: {
+    id: number;
+    addTime: number;
+  }[];
+}
+//#endregion
+//#region src/types/SongDetails.d.ts
+type SongDetail = {
+  id: number;
+  name: string;
+  artists: {
+    id: number;
+    name: string;
+  }[];
+  album: {
+    id: number;
+    name: string;
+    picUrl: string;
+  };
+  duration: number;
+};
+//#endregion
+//#region src/index.d.ts
+declare const getPlaylistDetail: (id: number) => Promise<PlaylistDetails>;
+declare const getLyric: (id: number) => Promise<Lyric>;
+declare const getSongsDetail: (ids: number[]) => Promise<SongDetail[]>;
+declare const _default: {
+  getPlaylistDetail: (id: number) => Promise<PlaylistDetails>;
+  getLyric: (id: number) => Promise<Lyric>;
+  getSongsDetail: (ids: number[]) => Promise<SongDetail[]>;
+};
+//#endregion
+export { _default as default, getLyric, getPlaylistDetail, getSongsDetail };

package/dist/index.mjs

@@ -0,0 +1,83 @@
+//#region src/utils/mergeLyricTimelines.ts
+function mergeLyricTimelines(original, translation) {
+	const originalMap = /* @__PURE__ */ new Map();
+	for (const item of original) originalMap.set(item.time, item.text);
+	const translationMap = /* @__PURE__ */ new Map();
+	for (const item of translation) translationMap.set(item.time, item.text);
+	const allTimes = /* @__PURE__ */ new Set();
+	for (const item of original) allTimes.add(item.time);
+	for (const item of translation) allTimes.add(item.time);
+	const sortedTimes = [...allTimes].sort((a, b) => a - b);
+	const result = [];
+	let lastOriginal;
+	let lastTranslation;
+	for (const time of sortedTimes) {
+		if (originalMap.has(time)) lastOriginal = originalMap.get(time);
+		if (translationMap.has(time)) lastTranslation = translationMap.get(time);
+		result.push({
+			time,
+			text: lastOriginal ?? "",
+			...lastTranslation !== void 0 ? { translation: lastTranslation } : {}
+		});
+	}
+	return result;
+}
+//#endregion
+//#region src/index.ts
+const BASE_URL = "https://music.163.com/api/";
+const getPlaylistDetail = async (id) => {
+	const data = await (await fetch(`${BASE_URL}/v6/playlist/detail?id=${id}`)).json();
+	return {
+		id: data.playlist.id,
+		name: data.playlist.name,
+		coverImgId: data.playlist.coverImgId,
+		coverImgUrl: data.playlist.coverImgUrl,
+		userId: data.playlist.userId,
+		createTime: data.playlist.createTime,
+		songs: data.playlist.trackIds.map((t) => ({
+			id: t.id,
+			addTime: t.at
+		}))
+	};
+};
+const parseLrc = (lrc) => lrc.split("\n").filter((l) => l.startsWith("[")).map((l) => {
+	const match = l.match(/^\[(\d{2}):(\d{2}(?:\.\d{2,3})?)\](.*)/);
+	if (!match) return null;
+	const minutes = parseInt(match[1], 10);
+	const seconds = parseFloat(match[2]);
+	return {
+		time: minutes * 60 + seconds,
+		text: match[3].trim()
+	};
+}).filter((e) => e !== null);
+const getLyric = async (id) => {
+	const data = await (await fetch(`${BASE_URL}/song/lyric?id=${id}&lv=-1&tv=-1`)).json();
+	return {
+		lines: mergeLyricTimelines(parseLrc(data.lrc.lyric), data.tlyric?.lyric ? parseLrc(data.tlyric.lyric) : []),
+		...data.transUser ? { translator: data.transUser } : {}
+	};
+};
+const getSongsDetail = async (ids) => {
+	const query = JSON.stringify(ids.map((id) => ({ id })));
+	return (await (await fetch(`${BASE_URL}/v3/song/detail?c=${query}`)).json()).songs.map((s) => ({
+		id: s.id,
+		name: s.name,
+		artists: s.ar.map((a) => ({
+			id: a.id,
+			name: a.name
+		})),
+		album: {
+			id: s.al.id,
+			name: s.al.name,
+			picUrl: s.al.picUrl
+		},
+		duration: s.dt
+	}));
+};
+var src_default = {
+	getPlaylistDetail,
+	getLyric,
+	getSongsDetail
+};
+//#endregion
+export { src_default as default, getLyric, getPlaylistDetail, getSongsDetail };

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@kuriyona/cecilia",
+  "version": "0.2.0",
+  "description": "网易云音乐 API 的非官方 TypeScript 封装",
+  "keywords": [
+    "api",
+    "music",
+    "netease",
+    "typescript"
+  ],
+  "homepage": "https://github.com/Kuriyona/Cecilia",
+  "bugs": {
+    "url": "https://github.com/Kuriyona/Cecilia/issues"
+  },
+  "license": "MIT",
+  "author": "Kuriyona <kuriyona@outlook.com>",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Kuriyona/Cecilia.git"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "tsdown": "^0.22.1",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.7"
+  },
+  "devEngines": {
+    "packageManager": {
+      "name": "pnpm",
+      "version": "^11.4.0",
+      "onFail": "download"
+    }
+  },
+  "email": "kuriyona@outlook.com",
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}