# music-tag-editor

**Repository Path**: phchen0769/music-tag-editor

## Basic Information

- **Project Name**: music-tag-editor
- **Description**: 音乐信息编辑工具，可以批量匹配音乐，批量应用。
- **Primary Language**: TypeScript
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-09
- **Last Updated**: 2026-07-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 免费音频标签编辑器

在线编辑常见音频格式的标题、歌手、专辑、年份、流派和专辑封面，所有文件处理均在浏览器内完成，无需上传到服务器。

## 功能特性

- **标签编辑** — 支持编辑标题、歌手、专辑、年份、流派、曲目、碟片、作曲者等字段
- **专辑封面** — 支持查看、替换和删除专辑封面图片
- **MusicBrainz 匹配** — 一键搜索 MusicBrainz 数据库，自动匹配歌曲元数据
- **批量编辑** — 支持同时上传多首歌曲，逐个匹配和编辑标签
- **多格式支持** — 支持读取 MP3、FLAC、WAV、AIFF、OGG、M4A、MP4、AAC、OPUS、WMA、APE、WavPack、MPC、TTA、Matroska 等格式
- **格式写入** — 支持导出 MP3、FLAC、WAV、OGG、M4A、MP4、OPUS、Matroska 格式
- **隐私安全** — 基于 WebAssembly，所有音频处理均在浏览器本地完成，文件不会上传

## 技术栈

| 技术 | 用途 |
| --- | --- |
| Vue 3 + TypeScript | 前端框架 |
| Vite | 构建工具 |
| Pinia | 状态管理 |
| taglib-wasm | 音频标签读写（WebAssembly） |
| @unimusic/chromaprint | 音频指纹识别 |
| MusicBrainz API | 在线元数据搜索 |
| lucide-vue-next | 图标库 |

## 本地开发

```bash
# 安装依赖
npm install

# 启动开发服务器
npm run dev

# 浏览器访问 http://localhost:5173
```

## 构建部署

```bash
# 构建生产版本
npm run build

# 产物位于 dist/ 目录，可部署到任意静态服务器
```

## Docker 部署

项目包含以下 Docker 相关文件：

| 文件 | 说明 |
| --- | --- |
| `Dockerfile` | 多阶段构建：Node.js 编译 + Nginx 运行 |
| `docker-compose.yml` | 服务编排，一键启动 |
| `nginx.conf` | Nginx 配置，支持 SPA 路由与静态资源缓存 |
| `.dockerignore` | 排除无关文件，加速构建 |

### Dockerfile 构建流程

```
┌──────────────────────┐     ┌──────────────────────┐
│  Stage 1: builder     │     │  Stage 2: runtime     │
│  node:20-alpine       │     │  nginx:stable-alpine  │
│                       │     │                       │
│  npm ci               │     │  COPY dist/ → html/   │
│  npm run build        │ ──→ │  COPY nginx.conf      │
│  产出 dist/           │     │  EXPOSE 80            │
└──────────────────────┘     └──────────────────────┘
```

- **Stage 1** 使用 `node:20-alpine` 安装依赖并执行 `npm run build`，产出 `dist/` 静态文件
- **Stage 2** 使用 `nginx:stable-alpine`，仅拷贝构建产物和 Nginx 配置，最终镜像体积极小
- `nginx.conf` 中 `try_files $uri $uri/ /index.html` 确保 Vue Router（history 模式）刷新不 404，静态资源设置 1 年强缓存

### 使用方式

```bash
# 克隆项目后，在项目根目录执行
docker compose up -d

# 查看运行状态
docker compose ps

# 查看日志
docker compose logs -f

# 停止并移除容器
docker compose down
```

启动后浏览器访问 **http://localhost:8080**。

如需修改端口，编辑 `docker-compose.yml` 中的 `ports` 映射，例如改为 `"3000:80"` 则访问 `http://localhost:3000`。

## 项目结构

```
src/
├── components/       # Vue 组件
│   ├── AppSidebar.vue   # 侧边栏（文件列表）
│   ├── BatchPage.vue    # 批量编辑页面
│   ├── CoverSection.vue # 封面编辑区域
│   ├── HomePage.vue     # 首页（上传入口）
│   ├── MatchSection.vue # MusicBrainz 匹配结果
│   ├── TagFields.vue    # 标签字段编辑
│   └── UploadPanel.vue  # 文件上传面板
├── formats/          # 格式处理
│   ├── flac.ts         # FLAC 标签写入
│   └── ogg.ts          # OGG 标签写入
├── stores/           # Pinia 状态管理
│   └── editor.ts       # 编辑器核心状态
├── App.vue           # 根组件
├── acoustid.ts       # AcoustID 指纹识别
├── audio-metadata.ts # 音频元数据读写
├── id3.ts            # ID3 标签解析与生成
├── musicbrainz.ts    # MusicBrainz API 封装
├── main.ts           # 应用入口
└── style.css         # 全局样式
```

## 浏览器兼容性

需要支持 WebAssembly 的现代浏览器：

- Chrome / Edge ≥ 80
- Firefox ≥ 79
- Safari ≥ 15

## 开源协议

MIT