# chrome-music-extension

**Repository Path**: yangxixi_323/chrome-music-extension

## Basic Information

- **Project Name**: chrome-music-extension
- **Description**: 这是一个基于 Chrome Manifest V3 的音乐播放扩展，封装 flac.life 的能力，提供简洁的弹窗解锁、全屏播放器、滚动分页搜索、无封面占位样式与细节打磨的米白主题界面。首次使用在弹窗输入解锁码后即可播放；播放失败（如 410）会有清晰提示。项目采用 MIT 协议，并附带中文免责声明。

- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-04
- **Last Updated**: 2025-11-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: 20251104

## README

# FLAC 音乐播放器 Chrome 扩展

<p align="center">
  <img src="icons/icon128.png" width="64" alt="FLAC 音乐播放器" />
</p>

<p align="center">
  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT" /></a>
  <img src="https://img.shields.io/badge/Chrome-Manifest%20V3-764ba2.svg" alt="Manifest V3" />
  <img src="https://img.shields.io/badge/UI-米白主题-667eea.svg" alt="UI Theme" />
</p>

一个基于 Chrome Manifest V3 的音乐播放扩展，封装 flac.life 的能力，提供简洁的弹窗解锁、全屏播放器、滚动分页搜索、无封面占位样式与细节打磨的米白主题界面。播放失败（如 410）会有清晰提示。项目采用 MIT 协议，并附带中文免责声明。

一个简约大气的 Chrome 浏览器扩展，封装 flac.life 网站，让您可以直接通过插件听音乐，无需复杂操作。

## 功能特性

- 🎵 **全屏播放界面**：在新标签页中打开，固定底部播放器栏，简洁好看
- 🔓 **解锁码管理**：弹窗内校验解锁码（12 小时有效），自动倒计时与过期处理
- 🔎 **搜索体验**：滚动加载分页；首屏骨架屏；翻页底部旋转加载指示
- 🖼️ **封面占位**：无封面不发起请求，使用占位框样式；失败自动降级
- 🪄 **空态水印**：列表为空时显示淡化“♪”水印，融入背景不突兀
- 🧩 **CSP 友好**：移除内联事件处理器，满足严格的 Content Security Policy
- 🎯 **播放失败提示**：资源 410/Gone 等情况，明确提示更换歌曲
- 🎨 **固定 Logo**：首次生成后缓存到本地，后续刷新保持一致

## 安装步骤

### ⚠️ 重要：首先生成图标文件

**如果遇到图标错误，请先完成此步骤！**

1. 在浏览器中打开项目文件夹中的 `generate-icons.html` 文件（双击即可）
2. 页面会自动生成图标预览
3. 点击"下载所有图标"按钮
4. 将下载的三个图标文件（icon16.png, icon48.png, icon128.png）移动到 `chrome-music-extension/icons/` 文件夹中
5. 如果 `icons` 文件夹不存在，请先创建它

### 2. 加载扩展

1. 打开 Chrome 浏览器
2. 访问 `chrome://extensions/`
3. 开启右上角的"开发者模式"
4. 点击"加载已解压的扩展程序"
5. 选择 `chrome-music-extension` 文件夹
6. 扩展安装完成！

## 使用方法

1. **首次使用**：
   - 点击浏览器工具栏中的扩展图标
   - 在弹窗中输入解锁码（从微信公众号【黑话君】获取）
   - 点击"确认解锁"

2. **播放音乐**：
   - 解锁成功后，点击"打开播放器"按钮
   - 在新标签页中享受全屏音乐播放体验

3. **解锁码管理**：
   - 解锁码有效期为12小时
   - 过期后需要重新输入
   - 插件会显示剩余有效时间

## 项目结构

```
chrome-music-extension/
├── manifest.json          # 扩展配置文件
├── popup.html             # 插件弹窗界面
├── popup.css              # 弹窗样式
├── popup.js               # 弹窗逻辑
├── player.html            # 全屏播放页面
├── player.css             # 播放页面样式
├── player.js              # 播放页面逻辑
├── background.js          # 后台服务脚本
├── content.js             # 内容脚本（用于网站交互）
├── logo-generator.js      # Logo 生成器（首次生成后缓存为固定 Logo）
├── generate-icons.html    # 图标生成工具
├── icons/                 # 图标文件夹
│   ├── icon16.png
│   ├── icon48.png
│   └── icon128.png
└── README.md              # 说明文档
```

## 技术栈

- Chrome Extension Manifest V3
- HTML5 / CSS3
- JavaScript (ES6+)
- Canvas API (Logo 生成)
- Chrome Storage API
- Chrome Tabs API
 - Fetch API / DOM API

## 注意事项

- 解锁码需要从微信公众号【黑话君】获取，解锁接口：`https://api.flac.life/unlock/{code}`
- 解锁码有效期为 12 小时，过期需重新输入
- 确保网络连接正常，以便访问 flac.life / api.flac.life
- 播放地址解析失败（如 410/Gone）将提示更换歌曲

## 开发说明

如需修改或扩展功能：

1. **修改样式**：编辑 `popup.css` 和 `player.css`
2. **修改逻辑**：编辑对应的 `.js` 文件
3. **修改配置**：编辑 `manifest.json`
4. **修改 Logo**：编辑 `logo-generator.js` 中的设计代码，可以添加更多随机样式

## 许可证

本项目采用 MIT License 开源协议，详见 `LICENSE` 文件。

## 免责声明

本项目仅用于学习与研究，不对使用结果承担任何责任。详细条款请参阅 `DISCLAIMER.md`。