## File: README.md

<h2 align="center">🎵 Alger Music Player</h2>




[项目下安装以及常用问题文档](https://www.yuque.com/alger-pfg5q/ip4f1a/bmgmfmghnhgwghkm?singleDoc#)

主要功能如下

- 🎵 音乐推荐
- 🔐 账号登录与同步
- 📝 功能
  - 播放历史记录
  - 歌曲收藏管理
  - 歌单 MV 排行榜 每日推荐
  - 自定义快捷键配置（全局或应用内）
- 🎨 界面与交互
  - 沉浸式歌词显示（点击左下角封面进入）
  - 独立桌面歌词窗口
  - 明暗主题切换
  - 迷你模式
  - 状态栏控制
  - 多语言支持
- 🎼 音乐功能
  - 支持歌单、MV、专辑等完整音乐服务
  - 音乐资源解析（基于 @unblockneteasemusic/server）
  - EQ均衡器
  - 定时播放 远程控制播放 倍速播放
  - 高品质音乐
  - 音乐文件下载
  - 搜索 MV 音乐 专辑 歌单 bilibili
  - 音乐单独选择音源解析
- 🚀 技术特性
  - 本地化服务，无需依赖在线API (基于 netease-cloud-music-api)
  - 全平台适配（Desktop & Web & Mobile Web & Android<测试> & ios<后续>）

## 项目简介

一个第三方音乐播放器、本地服务、桌面歌词、音乐下载、最高音质

## 预览地址

[http://music.alger.fun/](http://music.alger.fun/)

## 软件截图








## 项目启动

```bash
npm install
npm run dev
```

## 开发文档

点击这里[开发文档](./DEV.md)

## 赞赏☕️

[赞赏列表](http://donate.alger.fun/)
| 微信赞赏 | 支付宝赞赏 |
| :--------------------------------------------------------------------------------: | :--------------------------------------------------------------------------------: |
|  <small>喝点咖啡继续干</small> |  <small>来包辣条吧~</small> |

## 项目统计

[](https://starchart.cc/algerkong/AlgerMusicPlayer)


## 欢迎提Issues

## 声明

本软件仅用于学习交流，禁止用于商业用途，否则后果自负。
希望大家还是要多多支持官方正版，此软件仅用作开发教学。

---

## File: docs/custom-api-readme.md

## 🎵 自定义音源API配置

现在支持通过导入一个简单的 JSON 配置文件来对接第三方的音乐解析 API。这将提供极大的灵活性，可以接入任意第三方音源。

### 如何使用

1.  前往 **设置 -> 播放设置 -> 音源设置**。
2.  在 **自定义 API 设置** 区域，点击 **“导入 JSON 配置”** 按钮。
3.  选择你已经编写好的 `xxx.json` 配置文件。
4.  导入成功后，程序将优先使用你的自定义 API 进行解析。

### JSON 配置文件格式说明

导入的配置文件必须是一个合法的 JSON 文件，并包含以下字段：

| 字段名            | 类型     | 是否必须 | 描述                                                                                                                        |
| ----------------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------- |
| `name`            | `string` | 是       | API 名称，将显示在应用的 UI 界面上。                                                                                        |
| `apiUrl`          | `string` | 是       | API 的基础请求地址。                                                                                                        |
| `method`          | `string` | 否       | HTTP 请求方法。可以是 `"GET"` 或 `"POST"`。**如果省略，默认为 "GET"**。                                                     |
| `params`          | `object` | 是       | 请求时需要发送的参数。对于 `GET` 请求，它们会作为查询字符串；对于 `POST` 请求，它们会作为请求体。                           |
| `qualityMapping`  | `object` | 否       | **音质映射表**。用于将应用内部的音质值（如 `"lossless"`）翻译成你的 API 需要的特定值。如果省略，则直接使用应用内部值。      |
| `responseUrlPath` | `string` | 是       | **URL提取路径**。用于从 API 返回的 JSON 响应中找到最终可播放的音乐链接。支持点 `.` 和方括号 `[]` 语法来访问嵌套对象和数组。 |

#### 占位符

在 `params` 对象的值中，你可以使用以下占位符，程序在请求时会自动替换它们：

- `{songId}`: 将被替换为当前歌曲的 ID。
- `{quality}`: 将被替换为当前用户设置的音质字符串 (例如, `"higher"`, `"lossless"`)。

#### 音质值列表

应用内部使用的音质值如下，你可以在 `qualityMapping` 中使用它们作为**键**：
`standard`, `higher`, `exhigh`, `lossless`, `hires`, `jyeffect`, `sky`, `dolby`, `jymaster`

### 示例

假设有一个 API 如下：
`https://api.example.com/music?song_id=12345&bitrate=320000`
它返回的 JSON 是：
`{ "code": 200, "data": { "play_url": "http://..." } }`

那么对应的 JSON 配置文件应该是：

```json
{
  "name": "Example API",
  "apiUrl": "https://api.example.com/music",
  "method": "GET",
  "params": {
    "song_id": "{songId}",
    "bitrate": "{quality}"
  },
  "qualityMapping": {
    "higher": "128000",
    "exhigh": "320000",
    "lossless": "999000"
  },
  "responseUrlPath": "data.play_url"
}
```