audio-processing

音频摄取、分析、转换和生成（转录、TTS、VAD、功能）。

# Audio Processing Skill

A comprehensive toolset for audio manipulation and analysis with security validations.

## Security

- File paths are validated to prevent path traversal attacks
- Access to system directories (/etc, /proc, /sys, /root) is blocked
- TTS text input is limited to 10,000 characters
- All file operations use resolved absolute paths

## Tool API

### audio_tool
Perform audio operations like transcription, text-to-speech, and feature extraction.

- **Parameters:**
  - `action` (string, required): One of `transcribe`, `tts`, `extract_features`, `vad_segments`, `transform`.
  - `file_path` (string, optional): Path to input audio file.
  - `text` (string, optional): Text for TTS (max 10,000 chars).
  - `output_path` (string, optional): Path for output file (default: auto-generated).
  - `model` (string, optional): Whisper model size (tiny, base, small, medium, large). Default: `base`.
  - `ops` (string, optional): JSON string of operations for transform action.

**Usage:**

```bash
# Transcribe audio file
uv run --with "openai-whisper" --with "pydub" --with "numpy" skills/audio-processing/tool.py transcribe --file_path input.wav

# Transcribe with specific model
uv run --with "openai-whisper" skills/audio-processing/tool.py transcribe --file_path input.wav --model small

# Text-to-speech
uv run --with "gTTS" skills/audio-processing/tool.py tts --text "Hello world" --output_path hello.mp3

# Extract audio features
uv run --with "librosa" --with "numpy" --with "soundfile" skills/audio-processing/tool.py extract_features --file_path input.wav

# Voice activity detection (find speech segments)
uv run --with "pydub" skills/audio-processing/tool.py vad_segments --file_path input.wav

# Transform audio (trim, resample, normalize)
uv run --with "pydub" skills/audio-processing/tool.py transform --file_path input.wav --ops '[{"op": "trim", "start": 10, "end": 30}, {"op": "normalize"}]'
```

## Actions

### transcribe
Convert speech to text using OpenAI Whisper.

- Returns: `{ "text": "...", "segments": [...] }`
- Models: tiny, base, small, medium, large (larger = more accurate, slower)

### tts
Generate speech from text using Google TTS.

- Returns: `{ "file_path": "output.mp3", "status": "created" }`
- Language: English (default)

### extract_features
Extract audio features for analysis.

- Returns: duration, sample_rate, mfcc_mean, rms_mean
- Useful for audio classification, quality analysis

### vad_segments
Detect speech segments using silence detection.

- Returns: `{ "segments": [{ "start": 0.5, "end": 3.2 }, ...] }`
- Uses FFmpeg silencedetect filter
- Aggressiveness: 1-3 (default: 2)

### transform
Apply transformations to audio files.

- Operations: trim, resample, normalize
- Returns: `{ "file_path": "output.wav" }`

## Requirements

- **ffmpeg:** Required for VAD and transform operations
- **Python 3.8+:** All operations
- **Disk Space:** Whisper models range from 100MB (tiny) to 3GB (large)

## Error Handling

- Returns JSON error object on failure
- Validates all file paths before processing
- Gracefully handles missing dependencies

---

## 中文说明

# 音频处理技能

一套全面的音频处理与分析工具集，内置安全校验。

## 安全

- 校验文件路径，防止路径遍历攻击
- 阻止访问系统目录（/etc、/proc、/sys、/root）
- TTS 文本输入限制为 10,000 个字符
- 所有文件操作均使用解析后的绝对路径

## 工具 API

### audio_tool
执行音频操作，如转录、文本转语音和特征提取。

- **参数：**
  - `action`（字符串，必填）：取值为 `transcribe`、`tts`、`extract_features`、`vad_segments`、`transform` 之一。
  - `file_path`（字符串，可选）：输入音频文件的路径。
  - `text`（字符串，可选）：用于 TTS 的文本（最多 10,000 个字符）。
  - `output_path`（字符串，可选）：输出文件的路径（默认：自动生成）。
  - `model`（字符串，可选）：Whisper 模型大小（tiny、base、small、medium、large）。默认：`base`。
  - `ops`（字符串，可选）：用于 transform 操作的 JSON 字符串。

**用法：**

```bash
# Transcribe audio file
uv run --with "openai-whisper" --with "pydub" --with "numpy" skills/audio-processing/tool.py transcribe --file_path input.wav

# Transcribe with specific model
uv run --with "openai-whisper" skills/audio-processing/tool.py transcribe --file_path input.wav --model small

# Text-to-speech
uv run --with "gTTS" skills/audio-processing/tool.py tts --text "Hello world" --output_path hello.mp3

# Extract audio features
uv run --with "librosa" --with "numpy" --with "soundfile" skills/audio-processing/tool.py extract_features --file_path input.wav

# Voice activity detection (find speech segments)
uv run --with "pydub" skills/audio-processing/tool.py vad_segments --file_path input.wav

# Transform audio (trim, resample, normalize)
uv run --with "pydub" skills/audio-processing/tool.py transform --file_path input.wav --ops '[{"op": "trim", "start": 10, "end": 30}, {"op": "normalize"}]'
```

## 操作

### transcribe
使用 OpenAI Whisper 将语音转换为文本。

- 返回：`{ "text": "...", "segments": [...] }`
- 模型：tiny、base、small、medium、large（越大越准确，但速度越慢）

### tts
使用 Google TTS 从文本生成语音。

- 返回：`{ "file_path": "output.mp3", "status": "created" }`
- 语言：英语（默认）

### extract_features
提取音频特征以供分析。

- 返回：duration、sample_rate、mfcc_mean、rms_mean
- 适用于音频分类、质量分析

### vad_segments
通过静音检测识别语音片段。

- 返回：`{ "segments": [{ "start": 0.5, "end": 3.2 }, ...] }`
- 使用 FFmpeg silencedetect 滤镜
- 灵敏度：1-3（默认：2）

### transform
对音频文件应用变换。

- 操作：trim、resample、normalize
- 返回：`{ "file_path": "output.wav" }`

## 依赖要求

- **ffmpeg：** VAD 和 transform 操作所必需
- **Python 3.8+：** 所有操作
- **磁盘空间：** Whisper 模型大小从 100MB（tiny）到 3GB（large）不等

## 错误处理

- 失败时返回 JSON 错误对象
- 处理前校验所有文件路径
- 优雅地处理缺失的依赖