From c9ec8fa2c2cfd0f2f44c34dcb716267182ef27b2 Mon Sep 17 00:00:00 2001
From: Huaaudio <jiahua.zhang@kuleuven.be>
Date: Sat, 28 Mar 2026 02:46:33 +0100
Subject: [PATCH] update documents

---
 pkg/audio/asr/README.md | 54 +++++++++++++++++++++++++++++++++++++++++
 pkg/audio/tts/README.md | 46 +++++++++++++++++++++++++++++++++++
 2 files changed, 100 insertions(+)
 create mode 100644 pkg/audio/asr/README.md
 create mode 100644 pkg/audio/tts/README.md

diff --git a/pkg/audio/asr/README.md b/pkg/audio/asr/README.md
new file mode 100644
index 000000000..76a6bd893
--- /dev/null
+++ b/pkg/audio/asr/README.md
@@ -0,0 +1,54 @@
+# ASR (Automatic Speech Recognition)
+
+This package handles Automatic Speech Recognition (speech-to-text) capabilities.
+
+## Configuration
+
+PicoClaw uses the unified and secure `ModelList` configuration for ASR. Instead of plain-text API keys in the `voice` configuration, you should define your ASR providers in the global `model_list` and reference them by name in the `voice` configuration section.
+
+To configure an ASR model, set the `model_name` under the `voice` configuration to match a defined model in your `model_list`.
+
+### Example `config.json`
+
+```json
+{
+  "voice": {
+    "model_name": "my-asr-model",
+    "echo_transcription": true
+  },
+  "model_list": [
+    {
+      "model_name": "my-asr-model",
+      "model": "openai/whisper-1",
+      "api_base": "https://api.openai.com/v1"
+    },
+    {
+      "model_name": "elevenlabs-asr",
+      "model": "elevenlabs/scribe_v1"
+    }
+  ]
+}
+```
+
+### Security Configuration
+
+API keys for the ASR model should be supplied in your `.security.yml` file matching the respective `model_name`:
+
+```yaml
+model_list:
+  my-asr-model:
+    api_keys:
+      - "sk-openai-your-key-here"
+  elevenlabs-asr:
+    api_keys:
+      - "sk-elevenlabs-your-key"
+```
+
+## How It Works
+
+PicoClaw's `DetectTranscriber` function will attempt to detect the appropriate Transcriber in the following order:
+
+1. **Targeted Selection**: Standard matching via `cfg.Voice.ModelName`.
+    - If the protocol matches `elevenlabs/`, the ElevenLabs transcriber is initiated.
+    - If the protocol supports general OpenAI-compatible audio transcription endpoints (e.g., `openai`, `azure`, `groq`, `deepseek`), `AudioModelTranscriber` is leveraged.
+2. **Fallback Scanning**: If no `model_name` is selected, it scans `model_list` specifically looking for `elevenlabs/` protocol models or `groq/` provider formats (e.g. for Whisper fallback). 
diff --git a/pkg/audio/tts/README.md b/pkg/audio/tts/README.md
new file mode 100644
index 000000000..ce2ed3fad
--- /dev/null
+++ b/pkg/audio/tts/README.md
@@ -0,0 +1,46 @@
+# TTS (Text-to-Speech)
+
+This package handles Text-to-Speech (speech synthesis) capabilities.
+
+## Configuration
+
+PicoClaw uses the unified and secure `ModelList` configuration for TTS. Plain-text API keys are no longer tolerated in the `voice` config block directly. 
+
+To configure a TTS model, define it in your `model_list`, and set it in your `voice` configuration block using the `tts_model_name` field.
+
+### Example `config.json`
+
+```json
+{
+  "voice": {
+    "tts_model_name": "my-tts-model"
+  },
+  "model_list": [
+    {
+      "model_name": "my-tts-model",
+      "model": "openai/tts-1",
+      "api_base": "https://api.openai.com/v1"
+    }
+  ]
+}
+```
+
+### Security Configuration
+
+API keys for your TTS model are managed securely with standard `model_list` entries in `.security.yml`:
+
+```yaml
+model_list:
+  my-tts-model:
+    api_keys:
+      - "sk-openai-your-key-here"
+```
+
+## How It Works
+
+PicoClaw's `DetectTTS` function resolves the TTS Provider efficiently using the secure definitions:
+
+1. **Targeted Selection**: It will resolve the TTS Provider strictly via the `tts_model_name` configured in the `voice` block to pluck the respective model instance, base URL, keys, and proxy details.
+2. **Fallback Scanning**: If no explicit `tts_model_name` is set (or missing), PicoClaw will scan the `model_list` for any entry whose model structure explicitly contains the word `tts` and possesses a valid API key.
+
+Most standard TTS routing passes through `OpenAITTSProvider`, which acts universally for OpenAI-compatible audio speech synthesis API formats.