From 4ad7a8d4330f34c400babdc5834f3e325fe2915f Mon Sep 17 00:00:00 2001
From: Misaka_Company <pengqiangqiang0@gmail.com>
Date: Wed, 27 May 2026 18:14:48 +0800
Subject: [PATCH] Add comprehensive README with setup guide and usage
 documentation

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 README.md | 102 +++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 101 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 5d48814..385f5b9 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,103 @@
 # AudioScribe
 
-基于大模型 API 的录音转文字工具。
+基于火山引擎大模型录音文件识别 API 的录音转文字工具，支持说话人聚类分离。
+
+## 功能特性
+
+- 调用火山引擎大模型 ASR API 进行语音转写
+- 支持说话人聚类分离（自动识别不同说话人）
+- 自动生成 Markdown 格式的转写文档（按时间线排列，标注说话人）
+- 同时输出原始 JSON 数据
+- 支持 mp3、m4a 等常见音频格式
+
+## 项目结构
+
+```
+AudioScribe/
+├── transcribe_legacy.py   # 主脚本（APP ID + Access Token 认证）
+├── transcribe_all.py      # 备用脚本（API Key 认证）
+├── requirements.txt       # Python 依赖
+├── .env                   # 环境变量配置（需自行创建）
+├── tools/                 # 工具（ffmpeg 等）
+├── docs/                  # API 文档
+└── output/                # 转写结果输出目录
+```
+
+## 快速开始
+
+### 1. 安装依赖
+
+```bash
+python -m venv .venv
+.venv\Scripts\activate      # Windows
+# source .venv/bin/activate  # Linux/macOS
+pip install -r requirements.txt
+```
+
+### 2. 配置环境变量
+
+在项目根目录创建 `.env` 文件：
+
+```env
+# 火山引擎 API 配置（旧版控制台 - APP ID + Access Token）
+X_API_APP_KEY=你的APP_ID
+X_API_ACCESS_KEY=你的Access_Token
+X_API_RESOURCE_ID=volc.seedasr.auc
+
+# S3 兼容对象存储配置（用于上传音频文件）
+S3_ENDPOINT=https://your-s3-endpoint
+S3_ACCESS_KEY_ID=your_access_key
+S3_SECRET_ACCESS_KEY=your_secret_key
+S3_BUCKET=audioscribe
+```
+
+`X_API_RESOURCE_ID` 可选值：
+- `volc.bigasr.auc` — 大模型 ASR 1.0
+- `volc.seedasr.auc` — 大模型 ASR 2.0（推荐，需旧版控制台认证）
+
+### 3. 运行转写
+
+```bash
+python transcribe_legacy.py "音频文件.mp3"
+```
+
+输出文件将保存到 `output/` 目录：
+- `{音频名}_转写结果.json` — 原始 API 返回数据
+- `{音频名}_转写结果.md` — Markdown 格式转写文档
+
+## 两个脚本的区别
+
+| | `transcribe_legacy.py` | `transcribe_all.py` |
+|---|---|---|
+| 认证方式 | APP ID + Access Token（旧版控制台） | API Key（新版控制台） |
+| 对象存储 | S3 兼容（boto3） | MinIO |
+| 支持模型 | bigasr / seedasr | 仅 bigasr |
+| 输出目录 | `output/` | 项目根目录 |
+
+## 输出格式示例
+
+Markdown 文档按时间线排列，标注说话人：
+
+```markdown
+# 转写结果
+
+**源文件**: 示例.mp3
+**音频时长**: 09:04.61
+**说话人数量**: 5 人
+**分句数量**: 183
+
+---
+
+## 按时间线
+
+- **00:00.54 - 00:01.54** **说话人1** 已经检验了啊。
+- **00:02.46 - 00:03.38** **说话人2** 来，你大概说一下嘛。
+- **00:04.38 - 00:11.34** **说话人3** 就是计时，从比如说我们是5点钟下班儿……
+```
+
+## 依赖
+
+- Python 3.8+
+- requests
+- python-dotenv
+- boto3