# TrimTalk

**Repository Path**: wang-qin928/TrimTalk

## Basic Information

- **Project Name**: TrimTalk
- **Description**: 这是一个仓库，用来存储我的项目
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-15
- **Last Updated**: 2026-06-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# PolishVoice

PolishVoice 是一个面向中文单人口播的 Windows 桌面应用。它的目标是把一段原始 `MP3` 自动处理成更干净的成品音频，重点解决：

- 过长停顿
- 明显气口
- 口误后重说
- 相邻重复表达
- 与成品音频同步的中文字幕导出

当前仓库已经有一套可运行的 MVP 骨架：`Flet` 桌面界面、处理流水线、音频校验/解码、转写引擎工厂、决策/渲染/字幕模块的接口与初版实现。

## 当前定位

- 平台：`Windows` 优先
- 交互：`Flet` 单窗口桌面应用
- 输入：单个 `MP3`
- 输出：精剪后的 `MP3` + `SRT`
- 处理方式：默认 `完全离线`
- 审阅方式：卡片 / 列表式片段审阅，不做 DAW 式波形时间线

## 当前骨架包含什么

### UI 流程

应用目前已经拆成四个主视图：

- `HomeView`：首页 / 文件导入
- `ProcessingView`：8 阶段处理进度
- `ReviewView`：结果审阅、筛选、恢复误删片段
- `ExportView`：导出结果、试听与打开输出目录

同时已经有主题系统，内置 4 套视觉主题：

- `graphite_gold`
- `bamboo_breeze`
- `dark_cinema`
- `minimalist_book`

### 后端处理流水线

主流程在 [`src/app/pipeline.py`](src/app/pipeline.py) 中，当前按 8 个阶段编排：

1. 导入与校验音频
2. 语音转写
3. 停顿分析
4. 气口分析
5. 重复 / 重说分析
6. 生成编辑决策
7. 渲染成品音频
8. 生成 SRT 字幕

### 核心模块

- [`src/media/`](src/media/)：MP3 校验、音频信息读取、解码为 WAV
- [`src/transcription/`](src/transcription/)：本地 / 云端转写引擎抽象与工厂
- [`src/analysis/`](src/analysis/)：停顿、气口、重复检测
- [`src/decision/`](src/decision/)：编辑决策生成
- [`src/render/`](src/render/)：根据决策渲染成品 MP3
- [`src/subtitle/`](src/subtitle/)：根据最终保留片段生成 `SRT`
- [`src/ui/`](src/ui/)：Flet 界面、主题、通用组件
- [`src/models.py`](src/models.py)：Pydantic 数据模型
- [`src/config.py`](src/config.py)：本地配置加载与保存

## 目录结构

```text
PolishVoice/
├─ src/
│  ├─ app/
│  ├─ analysis/
│  ├─ decision/
│  ├─ media/
│  ├─ render/
│  ├─ subtitle/
│  ├─ transcription/
│  ├─ ui/
│  ├─ config.py
│  ├─ main.py
│  └─ models.py
├─ requirements.txt
├─ README.md
└─ .trellis/
```

## 运行要求

建议环境：

- Python `3.10+`
- Windows 10 / 11
- `FFmpeg` 已安装并加入系统 `PATH`

说明：

- `ffmpeg` / `ffprobe` 是当前音频校验、解码和导出的必需依赖
- 本地转写默认走 `faster-whisper`
- 如果机器有 NVIDIA GPU，后续可在设置中切换 `cuda`

## 安装

### 1. 创建虚拟环境

```powershell
python -m venv venv
venv\Scripts\activate
```

### 2. 安装依赖

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

### 3. 安装 FFmpeg

请确保下面两个命令可用：

```powershell
ffmpeg -version
ffprobe -version
```

如果不可用，需要先安装 FFmpeg 并加入 `PATH`。

## 启动

```powershell
venv\Scripts\python src\main.py
```

如果虚拟环境已经激活，也可以直接运行：

```powershell
python src\main.py
```

## 当前默认产品边界

当前骨架遵循的 MVP 边界如下：

- 仅支持 `MP3` 输入
- 默认支持 `60 分钟以内`
- 默认大小上限 `100MB`
- 字幕格式固定为 `SRT`
- 默认优先保留“更完整、更自然”的一次
- 主流程完全离线可用

## 配置说明

应用配置会保存在用户目录下：

```text
~/.polishvoice/config.json
```

当前配置项包括：

- Whisper 模型大小：`tiny / small / medium`
- 推理设备：`auto / cpu / cuda`
- 停顿处理模式：`natural / compact`
- 是否启用气口处理
- 是否启用重复处理
- 输出目录
- UI 主题

注意：

- 代码里目前保留了云端 ASR 相关字段与工厂分支，便于未来扩展
- 但本项目的 MVP 目标是 `完全离线`，不依赖 API key

## 当前实现状态

这套仓库现在更准确地说是“可运行骨架 + 初版实现”，而不是已经完成的最终产品。

已经有：

- 应用入口和页面切换
- 本地配置持久化
- MP3 校验规则
- FFmpeg 解码与渲染框架
- 处理阶段进度回调
- 审阅与恢复片段的交互骨架
- SRT 生成器框架

仍然需要继续打磨或补全的部分通常包括：

- 检测算法的准确率
- 模型加载与本地资源管理
- 大文件 / 超长音频策略
- 错误处理与边界回归测试
- Windows 打包与分发体验

## 开发建议

如果你要继续开发，建议先从这几个方向切入：

1. 跑通本地 `faster-whisper` 转写与词级时间戳
2. 验证 `silero_vad` 和停顿检测的结果质量
3. 完善 `decision` 层，明确删除 / 压缩 / 建议删除的阈值
4. 用真实样本回归 `render` 与 `subtitle` 的时间轴一致性
5. 最后再打磨审阅体验和导出体验

## 相关文档

- 产品需求文档：[.trellis/tasks/06-15-voice-polish-mvp/prd.md](.trellis/tasks/06-15-voice-polish-mvp/prd.md)
- 架构研究记录：[.trellis/tasks/06-15-voice-polish-mvp/research/architecture-options.md](.trellis/tasks/06-15-voice-polish-mvp/research/architecture-options.md)

## License

当前仓库尚未声明正式许可证。如需开源或商用分发，建议在后续补充明确的 License 文件。