musicfree-api/README.md

Multi-platform music API library for downloading and searching across various music services

# MusicFree API Library

一个多平台音乐搜索和下载API库，支持多个主流音乐平台，包括网易云音乐、QQ音乐、酷狗音乐、酷我音乐和小米音乐。

## 特性

- 支持多个音乐平台
- 统一的API接口
- 支持搜索歌曲、专辑、艺人、歌单和歌词
- 支持获取不同音质的音乐下载链接
- 支持获取歌词
- 支持导入歌单
- 支持获取排行榜

## 安装

```bash
npm install musicfree-api
```

## 快速开始

### 搜索歌曲

```javascript
const musicAPI = require('musicfree-api');

// 获取所有可用平台
const platforms = musicAPI.getAvailablePlatforms();
console.log(platforms);

// 搜索歌曲
async function searchSongs() {
  try {
    // 在网易云音乐上搜索歌曲
    const results = await musicAPI.search('wy', '周杰伦', 1, 'music');
    console.log(`找到 ${results.data.length} 首歌曲`);
    
    // 获取第一首歌的下载链接
    if (results.data.length > 0) {
      const song = results.data[0];
      console.log(`歌曲: ${song.title} - ${song.artist}`);
      
      // 获取高质量下载链接
      const mediaSource = await musicAPI.getMediaSource('wy', song, 'high');
      console.log(`下载链接: ${mediaSource.url}`);
      
      // 获取歌词
      const lyric = await musicAPI.getLyric('wy', song);
      console.log(`歌词: ${lyric.rawLrc}`);
    }
  } catch (error) {
    console.error('搜索错误:', error);
  }
}

searchSongs();
```

### 获取排行榜

```javascript
const musicAPI = require('musicfree-api');

async function getCharts() {
  try {
    // 获取QQ音乐排行榜
    const topLists = await musicAPI.getTopLists('qq');
    console.log('可用排行榜:');
    
    // 格式因平台而异
    if (Array.isArray(topLists)) {
      topLists.forEach((list, index) => {
        console.log(`${index + 1}. ${list.title}`);
      });
      
      // 获取第一个排行榜详情
      if (topLists.length > 0) {
        const detail = await musicAPI.getTopListDetail('qq', topLists[0]);
        console.log(`排行榜: ${topLists[0].title}`);
        console.log(`歌曲数: ${detail.musicList.length}`);
      }
    } else if (topLists.data) {
      // 处理分类排行榜
      topLists.data.forEach(category => {
        console.log(`[${category.title}]`);
        category.data.forEach(list => {
          console.log(`- ${list.title}`);
        });
      });
    }
  } catch (error) {
    console.error('获取排行榜错误:', error);
  }
}

getCharts();
```

## API 参考

所有API函数都需要指定平台代码作为第一个参数：
- `wy`: 网易云音乐
- `qq`: QQ音乐
- `kg`: 酷狗音乐
- `kw`: 酷我音乐
- `xiaomi`: 小米音乐

### 核心功能

#### `getAvailablePlatforms()`

获取所有可用的平台及其名称。

返回: 包含平台代码和名称的对象。

#### `search(platform, keyword, page = 1, type = 'music')`

在指定平台上搜索内容。

参数:
- `platform`: 平台代码
- `keyword`: 搜索关键词
- `page`: 页码 (默认: 1)
- `type`: 搜索类型，可以是 'music', 'album', 'artist', 'sheet', 'lyric'

返回: 包含搜索结果的对象。

#### `getMediaSource(platform, song, quality = 'high')`

获取歌曲的媒体源URL。

参数:
- `platform`: 平台代码
- `song`: 从搜索结果获得的歌曲对象
- `quality`: 音质，可以是 'low', 'standard', 'high', 'super'

返回: 包含媒体URL的对象。

#### `getLyric(platform, song)`

获取歌曲的歌词。

参数:
- `platform`: 平台代码
- `song`: 从搜索结果获得的歌曲对象

返回: 包含歌词的对象。

### 专辑和艺人

#### `getAlbumInfo(platform, album)`

获取专辑详情。

参数:
- `platform`: 平台代码
- `album`: 从搜索结果获得的专辑对象

返回: 包含专辑详情和曲目的对象。

#### `getArtistWorks(platform, artist, page = 1, type = 'music')`

获取艺人的作品（歌曲或专辑）。

参数:
- `platform`: 平台代码
- `artist`: 从搜索结果获得的艺人对象
- `page`: 页码 (默认: 1)
- `type`: 作品类型，可以是 'music' 或 'album'

返回: 包含艺人作品的对象。

### 歌单和排行榜

#### `importMusicSheet(platform, url)`

从URL导入歌单。

参数:
- `platform`: 平台代码
- `url`: 歌单URL

返回: 包含歌单曲目的数组。

#### `getTopLists(platform)`

获取平台上可用的排行榜。

参数:
- `platform`: 平台代码

返回: 包含排行榜的数组或对象（视平台而定）。

#### `getTopListDetail(platform, topList)`

获取排行榜详情。

参数:
- `platform`: 平台代码
- `topList`: 从getTopLists获得的排行榜对象

返回: 包含排行榜详情和曲目的对象。

#### `getRecommendSheetTags(platform)`

获取推荐的歌单标签。

参数:
- `platform`: 平台代码

返回: 包含标签的对象。

#### `getRecommendSheetsByTag(platform, tag, page = 1)`

获取特定标签的推荐歌单。

参数:
- `platform`: 平台代码
- `tag`: 从getRecommendSheetTags获得的标签对象
- `page`: 页码 (默认: 1)

返回: 包含推荐歌单的对象。

#### `getMusicSheetInfo(platform, sheet, page = 1)`

获取歌单信息和曲目。

参数:
- `platform`: 平台代码
- `sheet`: 从搜索结果获得的歌单对象
- `page`: 页码 (默认: 1)

返回: 包含歌单详情和曲目的对象。

## 命令行工具

库同时提供了一个命令行工具，可以通过以下方式使用：

```bash
npx musicfree-api
```

或者全局安装：

```bash
npm install -g musicfree-api
musicfree-api
```

## 注意事项

- 部分功能可能需要登录才能使用
- VIP歌曲可能无法获取下载链接
- 不同平台的API返回格式可能有所不同
- 请勿滥用API进行大量请求

## 许可证

MIT