# distinctAudio

**Repository Path**: ulquiola/distinctAudio

## Basic Information

- **Project Name**: distinctAudio
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-14
- **Last Updated**: 2026-01-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Distinct Audio - 高性能音频去重工具

一款基于本地文件夹的音频去重系统，界面流畅绚丽，支持 Windows、macOS 和 Linux，并具备回收站功能。

## ✨ 核心特性

### 🎯 智能识别
- **双重校验机制**：结合文件名相似度和音频声纹相似度，确保精准去重
- **文件名相似度**：使用 Levenshtein 距离算法对比文件名
- **音频声纹相似度**：提取 MFCC、Chroma 和频谱特征，计算相似度评分

### 📊 质量优先
在识别为重复的文件组中，按以下优先级保留唯一文件：
1. **比特率**：优先保留比特率更高的文件
2. **采样率**：比特率相同时，优先保留采样率更高的文件
3. **文件大小**：上述条件相同时，保留体积较大的文件

### 🛡️ 安全可靠
- **回收站机制**：删除文件时移动到应用专属回收站，防止误删
- **一键恢复**：提供界面按钮，允许用户将文件从回收站还原至原路径
- **跨平台支持**：无缝运行在 Windows、macOS 和 Linux 上

### ⚡ 高效处理
- **并发处理**：使用 Go 的 worker pool 模式并行处理音频指纹提取
- **缓存机制**：对已计算指纹的文件建立本地缓存，避免重复计算
- **增量扫描**：支持仅扫描新增或变更的文件

## 🎨 界面预览

现代化的 Vue 3 + Element Plus 界面，支持：
- 实时进度显示
- 动态波形图展示
- 响应式设计
- 流畅的动画效果

## 📁 项目结构

```
distinctAudio/
├── backend/                 # Go 后端
│   ├── cmd/                # 主程序入口
│   │   └── main.go
│   ├── internal/           # 内部模块
│   │   ├── audio/          # 音频处理
│   │   │   └── fingerprint.go
│   │   ├── dedup/          # 去重逻辑
│   │   │   └── dedup.go
│   │   ├── trash/          # 回收站
│   │   │   └── trash.go
│   │   ├── cache/          # 缓存
│   │   │   └── cache.go
│   │   └── server/         # Web 服务器
│   │       └── server.go
│   └── go.mod
├── frontend/               # Vue 3 前端
│   ├── src/
│   │   ├── api/           # API 接口
│   │   ├── components/    # 组件
│   │   ├── router/        # 路由
│   │   ├── stores/        # 状态管理
│   │   ├── styles/        # 样式
│   │   ├── utils/         # 工具函数
│   │   ├── views/         # 页面
│   │   ├── App.vue
│   │   └── main.js
│   ├── index.html
│   ├── package.json
│   └── vite.config.js
├── build.sh               # Linux/macOS 构建脚本
├── build.bat              # Windows 构建脚本
├── build-cross-platform.sh # 跨平台构建脚本
└── README.md
```

## 🚀 快速开始

### 前置要求

- **Go**：1.21 或更高版本
- **Node.js**：16 或更高版本
- **npm**：7 或更高版本

### 安装依赖

#### 后端依赖
```bash
cd backend
go mod download
```

#### 前端依赖
```bash
cd frontend
npm install
```

### 构建项目

#### Windows
```bash
build.bat
```

#### Linux/macOS
```bash
chmod +x build.sh
./build.sh
```

跨平台构建（需要 Docker）：
```bash
chmod +x build-cross-platform.sh
./build-cross-platform.sh
```

### 运行程序

#### Windows
```bash
cd bin
distinct-audio.exe
```

#### Linux/macOS
```bash
cd bin
./distinct-audio
```

程序启动后，会在浏览器中自动打开 `http://localhost:8080`

如果没有自动打开，请手动在浏览器中访问：`http://localhost:8080`

## 📖 使用指南

### 1. 首页

打开程序后，您会看到首页，包含以下功能：

- **系统状态**：显示当前系统运行状态
- **快速操作**：快速访问主要功能
- **最近扫描记录**：查看最近的扫描历史

### 2. 扫描音频文件

#### 步骤 1：选择扫描路径

1. 点击导航栏的「扫描」或点击首页的「开始扫描」按钮
2. 在扫描页面，点击「选择文件夹」按钮
3. 选择包含音频文件的文件夹路径

#### 步骤 2：配置扫描参数

- **相似度阈值**：设置音频相似度阈值（0.5 - 1.0）
  - 值越高，匹配越严格（推荐：0.85）
  - 值越低，匹配越宽松
- **扫描模式**：
  - **全量扫描**：扫描所有文件，首次使用推荐
  - **增量扫描**：仅扫描新增或变更的文件，速度更快
- **并发线程**：设置并发处理线程数（1 - 16）
  - 线程数越多，处理速度越快
  - 建议根据 CPU 核心数设置

#### 步骤 3：开始扫描

1. 点击「开始扫描」按钮
2. 扫描过程中会实时显示进度：
   - 已处理文件数
   - 总文件数
   - 进度百分比
   - 当前处理的文件名
3. 扫描完成后会自动跳转到结果页面

### 3. 查看扫描结果

扫描结果页面会显示所有检测到的重复音频文件组：

#### 结果列表

每个重复文件组显示：
- **文件名**：音频文件的名称
- **比特率**：音频比特率（如 320kbps）
- **采样率**：音频采样率（如 44100Hz）
- **文件大小**：文件大小（如 5.2MB）
- **时长**：音频时长（如 3:45）
- **相似度**：与最佳文件的相似度百分比

#### 操作按钮

每个文件组提供以下操作：

- **保留最佳**：自动保留质量最高的文件，将其他文件移至回收站
- **保留选中**：手动选择要保留的文件，其他文件移至回收站
- **全部保留**：不删除任何文件
- **预览**：预览音频文件（需要浏览器支持）

#### 批量操作

- **全选/取消全选**：选择或取消选择所有文件
- **批量删除**：将选中的文件移至回收站
- **批量保留**：保留选中的文件，删除未选中的文件

### 4. 回收站管理

点击导航栏的「回收站」可以查看所有被删除的文件：

#### 回收站功能

- **查看文件列表**：显示所有被删除的文件及其原路径、删除时间、文件大小
- **恢复文件**：点击「恢复」按钮将文件从回收站还原至原路径
  - 如果原路径已存在同名文件，会提示覆盖或取消
- **永久删除**：点击「永久删除」按钮彻底删除文件（不可恢复）
  - ⚠️ 此操作不可逆，请谨慎使用
- **清空回收站**：点击「清空回收站」按钮删除所有回收站中的文件
  - ⚠️ 此操作不可逆，请谨慎使用

#### 批量操作

- **批量恢复**：选中多个文件后，点击「批量恢复」
- **批量删除**：选中多个文件后，点击「批量删除」

### 5. 高级设置

#### 扫描设置

- 默认相似度阈值：0.85
- 默认并发线程数：4
- 默认扫描模式：全量扫描

#### 缓存管理

- 程序会自动缓存已计算的音频指纹
- 缓存文件存储在系统临时目录
- 清空缓存：在设置中点击「清空缓存」
  - ⚠️ 清空缓存后，下次扫描需要重新计算所有文件的指纹

#### 日志查看

- 程序运行日志存储在日志文件中
- 可以在设置中查看或导出日志

## 🔧 配置

### 环境变量

- `PORT`：服务器端口（默认：8080）
  
  修改端口：
  ```bash
  # Windows
  set PORT=9000
  distinct-audio.exe
  
  # Linux/macOS
  PORT=9000 ./distinct-audio
  ```

### 配置文件

配置文件位于：
- **Windows**：`%APPDATA%\distinct-audio\config.json`
- **Linux**：`~/.config/distinct-audio/config.json`
- **macOS**：`~/Library/Application Support/distinct-audio/config.json`

配置文件示例：
```json
{
  "port": 8080,
  "defaultSimilarityThreshold": 0.85,
  "defaultWorkers": 4,
  "defaultIncremental": false,
  "cacheEnabled": true,
  "cacheDir": "",
  "logLevel": "info"
}
```

### 扫描设置

在扫描页面可以配置：
- **扫描路径**：选择要扫描的文件夹
- **相似度阈值**：设置音频相似度阈值（0.5 - 1.0）
- **扫描模式**：全量扫描或增量扫描
- **并发线程**：设置并发处理线程数（1 - 16）

## 📚 API 文档

### 扫描
```http
POST /api/scan
Content-Type: application/json

{
  "scanPath": "/path/to/audio",
  "similarityThreshold": 0.85,
  "incremental": false,
  "workers": 4
}
```

### WebSocket
```
ws://localhost:8080/ws
```

消息类型：
- `scan_started`：扫描开始
- `progress`：进度更新
- `scan_completed`：扫描完成
- `scan_error`：扫描错误
- `error`：错误信息

### 回收站
```http
GET /api/trash                    # 获取回收站内容
POST /api/trash/empty             # 清空回收站
POST /api/restore                 # 恢复文件
POST /api/delete                  # 永久删除文件
```

## 🛠️ 技术栈

### 后端
- **语言**：Go 1.21+
- **Web 框架**：Gin
- **WebSocket**：Gorilla WebSocket
- **音频处理**：gonum (DSP 运算)
- **缓存**：JSON 文件缓存

### 前端
- **框架**：Vue 3
- **构建工具**：Vite
- **UI 库**：Element Plus
- **状态管理**：Pinia
- **路由**：Vue Router
- **HTTP 客户端**：Axios

## 📝 支持的音频格式

- MP3
- WAV
- FLAC（暂不支持，计划中）
- M4A（暂不支持，计划中）
- OGG（暂不支持，计划中）
- AAC（暂不支持，计划中）

## 🔒 数据安全

- 所有处理均在本地进行，不会上传到云端
- 删除的文件会先移动到回收站，可随时恢复
- 缓存数据存储在本地应用数据目录
- 不收集任何用户数据

## 🌍 跨平台支持

- ✅ Windows (amd64, arm64)
- ✅ macOS (amd64, arm64/Apple Silicon)
- ✅ Linux (amd64, arm64)

## ❓ 常见问题

### Q: 扫描速度很慢怎么办？

A: 可以尝试以下方法：
1. 增加并发线程数（在扫描设置中调整）
2. 使用增量扫描模式
3. 关闭其他占用 CPU 的程序

### Q: 为什么有些文件没有被识别为重复？

A: 可能的原因：
1. 相似度阈值设置过高，尝试降低阈值
2. 音频质量差异较大
3. 音频内容确实不同

### Q: 如何提高识别准确率？

A: 建议：
1. 使用较高的相似度阈值（0.85-0.9）
2. 确保音频文件质量良好
3. 对于同一首歌的不同版本，可能需要手动确认

### Q: 回收站文件能保存多久？

A: 回收站文件会一直保存，直到您：
1. 手动恢复文件
2. 永久删除文件
3. 清空回收站

### Q: 程序崩溃了怎么办？

A: 
1. 重新启动程序
2. 检查日志文件了解错误原因
3. 如果问题持续，请提交 Issue

### Q: 可以扫描网络驱动器吗？

A: 可以，但扫描速度可能会较慢，取决于网络速度。建议将文件先复制到本地再扫描。

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

### 开发指南

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request

## 📄 许可证

MIT License

## 📧 联系方式

如有问题或建议，请提交 Issue。

---

**Distinct Audio** - 让你的音乐库井井有条！🎵