# filename-to-music-tags

> 专业的音乐文件标签提取和写入工具。从音乐文件名自动提取歌曲名、艺术家信息，并写入到ID3标签的标题(TIT2)、艺术家(TPE1)和唱片集(TALB)字段中。支持MP3、WMA、FLAC等多种音频格式，使用UTF-8编码确保中文显示正常。适用于整理音乐库、修复标签信息、批量处理音乐文件元数据。

- Author: sanwenjing
- Repository: sanwenjing/opencode
- Version: 20260204091223
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/sanwenjing/opencode
- Web: https://mule.run/skillshub/@@sanwenjing/opencode~filename-to-music-tags:20260204091223

---

---
name: filename-to-music-tags
description: 专业的音乐文件标签提取和写入工具。从音乐文件名自动提取歌曲名、艺术家信息，并写入到ID3标签的标题(TIT2)、艺术家(TPE1)和唱片集(TALB)字段中。支持MP3、WMA、FLAC等多种音频格式，使用UTF-8编码确保中文显示正常。适用于整理音乐库、修复标签信息、批量处理音乐文件元数据。
license: 专有。LICENSE.txt 包含完整条款
---

## Filename To Music Tags - 音乐文件名标签提取工具

### 描述
这是一个专业的音乐文件元数据处理工具，能够自动从音乐文件名中提取信息并写入标准ID3标签。

### 目录结构
```
filename-to-music-tags/
├── SKILL.md                           # 技能主配置文件
└── scripts/                           # 脚本目录
    └── auto_tag_from_filename.py     # 一键自动标签写入脚本（位于 scripts/auto_tag_from_filename.py）
```

### 脚本索引
**编码声明**: 本技能所有脚本默认使用UTF-8编码，Windows系统下已配置UTF-8控制台输出。

| 脚本名称 | 脚本路径 | 功能描述 | 调用方式 |
|---------|---------|---------|---------|
| auto_tag_from_filename.py | scripts/auto_tag_from_filename.py | 一键完成标题、艺术家、唱片集全部标签的自动写入 | `python scripts/auto_tag_from_filename.py` |

### 核心功能

#### 1. 文件名解析
- 智能识别文件名中的分隔符（" - " 或 "-"）
- 提取歌曲名称和艺术家信息
- 支持中英文混合文件名

#### 2. 标签写入
- **标题(TIT2)**: 写入歌曲名称
- **艺术家(TPE1)**: 写入歌手/艺术家名称
- **唱片集(TALB)**: 写入完整文件名（不含扩展名）

#### 3. 编码支持
- 使用UTF-8/UTF-16编码写入标签
- 完美支持中文、日文、韩文等多语言
- 兼容所有主流音乐播放器

### 支持的音频格式

- MP3 (ID3v2.3/ID3v2.4)
- WMA (Windows Media Audio)
- FLAC (Free Lossless Audio Codec)
- M4A/AAC (MPEG-4 Audio)
- OGG (Ogg Vorbis)
- WAV (波形音频)

### 文件名格式支持

#### 标准格式
```
歌曲名 - 歌手.mp3
例如: "123 我爱你 - 新乐尘符.mp3"
提取结果:
- 标题: "123 我爱你"
- 艺术家: "新乐尘符"
- 唱片集: "123 我爱你 - 新乐尘符"
```

#### 其他格式
```
歌曲名-歌手.mp3
歌手 - 歌曲名.mp3
纯歌曲名.mp3
```

### 使用方法

#### 一键完成全部标签写入
```bash
# 确保在包含音乐文件的目录中运行
python scripts/auto_tag_from_filename.py
```
功能说明：
- 自动解析文件名中的 " - " 分隔符
- 同时写入标题(TIT2)、艺术家(TPE1)、唱片集(TALB)
- 批量处理整个音乐文件夹

### 使用流程

1. **准备音乐文件**
   - 确保文件名格式为: "歌曲名 - 歌手.mp3"
   - 将音乐文件放在同一目录

2. **运行脚本**
   ```bash
   python scripts/auto_tag_from_filename.py
   ```
   - 脚本会自动检测当前目录的所有音频文件
   - 显示前3个文件的解析示例
   - 确认后开始批量处理

3. **验证结果**
   - 在音乐播放器中查看属性
   - 确认标题、艺术家、专辑显示正确

### 输出示例

```
[  1/269] 123 我爱你 - 新乐尘符.mp3
      解析: 标题=123 我爱你, 艺术家=新乐尘符
      ✓ 标题: 123 我爱你; 艺术家: 新乐尘符
      ✓ 专辑: 123 我爱你 - 新乐尘符

[  2/269] 黄昏-周传雄.mp3
      解析: 标题=黄昏, 艺术家=周传雄
      ✓ 标题: 黄昏; 艺术家: 周传雄
      ✓ 专辑: 黄昏-周传雄
```

### 技术优势

- **智能解析**: 自动识别多种分隔符模式
- **批量处理**: 一次处理整个文件夹
- **编码安全**: 使用UTF-8/UTF-16编码，无乱码
- **格式兼容**: 支持主流音频格式
- **非破坏性**: 安全写入，不损坏音频数据

### 适用场景

1. **音乐库整理**: 从网络下载的音乐文件名规范但标签缺失
2. **标签修复**: 批量补充或修复ID3标签信息
3. **设备兼容**: 确保车载音响、MP3播放器正确显示中文
4. **归档管理**: 统一音乐文件元数据标准

### 注意事项

- 处理前建议备份原始文件
- 确保文件名格式正确（包含分隔符" - "）
- 部分特殊格式文件可能无法处理
- WMA文件使用专门的ASF标签格式
- 运行脚本前请确保在包含音乐文件的目录中

### 依赖要求

- Python 3.6+
- mutagen 库 (`pip install mutagen`)

### 兼容性

- Windows 7/8/10/11
- macOS
- Linux

### 类别
音乐工具、文件管理、元数据处理