# Audio Toolbox

**Repository Path**: chntamap/audio-toolbox

## Basic Information

- **Project Name**: Audio Toolbox
- **Description**: 音频工具箱 

包含：
1. MP3信息查看
2. 批量MP3压缩

该项目由deepseek辅助编写
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-01
- **Last Updated**: 2025-12-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MP3音频处理工具集

本项目包含两个独立的MP3音频处理工具：

1. **MP3文件体积分析器** - 分析MP3文件的体积相关参数
2. **MP3批量压缩转换器** - 批量压缩转换MP3文件

## 目录

- [项目概述](#项目概述)
- [工具1：MP3文件体积分析器](#工具1mp3文件体积分析器)
  - [功能特性](#功能特性)
  - [安装依赖](#安装依赖)
  - [使用方法](#使用方法)
  - [输出示例](#输出示例)
- [工具2：MP3批量压缩转换器](#工具2mp3批量压缩转换器)
  - [功能特点](#功能特点)
  - [系统要求](#系统要求)
  - [FFmpeg安装指南](#ffmpeg安装指南)
  - [安装依赖](#安装依赖-1)
  - [使用方法](#使用方法-1)
  - [参数说明](#参数说明)
  - [输出示例](#输出示例-1)
  - [故障排除](#故障排除)
- [项目文件结构](#项目文件结构)
- [注意事项](#注意事项)

## 项目概述

这两个工具可以单独使用，也可以配合使用：

1. **先分析**：使用体积分析器了解当前MP3文件的参数
2. **再压缩**：根据分析结果，使用批量压缩器进行压缩转换

## 工具1：MP3文件体积分析器

### 功能特性

- ✅ 分析MP3文件的体积相关参数
- ✅ 使用mutagen库，稳定可靠
- ✅ 仅关注核心体积参数，无多余功能
- ✅ 简洁的命令行界面

### 支持的参数

#### 核心体积参数：
1. **比特率 (Bitrate)** - 直接影响文件大小
2. **采样率 (Sample Rate)** - 影响音频质量基础
3. **声道数 (Channels)** - 影响编码效率
4. **时长 (Duration)** - 直接影响文件大小

#### 体积计算：
- 实际文件大小
- 理论音频数据大小
- 元数据大小
- 实际/理论比例

### 安装依赖

```bash
pip install -r requirements.txt
```

或者直接安装mutagen：

```bash
pip install mutagen
```

### 使用方法

#### 基本用法：
```bash
python mp3_volume_analyzer.py music.mp3
```

#### 示例：
```bash
python mp3_volume_analyzer.py "D:\Music\song.mp3"
```

### 输出示例

```
MP3文件体积分析报告
================================
文件: music.mp3
文件大小: 5.21 MB

音频技术参数（体积相关）:
• 比特率: 128.0 kbps
• 采样率: 44.1 kHz
• 声道数: 2 (Stereo)
• 时长: 3:45 (225.0秒)

体积分析:
• 实际文件大小: 5.21 MB
• 理论音频数据大小: 3.60 MB
• 元数据大小: 1.61 MB
• 实际/理论比例: 144.7%
================================
```

## 工具2：MP3批量压缩转换器

### 功能特点

- **批量处理**：支持处理大量MP3文件（约100个）
- **参数调整**：可配置比特率、采样率、声道数
- **简洁稳定**：最小化依赖，健壮的错误处理
- **进度显示**：实时显示处理进度和统计信息
- **默认配置**：32kbps, 22.05kHz, 立体声（符合用户需求）

### 系统要求

1. **Python 3.6+**
2. **ffmpeg**（必需，需要单独安装）

**重要：必须先安装ffmpeg才能使用本程序！**

### FFmpeg安装指南

#### Windows 系统

##### 方法1：下载预编译版本（推荐）
1. 访问 FFmpeg 官网：https://ffmpeg.org/download.html
2. 点击 "Windows builds from gyan.dev"
3. 下载最新版本（如：ffmpeg-release-full.7z）
4. 解压到 `C:\ffmpeg` 目录
5. 将 `C:\ffmpeg\bin` 添加到系统PATH

##### 方法2：使用包管理器（如果有）
```bash
# 如果使用 Chocolatey
choco install ffmpeg

# 如果使用 Scoop
scoop install ffmpeg
```

#### macOS 系统
```bash
# 使用 Homebrew（推荐）
brew install ffmpeg
```

#### Linux 系统
```bash
# Ubuntu/Debian
sudo apt-get update
sudo apt-get install ffmpeg
```

#### 验证安装
安装完成后，打开命令行验证：
```bash
ffmpeg -version
```

### 安装依赖

```bash
pip install -r requirements.txt
```

依赖包括：
- `pydub>=0.25.1` - 音频处理库
- `mutagen>=1.47.0` - MP3元数据读取

### 使用方法

#### 基本用法（使用默认配置）
```bash
python mp3_batch_compressor.py 输入文件夹 输出文件夹
```

默认配置：
- 比特率：32 kbps
- 采样率：22050 Hz (22.05 kHz)
- 声道数：2 (立体声)
- 输出文件后缀：`_compressed`

#### 指定参数
```bash
# 指定比特率和采样率
python mp3_batch_compressor.py input_folder output_folder \
    --bitrate 64k \
    --samplerate 44100

# 使用单声道
python mp3_batch_compressor.py input_folder output_folder --channels 1

# 自定义输出文件后缀
python mp3_batch_compressor.py input_folder output_folder --suffix "_low_quality"

# 覆盖已存在的输出文件
python mp3_batch_compressor.py input_folder output_folder --overwrite
```

### 参数说明

| 参数 | 可选值 | 默认值 | 说明 |
|------|--------|--------|------|
| `--bitrate` | `32k`, `64k`, `128k`, `192k`, `256k`, `320k` | `32k` | 目标比特率 |
| `--samplerate` | `11025`, `22050`, `44100`, `48000` | `22050` | 目标采样率(Hz) |
| `--channels` | `1`, `2` | `2` | 目标声道数 |
| `--suffix` | 任意字符串 | `_compressed` | 输出文件后缀 |
| `--overwrite` | 无参数 | `False` | 覆盖已存在的输出文件 |

### 输出示例

```
MP3批量压缩转换器 - 简洁稳定版
============================================================
输入目录: ./music
输出目录: ./compressed
压缩配置: 32k, 22050Hz, 2声道

正在扫描目录: ./music
找到 5 个MP3文件

开始批量压缩处理...
配置: 32k, 22050Hz, 2声道
------------------------------------------------------------

[1/5] 处理: song1.mp3
  正在加载: song1.mp3
  原始: 44100Hz, 2声道, 3:45
  目标: 22050Hz, 2声道, 32k
  调整采样率: 44100Hz → 22050Hz
  正在导出到: song1_compressed.mp3
  压缩完成: 5.21 MB → 1.30 MB (减少 3.91 MB, 75.0%)

批量压缩处理完成
============================================================
处理统计:
  • 总文件数: 5
  • 成功: 5
  • 失败: 0
  • 原始总大小: 25.43 MB
  • 压缩后总大小: 6.36 MB
  • 总体积减少: 19.07 MB (75.0%)
  • 总处理时间: 12.5秒
  • 平均处理时间: 2.50秒/文件
============================================================

处理完成！
```

### 故障排除

#### 问题1: "Couldn't find ffmpeg" 警告
**解决方案**：
1. 确认ffmpeg已正确安装
2. 重启命令行窗口
3. 或将ffmpeg.exe放在项目目录下

#### 问题2: 所有文件处理失败
**可能原因**：
1. ffmpeg未正确安装
2. 文件权限问题
3. 磁盘空间不足

#### 问题3: 中文文件名处理失败
**解决方案**：
1. 确保系统编码支持中文
2. 避免使用特殊字符

## 项目文件结构

```
项目目录/
├── mp3_volume_analyzer.py      # MP3文件体积分析器
├── mp3_batch_compressor.py     # MP3批量压缩转换器
├── requirements.txt            # 依赖文件
├── test_ffmpeg.py             # FFmpeg测试脚本（可选）
├── README_INTEGRATED.md       # 本整合说明文档
├── README.md                  # 原始体积分析器说明
├── README_batch_compressor.md # 原始批量压缩器说明
└── INSTALL_FFMPEG.md          # FFmpeg安装指南
```

## 注意事项

### 通用注意事项
1. **Python版本**：需要Python 3.6或更高版本
2. **文件编码**：支持中文文件名，但避免使用特殊字符
3. **文件权限**：确保有读取输入文件和写入输出目录的权限

### 体积分析器注意事项
1. **依赖简单**：仅需mutagen库，安装简单
2. **单一功能**：专注于体积参数分析，无多余功能
3. **快速分析**：分析速度快，几乎无等待时间

### 批量压缩器注意事项
1. **ffmpeg必需**：必须先安装ffmpeg才能使用
2. **音质损失**：压缩会降低音质，请根据需求选择合适的参数
3. **处理时间**：大文件或大量文件可能需要较长时间
4. **磁盘空间**：确保输出目录有足够的空间
5. **备份建议**：建议先备份原始文件，再执行批量压缩

### 压缩效果估算
使用默认配置（32kbps, 22.05kHz, 立体声）：
- 原始256kbps → 体积减少约87.5%
- 原始128kbps → 体积减少约75.0%
- 原始64kbps → 体积减少约50.0%

## 使用流程建议

### 最佳实践流程：
1. **分析阶段**：使用体积分析器了解当前MP3文件的参数
   ```bash
   python mp3_volume_analyzer.py sample.mp3
   ```

2. **测试阶段**：使用测试脚本验证ffmpeg安装
   ```bash
   python test_ffmpeg.py
   ```

3. **小规模测试**：先处理少量文件测试效果
   ```bash
   # 创建测试文件夹，放入几个MP3文件
   python mp3_batch_compressor.py test_input test_output
   ```

4. **批量处理**：确认效果满意后，处理全部文件
   ```bash
   python mp3_batch_compressor.py "D:\File\MP3" "D:\File\MP3-out"
   ```

5. **验证结果**：使用体积分析器对比压缩前后的文件
   ```bash
   python mp3_volume_analyzer.py "D:\File\MP3-out\song1_compressed.mp3"
   ```

## 技术支持

如果遇到问题：
1. 首先运行 `python test_ffmpeg.py` 检查环境
2. 确保ffmpeg已正确安装并添加到PATH
3. 检查文件权限和磁盘空间
4. 查看程序输出的详细错误信息

## 许可证

自由使用，无特殊限制。