MusicFree插件开发与使用完全指南

MusicFree是一款功能强大的音乐播放器，其插件系统为用户提供了无限扩展的可能性。通过安装不同的插件，用户可以接入各种音乐平台、歌词服务和其他音频资源，打造专属的音乐体验。

插件系统概述

MusicFree插件系统采用模块化设计，每个插件都是一个独立的模块，负责处理特定平台或服务的音乐数据。插件通过定义标准接口与播放器核心进行交互，确保功能的一致性和稳定性。

可用插件列表

当前项目提供了多种音乐服务的插件支持：

• Audiomack - 国际音乐平台支持
• Bilibili - 哔哩哔哩音频内容
• 猫耳FM - 有声小说和广播剧
• 快手 - 短视频平台音乐内容
• 音悦台 - 音乐视频平台
• Youtube - 全球视频平台
• WebDAV - 个人云存储音乐
• Navidrome - 自建音乐服务器
• Suno/Udio - AI音乐生成平台
• 歌词网/歌词千寻 - 歌词服务

插件安装方法

自动安装方式

1. 打开MusicFree应用，进入"插件管理"界面
2. 点击"从网络安装"按钮
3. 输入插件配置文件的URL地址
4. 系统会自动验证并安装插件

手动安装步骤

1. 获取插件的JSON配置文件
2. 在MusicFree中依次打开"设置" > "插件管理" > "从文件安装"
3. 选择下载好的JSON文件完成安装

插件开发指南

插件基本结构

每个插件都需要导出一个包含特定属性和方法的对象：

module.exports = {
    platform: "插件名称",
    version: "版本号",
    cacheControl: "缓存策略",
    // 搜索功能
    async search(query, page, type) {
        // 实现搜索逻辑
        return {
            isEnd: true,
            data: searchResults
        }
    },
    // 获取音源
    async getMediaSource(musicItem, quality) {
        // 实现音源获取逻辑
        return {
            url: "音频URL",
            quality: "音质等级"
        }
    }
};

核心接口定义

插件需要实现以下核心接口：

• search - 搜索音乐、专辑、艺术家或歌单
• getMediaSource - 根据音乐信息获取播放地址
• getMusicInfo - 根据主键查询歌曲详细信息
• getLyric - 获取歌词内容
• getAlbumInfo - 获取专辑信息及包含的歌曲
• getArtistWorks - 获取艺术家作品
• importMusicSheet - 导入外部歌单
• getTopLists - 获取音乐榜单
• getTopListDetail - 获取榜单详情

开发示例

参考项目中的示例插件 example/freesound.js，该插件展示了如何：

1. 使用axios进行网络请求
2. 使用cheerio解析HTML内容
3. 构建标准的音乐数据结构
4. 处理分页和搜索结果

数据类型定义

插件开发涉及的主要数据类型包括：

• IMusic.IMusicItem - 音乐项目信息
• IAlbum.IAlbumItem - 专辑信息
• IArtist.IArtistItem - 艺术家信息
• IMusicSheet.IMusicSheetItem - 歌单信息

插件配置说明

缓存策略

插件支持三种缓存控制策略：

• cache - 使用缓存
• no-cache - 不使用缓存
• no-store - 完全不存储缓存

用户变量配置

插件可以定义用户需要输入的变量，如API密钥、服务器地址等：

userVariables: [
    {
        key: "api_key",
        name: "API密钥"
    }
]

构建与测试

项目提供了完整的构建和测试脚本：

# 构建所有插件
npm run build

# 测试特定插件
npm run test-bilibili
npm run test-youtube
npm run test-maoerfm

使用注意事项

1. 版权声明：本仓库的插件仅为示例，来自于网络公开接口，已过滤掉所有VIP/收费/试听歌曲
2. 学习用途：仅供学习参考使用，请勿用于商业用途
3. 合法使用：请合理合法使用插件内容

故障排除

常见问题解决

1. 插件安装失败：检查网络连接，确认插件配置文件格式正确
2. 搜索无结果：验证目标网站接口是否可用，检查网络代理设置
3. 播放失败：确认音频链接有效，检查音质设置

性能优化建议

• 合理设置缓存策略减少网络请求
• 优化搜索算法提高响应速度
• 定期更新插件适配平台变化

项目结构说明

• plugins/ - 各平台插件源码目录
• types/ - TypeScript类型定义文件
• scripts/ - 构建脚本
• test/ - 插件测试文件

通过掌握MusicFree插件的开发和使用方法，你可以根据自己的需求定制专属的音乐体验，接入更多音乐资源和服务。