iflytek-asr

# 讯飞语音转文字 (iFlytek ASR)

使用科大讯飞语音识别 API 将音频文件转换为文本，支持中文方言识别。

## 功能特性

- ✅ 支持多种音频格式：mp3, wav, pcm, mp4, m4a, aac, ogg, flac, speex, opus, wma
- ✅ 支持 YouTube 视频下载并转文本
- ✅ 文件大小限制：≤500MB
- ✅ 时长限制：≤5小时
- ✅ 自动识别中文方言
- ✅ 自动添加标点符号

## 前置要求

### 1. 获取讯飞 API 凭证

1. 访问 [科大讯飞开放平台](https://www.xfyun.cn)
2. 注册/登录账号
3. 创建应用，选择「语音转写」服务
4. 获取凭证：
   - `XFYUN_APP_ID`
   - `XFYUN_ACCESS_KEY_ID`
   - `XFYUN_ACCESS_KEY_SECRET`

### 2. 配置环境变量

在 skill 目录下创建 `.env` 文件：

```env
XFYUN_APP_ID=your_app_id
XFYUN_ACCESS_KEY_ID=your_access_key_id
XFYUN_ACCESS_KEY_SECRET=your_access_key_secret
```

### 3. 安装依赖

```bash
pip3 install yt-dlp requests python-dotenv
```

## 使用方法

### 转录本地音频

```bash
python3 scripts/speech_to_text.py <音频文件路径> [输出文本路径]
```

示例：
```bash
python3 scripts/speech_to_text.py meeting.mp3
python3 scripts/speech_to_text.py recording.wav output.txt
```

### YouTube 视频转文字

```bash
python3 scripts/download_and_transcribe.py "YOUTUBE_URL" [保存目录]
```

示例：
```bash
python3 scripts/download_and_transcribe.py "https://www.youtube.com/watch?v=VIDEO_ID" ~/Downloads
```

### 仅下载 YouTube 音频

```bash
python3 scripts/download_audio.py "YOUTUBE_URL" [保存目录]
```

## 对比：讯飞 vs Whisper

| 特性 | 讯飞 ASR | Whisper |
|------|---------|---------|
| 成本 | API 配额（有免费额度） | 免费 |
| 离线 | ❌ 需要网络 | ✅ 本地运行 |
| 速度 | ⭐⭐⭐⭐⭐ 快 | ⭐⭐⭐ 较慢 |
| 中文准确率 | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ |
| 标点符号 | ✅ 自动添加 | ❌ 无 |
| 方言支持 | ✅ 支持 | ⭐⭐ 一般 |

**建议：**
- 重要会议/采访 → 讯飞（准确率高、有标点）
- 日常语音消息 → Whisper（免费、无限制）

## API 限制

讯飞免费版：
- 每日调用次数：500 次
- 单次文件大小：≤500MB
- 单次时长：≤5小时

## 文件结构

```
iflytek-asr/
├── SKILL.md           # 本文档
├── README.md          # 详细说明
├── QUICKSTART.md      # 快速开始
├── .env.exa...

# 讯飞语音转文本 Skill

使用科大讯飞 API 将音频文件转换为文本，支持中文方言识别。

## 功能特性

- ✅ 支持多种音频格式：mp3, wav, pcm, mp4, m4a, aac, ogg, flac, speex, opus, wma
- ✅ 支持 YouTube 视频下载并转文本
- ✅ 文件大小限制：≤500MB
- ✅ 时长限制：≤5小时
- ✅ 自动识别中文方言

## 安装步骤

### 1. 安装依赖

```bash
pip3 install yt-dlp requests python-dotenv
```

### 2. 获取讯飞 API 凭证

1. 访问 [科大讯飞开放平台](https://www.xfyun.cn)
2. 注册/登录账号
3. 创建应用，选择"语音识别"服务
4. 获取以下凭证：
   - `XFYUN_APP_ID`
   - `XFYUN_ACCESS_KEY_ID`
   - `XFYUN_ACCESS_KEY_SECRET`

### 3. 配置凭证

复制 `.env.example` 为 `.env` 并填入你的凭证：

```bash
cp .env.example .env
# 然后编辑 .env 文件，填入你的凭证
```

`.env` 文件内容示例：
```env
XFYUN_APP_ID=your_app_id_here
XFYUN_ACCESS_KEY_ID=your_access_key_id_here
XFYUN_ACCESS_KEY_SECRET=your_access_key_secret_here
```

⚠️ **注意**：`.env` 文件包含敏感信息，不要提交到 Git 仓库！

## 使用方法

### 方式 1：转录本地音频文件

```bash
python3 scripts/speech_to_text.py <音频文件路径> [输出文本路径]
```

**示例：**
```bash
# 转录 MP3 文件，输出同名 .txt
python3 scripts/speech_to_text.py recording.mp3

# 指定输出文件
python3 scripts/speech_to_text.py meeting.wav transcript.txt
```

### 方式 2：YouTube 下载音频

```bash
python3 scripts/download_audio.py "YOUTUBE_URL" [保存目录]
```

**示例：**
```bash
# 下载到当前目录
python3 scripts/download_audio.py "https://www.youtube.com/watch?v=VIDEO_ID"

# 下载到指定目录
python3 scripts/download_audio.py "https://www.youtube.com/watch?v=VIDEO_ID" ~/Downloads
```

### 方式 3：YouTube 下载 + 自动转文本（推荐）

```bash
python3 scripts/download_and_transcribe.py "YOUTUBE_URL" [保存目录]
```

**示例：**
```bash
python3 scripts/download_and_transcribe.py "https://www.youtube.com/watch?v=VIDEO_ID" ~/Downloads
```

输出文件：
- `VIDEO_ID.mp3` - 音频文件
- `VIDEO_ID.txt` - 转录文本

## 支持的 YouTube 链接格式

- `https://www.youtube.com/watch?v=VIDEO_ID`
- `https://youtu.be/VIDEO_ID`
- `http...