首页
/ MusicFree插件示例代码：常见功能实现参考

MusicFree插件示例代码：常见功能实现参考

2026-02-04 04:45:55作者：苗圣禹Peter
MusicFree
插件化、定制化、无广告的免费音乐播放器
项目地址：https://gitcode.com/GitHub_Trending/mu/MusicFree

还在为MusicFree插件开发而烦恼吗？本文为你提供全面的插件开发示例代码，涵盖搜索、播放、歌单导入等核心功能，助你快速上手插件开发！

插件基础结构

每个MusicFree插件都是一个CommonJS模块，必须返回一个符合IPluginDefine接口的对象：

module.exports = {
    // 平台名称（必填）
    platform: "示例音乐平台",
    
    // 插件版本
    version: "1.0.0",
    
    // 支持的MusicFree版本
    appVersion: ">=0.6.0",
    
    // 插件描述
    description: "示例音乐平台插件，支持搜索、播放等功能",
    
    // 支持的搜索类型
    supportedSearchType: ["music", "album", "artist"],
    
    // 默认搜索类型
    defaultSearchType: "music",
    
    // 缓存控制
    cacheControl: "cache",
    
    // 用户自定义变量
    userVariables: [
        {
            key: "apiKey",
            name: "API密钥",
            hint: "请输入音乐平台的API密钥"
        }
    ],
    
    // 搜索功能
    search: async function(query, page, type) {
        // 搜索实现
    },
    
    // 获取媒体源
    getMediaSource: async function(musicItem, quality) {
        // 播放源获取实现
    },
    
    // 其他功能方法...
};

核心功能实现示例

1. 搜索功能实现

// 音乐搜索示例
search: async function(query, page, type) {
    try {
        const pageSize = 20;
        const response = await axios.get('https://api.example.com/search', {
            params: {
                keyword: query,
                type: type,
                page: page,
                pageSize: pageSize
            },
            headers: {
                'User-Agent': 'Mozilla/5.0 (compatible; MusicFree)'
            }
        });
        
        const data = response.data;
        
        // 处理音乐搜索结果
        if (type === 'music') {
            return {
                isEnd: data.isEnd || (data.list && data.list.length < pageSize),
                data: data.list.map(item => ({
                    id: item.id,
                    platform: "示例音乐平台",
                    title: item.name,
                    artist: item.artists.map(a => a.name).join('/'),
                    duration: item.duration / 1000, // 转换为秒
                    artwork: item.album.picUrl,
                    album: item.album.name
                }))
            };
        }
        
        // 处理专辑搜索结果
        if (type === 'album') {
            return {
                isEnd: data.isEnd,
                data: data.list.map(item => ({
                    id: item.id,
                    platform: "示例音乐平台",
                    title: item.name,
                    artist: item.artist.name,
                    artwork: item.picUrl,
                    description: item.description
                }))
            };
        }
        
        // 处理歌手搜索结果
        if (type === 'artist') {
            return {
                isEnd: data.isEnd,
                data: data.list.map(item => ({
                    id: item.id,
                    platform: "示例音乐平台",
                    name: item.name,
                    avatar: item.picUrl,
                    worksNum: item.musicSize
                }))
            };
        }
        
    } catch (error) {
        console.error('搜索失败:', error);
        return {
            isEnd: true,
            data: []
        };
    }
}

2. 播放源获取实现

getMediaSource: async function(musicItem, quality = 'standard') {
    try {
        // 根据音质选择对应的URL
        const qualityMap = {
            'low': '128kbps',
            'standard': '320kbps', 
            'high': 'flac',
            'super': 'hires'
        };
        
        const response = await axios.get('https://api.example.com/song/url', {
            params: {
                id: musicItem.id,
                quality: qualityMap[quality]
            }
        });
        
        const urlInfo = response.data.data[0];
        
        if (!urlInfo.url) {
            throw new Error('无法获取播放地址');
        }
        
        return {
            url: urlInfo.url,
            headers: {
                'Referer': 'https://example.com/',
                'User-Agent': 'Mozilla/5.0 (compatible; MusicFree)'
            },
            quality: quality,
            userAgent: 'Mozilla/5.0 (compatible; MusicFree)'
        };
        
    } catch (error) {
        console.error('获取播放源失败:', error);
        return null;
    }
}

3. 歌词获取实现

getLyric: async function(musicItem) {
    try {
        const response = await axios.get('https://api.example.com/lyric', {
            params: { id: musicItem.id }
        });
        
        const lyricData = response.data;
        
        return {
            rawLrc: lyricData.lrc?.lyric || '',
            translation: lyricData.tlyric?.lyric || ''
        };
        
    } catch (error) {
        console.error('获取歌词失败:', error);
        return null;
    }
}

4. 歌单导入实现

importMusicSheet: async function(urlLike) {
    try {
        // 解析歌单ID
        const match = urlLike.match(/playlist\/(\d+)/);
        if (!match) {
            throw new Error('无效的歌单链接');
        }
        
        const playlistId = match[1];
        const response = await axios.get(`https://api.example.com/playlist/detail`, {
            params: { id: playlistId }
        });
        
        const playlist = response.data.playlist;
        
        // 获取歌单所有歌曲
        const allSongs = [];
        let offset = 0;
        const limit = 500;
        
        while (true) {
            const trackResponse = await axios.get('https://api.example.com/playlist/track/all', {
                params: {
                    id: playlistId,
                    limit: limit,
                    offset: offset
                }
            });
            
            const tracks = trackResponse.data.songs;
            allSongs.push(...tracks);
            
            if (tracks.length < limit) {
                break;
            }
            offset += limit;
        }
        
        return allSongs.map(song => ({
            id: song.id,
            platform: "示例音乐平台",
            title: song.name,
            artist: song.ar.map(a => a.name).join('/'),
            duration: song.dt / 1000,
            artwork: song.al.picUrl,
            album: song.al.name
        }));
        
    } catch (error) {
        console.error('导入歌单失败:', error);
        return null;
    }
}

5. 专辑信息获取

getAlbumInfo: async function(albumItem, page = 1) {
    try {
        const pageSize = 50;
        const response = await axios.get('https://api.example.com/album', {
            params: {
                id: albumItem.id,
                limit: pageSize,
                offset: (page - 1) * pageSize
            }
        });
        
        const albumData = response.data;
        const songs = albumData.songs || [];
        
        return {
            albumItem: {
                ...albumItem,
                description: albumData.album.description,
                publishTime: albumData.album.publishTime
            },
            musicList: songs.map(song => ({
                id: song.id,
                platform: "示例音乐平台",
                title: song.name,
                artist: song.ar.map(a => a.name).join('/'),
                duration: song.dt / 1000,
                artwork: song.al.picUrl,
                album: song.al.name
            })),
            isEnd: songs.length < pageSize
        };
        
    } catch (error) {
        console.error('获取专辑信息失败:', error);
        return null;
    }
}

高级功能示例

6. 用户变量使用

// 在插件中使用用户配置的变量
search: async function(query, page, type) {
    const apiKey = env.userVariables?.apiKey;
    if (!apiKey) {
        throw new Error('请先配置API密钥');
    }
    
    const response = await axios.get('https://api.example.com/search', {
        params: {
            keyword: query,
            type: type,
            page: page,
            api_key: apiKey
        }
    });
    
    // 处理结果...
}

7. 错误处理和重试机制

getMediaSource: async function(musicItem, quality, retryCount = 3) {
    for (let attempt = 1; attempt <= retryCount; attempt++) {
        try {
            const response = await axios.get('https://api.example.com/song/url', {
                params: { id: musicItem.id, quality: quality },
                timeout: 5000
            });
            
            if (response.data.code === 200) {
                return {
                    url: response.data.data[0].url,
                    headers: { 'User-Agent': 'MusicFree' }
                };
            }
            
        } catch (error) {
            if (attempt === retryCount) {
                console.error(`获取播放源失败（尝试${attempt}次）:`, error);
                return null;
            }
            await new Promise(resolve => setTimeout(resolve, 1000 * attempt));
        }
    }
}

8. 缓存策略实现

// 使用内存缓存提高性能
const searchCache = new Map();

search: async function(query, page, type) {
    const cacheKey = `${query}-${type}-${page}`;
    
    // 检查缓存
    if (searchCache.has(cacheKey)) {
        return searchCache.get(cacheKey);
    }
    
    try {
        const result = await actualSearchImplementation(query, page, type);
        
        // 缓存结果（5分钟有效期）
        searchCache.set(cacheKey, result);
        setTimeout(() => searchCache.delete(cacheKey), 5 * 60 * 1000);
        
        return result;
    } catch (error) {
        console.error('搜索失败:', error);
        return { isEnd: true, data: [] };
    }
}

最佳实践和注意事项

代码质量规范

// 1. 统一的错误处理
function withErrorHandling(fn, defaultReturn) {
    return async function(...args) {
        try {
            return await fn(...args);
        } catch (error) {
            console.error('操作失败:', error.message);
            return defaultReturn;
        }
    };
}

// 2. 参数验证
function validateMusicItem(musicItem) {
    if (!musicItem || !musicItem.id || !musicItem.platform) {
        throw new Error('无效的音乐项目');
    }
}

// 3. 使用安全的HTTP请求
async function safeRequest(url, options = {}) {
    const controller = new AbortController();
    const timeoutId = setTimeout(() => controller.abort(), 10000);
    
    try {
        const response = await fetch(url, {
            ...options,
            signal: controller.signal,
            headers: {
                'User-Agent': 'MusicFree/1.0',
                ...options.headers
            }
        });
        
        clearTimeout(timeoutId);
        return response;
    } catch (error) {
        clearTimeout(timeoutId);
        throw error;
    }
}

性能优化建议

// 1. 批量请求优化
async function batchGetMediaSources(musicItems, quality) {
    const ids = musicItems.map(item => item.id).join(',');
    const response = await axios.get('https://api.example.com/song/url/batch', {
        params: { ids, quality }
    });
    
    return musicItems.map(item => {
        const urlInfo = response.data.find(d => d.id === item.id);
        return {
            url: urlInfo?.url,
            headers: { 'User-Agent': 'MusicFree' }
        };
    });
}

// 2. 请求去重
const pendingRequests = new Map();

async function deduplicatedRequest(key, requestFn) {
    if (pendingRequests.has(key)) {
        return pendingRequests.get(key);
    }
    
    const promise = requestFn();
    pendingRequests.set(key, promise);
    
    try {
        return await promise;
    } finally {
        pendingRequests.delete(key);
    }
}

完整插件示例

module.exports = {
    platform: "ExampleMusic",
    version: "1.0.0",
    appVersion: ">=0.6.0",
    description: "示例音乐平台插件",
    supportedSearchType: ["music", "album", "artist"],
    defaultSearchType: "music",
    cacheControl: "cache",
    
    userVariables: [
        {
            key: "apiKey",
            name: "API密钥",
            hint: "请输入ExampleMusic的API密钥"
        }
    ],
    
    search: async function(query, page, type) {
        const apiKey = env.userVariables?.apiKey;
        if (!apiKey) throw new Error("请配置API密钥");
        
        const response = await axios.get('https://api.example.com/search', {
            params: { q: query, type, page, limit: 20, api_key: apiKey }
        });
        
        return processSearchResult(response.data, type);
    },
    
    getMediaSource: async function(musicItem, quality) {
        const response = await axios.get('https://api.example.com/song/url', {
            params: { id: musicItem.id, quality }
        });
        
        return {
            url: response.data.url,
            headers: { 'User-Agent': 'MusicFree' },
            quality: quality
        };
    },
    
    getLyric: async function(musicItem) {
        const response = await axios.get('https://api.example.com/lyric', {
            params: { id: musicItem.id }
        });
        
        return {
            rawLrc: response.data.lrc,
            translation: response.data.tlyrc
        };
    }
};

function processSearchResult(data, type) {
    // 统一的搜索结果处理逻辑
    switch (type) {
        case 'music':
            return processMusicResults(data);
        case 'album':
            return processAlbumResults(data);
        case 'artist':
            return processArtistResults(data);
        default:
            return { isEnd: true, data: [] };
    }
}

总结

通过本文的示例代码，你应该已经掌握了MusicFree插件开发的核心技能。记住以下关键点：

  1. 遵循接口规范：严格实现IPluginDefine接口定义的方法
  2. 错误处理：完善的错误处理机制确保插件稳定性
  3. 性能优化：合理使用缓存和批量请求提升用户体验
  4. 用户友好：清晰的错误提示和配置指引

现在就开始你的插件开发之旅吧！如有问题，欢迎在MusicFree社区交流讨论。

MusicFree
插件化、定制化、无广告的免费音乐播放器
项目地址：https://gitcode.com/GitHub_Trending/mu/MusicFree
登录后查看全文

相关内容推荐

1 MusicFree插件系统深度排障指南：从现象到本质的系统解决方法论2 MusicFree的插件生态系统：探索第三方插件 3 MusicFree插件故障排除完全指南：从问题定位到预防措施4 MusicFree插件化音乐播放器完全使用指南5 MusicFree插件故障排除全攻略：从加载失败到功能异常的系统解决方案6 MusicFree插件故障排除：常见问题与解决方案7 解锁无限音乐体验：MusicFree插件完全攻略手册 🎵8 颠覆音乐体验：MusicFree插件系统如何重构你的音乐世界9 MusicFree插件开发与使用完全指南10 MusicFree插件系统完全指南：从入门到精通
热门项目推荐
相关项目推荐

热门内容推荐

1 如何通过技术构建掌握核心原理？从零开始的实践学习路径2 编程技能树构建指南：从0到1掌握实战开发能力3 解构技术黑箱：从零构建核心系统的实践指南4 解构技术黑箱：从0到1构建核心系统的实践指南5 从零构建技术实践：build-your-own-x项目的实践指南6 从零构建技术实践指南：探索build-your-own-x项目的学习价值

最新内容推荐

从配置混乱到智能管理：DsHidMini设备个性化配置系统的进化之路如何用G-Helper优化华硕笔记本性能？8MB轻量化工具的实战指南打破音乐枷锁：用Unlock Music解放你的加密音频文件网盘加速工具配置指南：从网络诊断到高效下载的完整方案UI-TARS-desktop环境搭建全攻略：从零基础到成功运行的5个关键步骤突破Windows界面限制：ExplorerPatcher让系统交互回归高效本质突破Arduino ESP32安装困境：从根本解决下载失败的实战指南Notion数据管理高效工作流：从整理到关联的完整指南设计资源解锁：探索Fluent Emoji的创意应用与设计升级路径StarRocks Stream Load数据导入实战指南：从问题解决到性能优化

项目优选

收起
docsdocs
暂无描述
Dockerfile
689
4.46 K
pytorchpytorch
Ascend Extension for PyTorch
Python
543
668
atomcodeatomcode
Claude Code 的开源替代方案。连接任意大模型，编辑代码，运行命令，自动验证 — 全自动执行。用 Rust 构建，极致性能。 ｜ An open-source alternative to Claude Code. Connect any LLM, edit code, run commands, and verify changes — autonomously. Built in Rust for speed. Get Started
Rust
403
73
ops-mathops-math
本项目是CANN提供的数学类基础计算算子库，实现网络在NPU上加速计算。
C++
955
928
communitycommunity
本项目是CANN开源社区的核心管理仓库，包含社区的治理章程、治理组织、通用操作指引及流程规范等基础信息
648
230
kernelkernel
openEuler内核是openEuler操作系统的核心，既是系统性能与稳定性的基石，也是连接处理器、设备与服务的桥梁。
C
407
323
Oohos_react_native
React Native鸿蒙化仓库
C++
336
386
RuoYi-Vue3RuoYi-Vue3
🎉 (RuoYi)官方仓库 基于SpringBoot，Spring Security，JWT，Vue3 & Vite、Element Plus 的前后端分离权限管理系统
Vue
1.59 K
924
MindSpeed-LLMMindSpeed-LLM
昇腾LLM分布式训练框架
Python
146
172
flutter_flutterflutter_flutter
暂无简介
Dart
935
234