自制网页音乐播放器AuroraPlayer，可用于博客插入

# AuroraPlayer 一个轻量级、功能丰富的网页音乐播放器-可以引入到网站,博客等 # 🎵 本地音乐播放器 v2.2 一个轻量级、功能丰富的本地音乐播放器，基于原网易云音乐播放器修改，专为本地文件播放优化。 ## ✨ 功能特性 ### 🎵 核心播放功能 - **本地音乐播放** - 支持MP3、WAV、OGG等主流音频格式 - **歌词同步显示** - 支持标准LRC格式歌词文件 - **自动重播** - 歌曲播放结束后自动重新开始 - **进度控制** - 可拖动进度条精确定位 ### 🎨 界面设计 - **圆盘模式** - 黑胶唱片风格的视觉效果 - **随机封面** - 无封面时自动获取精美图片 - **响应式设计** - 完美适配桌面端和移动端 - **多主题支持** - 自动/亮色/暗色主题切换 - **平滑动画** - 流畅的过渡和交互动效 ### 🔧 高级功能 - **最小化模式** - 可缩小为悬浮按钮，节省屏幕空间 - **嵌入模式** - 适合iframe或小区域集成 - **智能封面** - 支持自定义封面URL或随机API - **用户交互检测** - 优化的自动播放策略 - **音量控制** - 精确的音量调节 ### 📱 移动端优化 - **触摸优化** - 完美支持触摸屏操作 - **自适应布局** - 根据屏幕大小自动调整 - **手势支持** - 滑动、点击等自然交互 ## 🚀 快速开始 ### 1. 基本用法 ### 1️⃣ 引入文件 ```html <!-- 引入 CSS (HEAD标签内) --> <link rel="stylesheet" href="/music.css"> <!-- 引入 JS (BODY标签底部) --> <script src="/music.js"></script> ``` ### 2️⃣ 使用播放器 #### 方法 A：使用 HTML 标签 (标准) 适合开发者或固定布局使用： ```html <div class="netease-mini-player" data-music-file="audio/岸边客 (心碎版0.9x)-夏子航（2603）.mp3" data-lyric-file="audio/岸边客 (心碎版0.9x)-夏子航（2603）.lrc" data-autoplay="true" data-position="static" data-theme="auto" data-size="normal"> </div> ``` #### 方法 B：使用短代码 (推荐 v2.2+) 播放器内置了短代码解析功能，支持以下格式： ##### 📝 短代码格式 **基础格式：** ```html {nmpv2:music-file=audio/song.mp3,lyric-file=audio/song.lrc,autoplay=true} ``` **完整格式：** ```html {nmpv2:music-file=audio/岸边客.mp3,lyric-file=audio/岸边客.lrc,position=bottom-right,cover-mode=true,default-minimized=true,theme=auto} ``` ##### 🎯 支持的短代码参数 | 参数 | 对应 data-* 属性 | 类型 | 默认值 | 说明 | |------|------------------|------|--------|------| | `position` | `data-position` | string | `static` | 播放器位置 | | `theme` | `data-theme` | string | `auto` | 主题模式 | | `lyric` | `data-lyric` | boolean | `true` | 显示歌词 | | `embed` | `data-embed` | boolean | `false` | 嵌入模式 | | `minimized` | `data-default-minimized` | boolean | `false` | 默认最小化 | | `autoplay` | `data-autoplay` | boolean | `false` | 自动播放 | | `idle-opacity` | `data-idle-opacity` | string | 可选 | 空闲透明度 | | `auto-pause` | `data-auto-pause` | boolean | `false` | 页面隐藏暂停 | | `cover-mode` | `data-cover-mode` | boolean | `false` | 圆盘模式 | | `cover-url` | `data-cover-url` | string | 可选 | 自定义封面 | ##### 🛠️ WordPress 集成示例 **方法1：直接使用短代码（推荐）** ```php // 在文章或页面中直接使用 {nmpv2:music-file=audio/歌曲.mp3,lyric-file=audio/歌曲.lrc,autoplay=true} ``` **方法2：创建自定义短代码** ```php // 在主题的 functions.php 中添加 function music_player_shortcode($atts) { $atts = shortcode_atts(array( // 核心参数 'music' => '', 'lyric' => '', 'autoplay' => 'false', 'position' => 'static', 'theme' => 'auto', 'size' => 'compact', 'lyric' => 'true', 'embed' => 'false', // 界面参数 'cover_mode' => 'false', 'cover_url' => '', 'default_minimized' => 'false', 'idle_opacity' => '', // 行为参数 'auto_pause' => 'false' ), $atts); ob_start(); ?> <div class="netease-mini-player" data-music-file="<?php echo esc_attr($atts['music']); ?>" data-lyric-file="<?php echo esc_attr($atts['lyric']); ?>" data-autoplay="<?php echo esc_attr($atts['autoplay']); ?>" data-position="<?php echo esc_attr($atts['position']); ?>" data-theme="<?php echo esc_attr($atts['theme']); ?>" data-size="<?php echo esc_attr($atts['size']); ?>" data-lyric="<?php echo esc_attr($atts['lyric']); ?>" data-embed="<?php echo esc_attr($atts['embed']); ?>" data-cover-mode="<?php echo esc_attr($atts['cover_mode']); ?>" data-cover-url="<?php echo esc_attr($atts['cover_url']); ?>" data-default-minimized="<?php echo esc_attr($atts['default_minimized']); ?>" <?php if (!empty($atts['idle_opacity'])): ?> data-idle-opacity="<?php echo esc_attr($atts['idle_opacity']); ?>" <?php endif; ?> data-auto-pause="<?php echo esc_attr($atts['auto_pause']); ?>" >> </div> <?php return ob_get_clean(); } add_shortcode('music_player', 'music_player_shortcode'); ``` ##### 📋 使用示例 **基础播放器：** ```html {nmpv2:music-file=audio/demo.mp3} ``` **带歌词的播放器：** ```html {nmpv2:music-file=audio/demo.mp3,lyric-file=audio/demo.lrc,autoplay=true} ``` **悬浮播放器（右下角）：** ```html {nmpv2:music-file=audio/song.mp3,position=bottom-right,cover-mode=true,default-minimized=true} ``` **嵌入式播放器：** ```html {nmpv2:music-file=audio/background.mp3,embed=true,autoplay=true,auto-pause=false} ``` **自定义封面：** ```html {nmpv2:music-file=audio/music.mp3,cover-url=https://picsum.photos/seed/music/300/300.jpg,cover-mode=true} ``` **完整配置：** ```html {nmpv2:music-file=audio/岸边客.mp3,lyric-file=audio/岸边客.lrc,position=bottom-right,cover-mode=true,default-minimized=true,theme=dark,autoplay=false,size=normal} ``` ## 📋 参数速查表 ### 🎯 快速配置 #### 最简配置 ```html <div class="netease-mini-player" data-music-file="audio/song.mp3"></div> ``` #### 标准配置 ```html <div class="netease-mini-player" data-music-file="audio/song.mp3" data-lyric-file="audio/song.lrc" data-autoplay="true" data-position="bottom-right"> </div> ``` #### 完整配置 ```html <div class="netease-mini-player" data-music-file="audio/song.mp3" data-lyric-file="audio/song.lrc" data-autoplay="true" data-position="bottom-right" data-theme="auto" data-size="normal" data-lyric="true" data-embed="false" data-cover-mode="true" data-cover-url="https://example.com/cover.jpg" data-default-minimized="true" data-auto-pause="true" data-idle-opacity="0.3"> </div> ``` ### 🎮 短代码快捷方式 | 需求 | 短代码 | 说明 | |------|--------|------| | 基础播放 | `{nmpv2:music-file=song.mp3}` | 最简单的播放器 | | 带歌词 | `{nmpv2:music-file=song.mp3,lyric-file=song.lrc}` | 显示歌词 | | 自动播放 | `{nmpv2:music-file=song.mp3,autoplay=true}` | 页面加载后播放 | | 悬浮模式 | `{nmpv2:music-file=song.mp3,position=bottom-right}` | 右下角悬浮 | | 圆盘模式 | `{nmpv2:music-file=song.mp3,cover-mode=true}` | 黑胶唱片风格 | --- ## 📝 2. 文件命名规则 为了让播放器自动识别歌曲信息，建议按以下格式命名： **推荐格式：** `歌名-歌手.扩展名` ``` ✅ 正确示例： - 岸边客 (心碎版0.9x)-夏子航（2603）.mp3 - 月亮之上-凤凰传奇.lrc - 夜曲-周杰伦.mp3 ❌ 不推荐： - song1.mp3 - 音乐文件.mp3 ``` ### 3. 完整配置参数 | 参数 | 类型 | 默认值 | 说明 | 示例 | |------|------|--------|------|------| | **data-music-file** | string | 必填 | 音乐文件路径 | `audio/song.mp3`, `audio/music/歌曲.mp3` | | **data-lyric-file** | string | 可选 | 歌词文件路径 | `audio/song.lrc`, `lyrics/歌词.lrc` | | **data-autoplay** | boolean | false | 是否自动播放 | `true`, `false` | | **data-position** | string | static | 播放器位置 | `static`, `top-left`, `top-right`, `bottom-left`, `bottom-right` | | **data-theme** | string | auto | 主题模式 | `auto`, `light`, `dark` | | **data-lyric** | boolean | true | 是否显示歌词 | `true`, `false` | | **data-embed** | boolean | false | 嵌入模式 | `true`, `false` | | **data-cover-mode** | boolean | false | 圆盘模式 | `true`, `false` | | **data-cover-url** | string | 可选 | 自定义封面 | `https://picsum.photos/300/300.jpg`, `/images/cover.jpg` | | **data-default-minimized** | boolean | false | 默认最小化 | `true`, `false` | | **data-size** | string | compact | 播放器尺寸 | `compact`, `normal`, `large` | | **data-auto-pause** | boolean | false | 页面隐藏时暂停 | `true`, `false` | | **data-idle-opacity** | string | 可选 | 空闲透明度 | `0.1`, `0.3`, `0.5`, `0.7`, `0.9` | --- #### 🎯 所有参数完整示例 ```html <!-- 完整功能配置 - 所有可用参数 --> <div class="netease-mini-player" data-music-file="audio/歌曲.mp3" data-lyric-file="audio/歌曲.lrc" data-autoplay="false" data-position="bottom-right" data-theme="auto" data-size="normal" data-lyric="true" data-embed="false" data-cover-mode="true" data-cover-url="https://example.com/cover.jpg" data-default-minimized="true" data-auto-pause="true" data-idle-opacity="0.3"> </div> ``` #### 📋 参数使用场景组合 **桌面端悬浮播放器**（推荐配置）： ```html <div class="netease-mini-player" data-music-file="audio/song.mp3" data-lyric-file="audio/song.lrc" data-position="bottom-right" data-cover-mode="true" data-default-minimized="true" data-auto-pause="true" data-lyric="true"> </div> ``` **移动端嵌入式播放器**： ```html <div class="netease-mini-player" data-music-file="audio/song.mp3" data-lyric-file="audio/song.lrc" data-embed="true" data-size="compact" data-auto-pause="true" data-lyric="false"> </div> ``` **页面背景音乐播放器**： ```html <div class="netease-mini-player" data-music-file="audio/background.mp3" data-position="top-left" data-default-minimized="true" data-lyric="false" data-auto-pause="true"> </div> ``` **展示型播放器**（带封面和歌词）： ```html <div class="netease-mini-player" data-music-file="audio/demo.mp3" data-lyric-file="audio/demo.lrc" data-theme="light" data-size="normal" data-cover-mode="true" data-cover-url="https://picsum.photos/seed/music/300/300.jpg" data-lyric="true" data-auto-pause="false"> </div> ``` --- ### 🔧 内部配置参数 这些参数在 JavaScript 代码中定义，通常不需要手动修改： | 参数 | 默认值 | 说明 | |------|--------|------| | `idleDelay` | 5000ms | 空闲状态检测延迟 | | `playPauseDebounceDelay` | 100ms | 播放按钮防抖延迟 | | `mouseReturnDelay` | 3000ms | 鼠标在中央区域停留后自动播放延迟 | | `volume` | 0.7 | 默认音量（0-1） | | `cacheExpiry` | 5分钟 | 数据缓存过期时间 | #### 🔧 参数详细说明 ##### 播放器位置 (`data-position`) - `static` - 普通文档流中的播放器（默认） - `top-left` - 左上角悬浮播放器 - `top-right` - 右上角悬浮播放器 - `bottom-left` - 左下角悬浮播放器 - `bottom-right` - 右下角悬浮播放器（推荐） ##### 主题模式 (`data-theme`) - `auto` - 自动检测系统主题（默认） - `light` - 强制亮色主题 - `dark` - 强制暗色主题 ##### 播放器尺寸 (`data-size`) - `compact` - 紧凑模式（默认） - `normal` - 标准模式 - `large` - 大尺寸模式 ##### 嵌入模式 (`data-embed`) - `false` - 独立悬浮播放器（默认） - `true` - 嵌入页面内，适合iframe集成 ##### 圆盘模式 (`data-cover-mode`) - `false` - 普通封面显示（默认） - `true` - 黑胶唱片风格，封面会旋转 ##### 自动暂停 (`data-auto-pause`) - `false` - 页面隐藏时继续播放（默认） - `true` - 页面隐藏时自动暂停 ##### 歌词显示 (`data-lyric`) - `true` - 显示歌词（默认） - `false` - 隐藏歌词显示 ##### 自定义封面 (`data-cover-url`) - 留空 - 使用随机API获取封面 - 填写URL - 使用指定的图片作为封面 #### ⚠️ 参数兼容性说明 | 参数 | 浏览器支持 | 特殊要求 | 推荐用法 | |------|------------|----------|----------| | `data-autoplay` | 现代浏览器 | 需要用户交互 | 设置为 `false` 避免限制 | | `data-embed` | 所有浏览器 | 无 | 集成到iframe时使用 | | `data-auto-pause` | 所有浏览器 | 无 | 移动端建议开启 | | `data-cover-url` | 所有浏览器 | 需要CORS或同域 | 留空使用随机API | | `data-idle-opacity` | 现代浏览器 | CSS3支持 | 最小化模式时使用 | #### 🎯 最佳实践推荐 **桌面端悬浮播放器：** ```html <div class="netease-mini-player" data-music-file="audio/song.mp3" data-lyric-file="audio/song.lrc" data-position="bottom-right" data-cover-mode="true" data-default-minimized="true" data-auto-pause="true"> </div> ``` **移动端嵌入播放器：** ```html <div class="netease-mini-player" data-music-file="audio/song.mp3" data-lyric-file="audio/song.lrc" data-embed="true" data-size="compact" data-auto-pause="true"> </div> ``` **后台音乐播放器：** ```html <div class="netease-mini-player" data-music-file="audio/background.mp3" data-autoplay="false" data-position="top-left" data-theme="auto" data-default-minimized="true" data-lyric="false"> </div> ``` ## 📁 支持的文件格式 ### 🎵 音频文件 - **MP3** - 最常用的音频格式 - **WAV** - 无损音频格式 - **OGG** - 开源音频格式 - **AAC** - 高效音频编码 - **M4A** - Apple音频格式 - 以及其他HTML5 Audio支持的所有格式 ### 📜 歌词文件 - **LRC** - 标准歌词文件格式 - **UTF-8编码** - 支持多语言字符 ## 🎼 LRC歌词格式详解 ### 标准格式 ```lrc [ar:艺术家名] [ti:歌曲标题] [al:专辑名称] [offset:时间偏移量] // 可选，单位毫秒 [00:12.34]第一句歌词 [00:56.78]第二句歌词 [01:23.45]第三句歌词 [01:45.67]器乐演奏部分 ``` ### 时间戳格式 - `[分:秒.毫秒]` - 精确到10毫秒 - `[分:秒:毫秒]` - 精确到毫秒（3位） ## 🎮 JavaScript API ### 获取播放器实例 ```javascript const element = document.querySelector('.netease-mini-player'); const player = element.neteasePlayer; ``` ### 播放控制 ```javascript // 基础控制 await player.play(); // 播放音乐 player.pause(); // 暂停播放 await player.togglePlay(); // 切换播放状态 // 进度控制 player.seekTo(event); // 跳转到指定位置 // 界面控制 player.toggleMinimize(); // 切换最小化状态 player.toggleLyrics(); // 切换歌词显示 ``` ### 事件监听 ```javascript const player = element.neteasePlayer; // 监听播放状态变化 player.element.addEventListener('click', () => { console.log('当前播放状态:', player.isPlaying); }); // 监听进度更新 player.audio.addEventListener('timeupdate', () => { console.log('当前时间:', player.currentTime); }); ``` ## ⚠️ 重要注意事项 ### 🔒 浏览器安全限制 1. **同源策略** - 文件需在同一域名下，或配置CORS 2. **自动播放策略** - 需要用户交互后才能自动播放 3. **本地文件访问** - 直接打开HTML文件可能无法加载本地文件 ### 📂 文件路径说明 - 相对路径基于HTML文件位置 - 推荐使用绝对路径避免混淆 - 确保文件路径大小写匹配 ### 🌍 编码格式 - **歌词文件** - 必须使用UTF-8编码 - **音频文件** - 支持各种编码格式 ### 🌐 浏览器兼容性 | 浏览器 | 版本要求 | 支持状态 | |--------|----------|----------| | Chrome | 60+ | ✅ 完全支持 | | Firefox | 55+ | ✅ 完全支持 | | Safari | 12+ | ✅ 完全支持 | | Edge | 79+ | ✅ 完全支持 | | IE | 11 | ❌ 不支持 | ## 📂 项目结构 ``` music/ # 项目根目录 ├── index.html # 示例页面 ├── music.css # 样式文件 ├── music.js # 核心JavaScript ├── README.md # 项目文档 └── audio/ # 音频资源目录 ├── 岸边客 (心碎版0.9x)-夏子航（2603）.mp3 └── 岸边客 (心碎版0.9x)-夏子航（2603）.lrc ``` ## 📋 使用示例 ### 示例1: 基础播放器 ```html <div class="netease-mini-player" data-music-file="audio/demo.mp3" data-lyric-file="audio/demo.lrc"> </div> ``` ### 示例2: 悬浮播放器（右下角） ```html <div class="netease-mini-player" data-music-file="audio/song.mp3" data-position="bottom-right" data-cover-mode="true" data-default-minimized="true"> </div> ``` ### 示例3: 嵌入式播放器 ```html <div class="netease-mini-player" data-music-file="audio/background.mp3" data-embed="true" data-autoplay="true"> </div> ``` ### 示例4: 自定义封面 ```html <div class="netease-mini-player" data-music-file="audio/music.mp3" data-cover-url="https://picsum.photos/seed/music/300/300.jpg" data-cover-mode="true"> </div> ``` ### 示例5: 完整功能配置 ```html <div class="netease-mini-player" data-music-file="audio/song.mp3" data-lyric-file="audio/song.lrc" data-autoplay="true" data-position="bottom-right" data-theme="auto" data-size="normal" data-lyric="true" data-cover-mode="true" data-cover-url="https://example.com/cover.jpg" data-default-minimized="true" data-auto-pause="true" data-idle-opacity="0.3"> </div> ``` ### 示例6: 嵌入式完整配置 ```html <div class="netease-mini-player" data-music-file="audio/background.mp3" data-lyric-file="audio/background.lrc" data-embed="true" data-autoplay="false" data-theme="light" data-size="compact" data-lyric="true" data-cover-mode="false" data-auto-pause="true"> </div> ``` ### 示例7: 悬浮播放器（暗色主题） ```html <div class="netease-mini-player" data-music-file="audio/dark-theme-song.mp3" data-position="top-left" data-theme="dark" data-cover-mode="true" data-default-minimized="true" data-lyric="false"> </div> ``` ### 原项目 本项目基于 [NeteaseMiniPlayer v2](https://github.com/ImBHCN/NeteaseMiniPlayer) 进行修改开发。 ```mermaid flowchart TD A[播放器初始化] --> B[检测来源网站] B --> C{来源类型判断} C -->|同域名内部访问| D[直接尝试播放] C -->|外部来源| E[等待用户交互+鼠标检测] C -->|直接访问| E D --> F[播放成功?] F -->|成功| G[✅ 自动播放完成] F -->|失败| H[回退到用户交互模式] H --> I[监听用户交互事件] E --> J[监听用户交互+鼠标移动] J --> K{检测到用户交互?} K -->|是| L[记录交互时间] K -->|否| J L --> M{鼠标在中央区域?} M -->|是| N[开始1.5秒倒计时] M -->|否| J N --> O{倒计时结束检查} O -->|鼠标在页面内+近期有交互| P[执行自动播放] O -->|条件不满足| Q[❌ 取消自动播放] P --> R[播放成功?] R -->|成功| G R -->|失败| S[等待用户明确点击] I --> T{用户交互事件?} T -->|点击/按键| U[直接播放] T -->|否| I U --> G S --> V[监听首次用户交互] V --> W{用户明确点击?} W -->|是| U W -->|否| V style A fill:#e1f5fe style G fill:#c8e6c9 style Q fill:#ffcdd2 style S fill:#fff3cd ```