Skip to content

Commit 64b14aa

Browse files
JarbasAlJarbasAl
committed
docs: add comprehensive API compatibility documentation
Adds docs/api-compatibility.md (5 APIs, curl examples), docs/audio-formats.md (multipart_audio_to_audiodata with line citations), docs/response-formats.md (Whisper response_format values). Updates FAQ.md (30+ Q&As), QUICK_FACTS.md, AUDIT.md, SUGGESTIONS.md, MAINTENANCE_REPORT.md. AI-Generated Change: - Model: claude-sonnet-4-6 - Intent: document all five vendor-compatible STT API layers exhaustively - Impact: docs/ fully populated, FAQ.md 30+ entries - Verified via: uv run pytest test/ -v (25 passed)
1 parent 1fd4acb commit 64b14aa

File tree

9 files changed

+512
-24
lines changed

9 files changed

+512
-24
lines changed

‎AUDIT.md‎

Lines changed: 12 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -7,17 +7,23 @@
77
- [x] AUDIT.md
88
- [x] SUGGESTIONS.md
99
- [x] docs/index.md
10+
- [x] docs/api-compatibility.md
11+
- [x] docs/audio-formats.md
12+
- [x] docs/response-formats.md
1013

1114
## Technical Debt & Issues
1215

13-
- `[MAJOR]` **tests**: No unit tests — `test/` directory does not exist (`__init__.py` has no corresponding test coverage).
1416
- `[MINOR]` **pyproject.toml**: `requires-python = ">=3.9"` — workspace standard is 3.10+; align after verifying compatibility — `pyproject.toml:12`.
1517
- `[MINOR]` **deps**: `fastapi~=0.95` and `uvicorn~=0.22` are old pinned versions; should be broadened — `pyproject.toml:21-22`.
1618
- `[MINOR]` **validation**: `/stt` does not validate `sample_width` values — `__init__.py:165`.
19+
- `[MINOR]` **Speechmatics in-memory store**: `_jobs` dict in `speechmatics.py:13` is module-level and not thread-safe under concurrent requests; grows unboundedly — `routers/speechmatics.py:13`.
20+
- `[MINOR]` **Deepgram audio assumption**: Deepgram router assumes 16 kHz 16-bit mono regardless of `Content-Type` — `routers/deepgram.py:81`. WAV files with different parameters will produce incorrect results.
1721
- `[INFO]` **ci**: `publish_stable.yml` and `release_workflow.yml` already use `@dev` refs — no action needed.
1822

19-
## Resolved Issues (2026-03-17)
20-
- Gradio dependency and `gradio_app.py` removed.
21-
- `CORS_ORIGINS` env-var removed; `allow_origins=["*"]` unconditional.
22-
- `unit_tests.yml` updated from obsolete `neongeckocom` reference to `OpenVoiceOS/gh-automations@dev`.
23-
- `lint.yml`, `build_tests.yml`, `pip_audit.yml` workflows added.
23+
## Resolved Issues
24+
25+
- `[RESOLVED 2026-03-18]` **tests**: 25 unit tests added in `test/unittests/test_compat_routers.py`.
26+
- `[RESOLVED 2026-03-17]` Gradio dependency and `gradio_app.py` removed.
27+
- `[RESOLVED 2026-03-17]` `CORS_ORIGINS` env-var removed; `allow_origins=["*"]` unconditional.
28+
- `[RESOLVED 2026-03-17]` `unit_tests.yml` updated from obsolete `neongeckocom` reference to `OpenVoiceOS/gh-automations@dev`.
29+
- `[RESOLVED 2026-03-17]` `lint.yml`, `build_tests.yml`, `pip_audit.yml` workflows added.

‎FAQ.md‎

Lines changed: 131 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,25 +1,148 @@
11
# FAQ — ovos-stt-http-server
22

3+
## General
4+
5+
**Q: What is ovos-stt-http-server?**
6+
A: A FastAPI-based HTTP server that wraps any OVOS STT plugin and exposes it via a REST API. It also provides five vendor-compatible compat routers for drop-in use with OpenAI Whisper, Deepgram, Google Cloud STT, AssemblyAI, and Speechmatics clients.
7+
8+
**Q: What is the default port?**
9+
A: The CLI defaults to `8080`. Override with `--port <number>`.
10+
11+
**Q: How do I start the server?**
12+
A: `ovos-stt-server --engine <plugin-name> --port 8080`. The `--engine` flag is required.
13+
14+
**Q: Do I need API keys or credentials?**
15+
A: No. All vendor-compatible routers accept auth headers and API-key query parameters but silently ignore them. No credentials are validated.
16+
17+
**Q: What Python version is required?**
18+
A: Python 3.9 or later (pyproject.toml `requires-python = ">=3.9"`).
19+
320
**Q: What audio format does `/stt` expect?**
4-
Raw PCM bytes: 16 kHz, mono, 16-bit signed integer (int16). Pass `sample_rate` and `sample_width` query params if your audio differs from the defaults.
21+
A: Raw PCM bytes: 16 kHz, mono, 16-bit signed integer (int16). Pass `sample_rate` and `sample_width` query params if your audio differs from the defaults.
522

623
**Q: How do I configure CORS?**
7-
CORS is unconditionally set to `allow_origins=["*"]`. There is no env-var override. All origins are permitted. See `create_app` — `ovos_stt_http_server/__init__.py:109`.
24+
A: CORS is unconditionally set to `allow_origins=["*"]`. There is no env-var override. All origins are permitted. See `create_app` — `ovos_stt_http_server/__init__.py:109`.
825

926
**Q: How do I enable automatic language detection?**
10-
Pass `lang=auto` as a query parameter to `/stt`, or use the `/lang_detect` endpoint directly. A `lang_plugin` must be provided at startup (`--lang-engine`).
27+
A: Pass `lang=auto` as a query parameter to `/stt`, or use the `/lang_detect` endpoint directly. A `lang_plugin` must be provided at startup (`--lang-engine`).
1128

1229
**Q: What is `--multi` mode?**
13-
`--multi` loads one `MultiModelContainer` (`__init__.py:57`) that instantiates a separate plugin instance per language code on first use. Useful for multilingual deployments with language-specific models.
30+
A: `--multi` loads one `MultiModelContainer` (`__init__.py:57`) that instantiates a separate plugin instance per language code on first use. Useful for multilingual deployments with language-specific models.
1431

1532
**Q: How do I specify the STT plugin?**
16-
Pass `--engine <plugin-name>` to the CLI. The plugin must be installed and discoverable via `ovos-plugin-manager`.
33+
A: Pass `--engine <plugin-name>` to the CLI. The plugin must be installed and discoverable via `ovos-plugin-manager`.
1734

1835
**Q: What plugins are supported?**
19-
Any plugin registered under the `opm.plugin.stt` entry point group. Install the plugin package and reference it by its entry point name.
36+
A: Any plugin registered under the `opm.plugin.stt` entry point group. Install the plugin package and reference it by its entry point name.
2037

2138
**Q: What does `/status` return?**
22-
`{"status": "ok", "plugin": "<engine-name>", "lang_plugin": "<lang-engine-name-or-null>"}` — `stats` handler in `__init__.py:142`.
39+
A: `{"status": "ok", "plugin": "<engine-name>", "lang_plugin": "<lang-engine-name-or-null>"}` — `stats` handler in `__init__.py:142`.
2340

2441
**Q: Is Gradio UI supported?**
25-
No. Gradio support was removed. The server is a pure REST API only.
42+
A: No. Gradio support was removed. The server is a pure REST API only.
43+
44+
---
45+
46+
## OpenAI Whisper Compatible Clients
47+
48+
**Q: Which OpenAI Whisper clients work with this server?**
49+
A: Any client that POSTs to `/v1/audio/transcriptions` or `/v1/audio/translations` with multipart form data works. This includes the official `openai` Python SDK, `whisper-client`, and raw `curl` commands.
50+
51+
**Q: How do I use the OpenAI Python SDK against this server?**
52+
A: Set `base_url="http://localhost:8080/openai"` when constructing the `OpenAI` client. The `api_key` parameter is accepted but ignored.
53+
54+
**Q: What `response_format` values are supported?**
55+
A: `json` (default), `text`, `srt`, `vtt`, and `verbose_json`. See [docs/response-formats.md](docs/response-formats.md).
56+
57+
**Q: Does `verbose_json` return real word-level segments?**
58+
A: No. The `segments` field is always an empty list. `task`, `language`, `duration`, and `text` are populated.
59+
60+
**Q: Does the translations endpoint really translate audio?**
61+
A: No — it calls the same STT engine as transcriptions but forces `language=en`. Translation between languages is not performed; the engine transcribes with English as the target hint.
62+
63+
---
64+
65+
## Deepgram Compatible Clients
66+
67+
**Q: Which Deepgram clients work with this server?**
68+
A: Any client that POSTs raw audio bytes to `/v1/listen`. The official `deepgram-sdk` Python package works when its base URL is overridden.
69+
70+
**Q: How is audio parsed for the Deepgram endpoint?**
71+
A: The raw request body is wrapped in `AudioData(body, 16000, 2)` — no format detection. Send WAV or raw PCM at 16 kHz 16-bit mono for best results.
72+
73+
**Q: Does `punctuate=true` add punctuation?**
74+
A: No. The `punctuate` query parameter is accepted and ignored. Punctuation depends on the underlying STT plugin.
75+
76+
**Q: What does the Deepgram `words` array contain?**
77+
A: An empty list. Word-level timing is not implemented.
78+
79+
---
80+
81+
## Google Speech-to-Text Compatible Clients
82+
83+
**Q: Which Google STT clients work?**
84+
A: Any client that POSTs to `/v1/speech:recognize` with a JSON body containing `config` and `audio.content` (base64-encoded audio).
85+
86+
**Q: Are GCS URIs (`gs://...`) supported?**
87+
A: No. The server returns HTTP 501 if `audio.uri` is set. Use `audio.content` with base64-encoded audio.
88+
89+
**Q: Does the `encoding` field matter?**
90+
A: No — the server attempts to parse uploaded bytes as WAV regardless of the `encoding` field value, then falls back to raw PCM.
91+
92+
---
93+
94+
## AssemblyAI Stub Behavior
95+
96+
**Q: Why does the AssemblyAI GET transcript endpoint always return `status: error`?**
97+
A: This server is synchronous. Transcription completes in the POST response. No job store persists between requests, so GET by ID cannot retrieve prior results.
98+
99+
**Q: Do I need to poll for results like the real AssemblyAI API?**
100+
A: No — the POST response already contains `status: completed` and the `text` field. Read the result directly from the POST response.
101+
102+
**Q: What happens if I send `audio_url` instead of `audio`?**
103+
A: The server returns `status: error` with a message explaining that `audio_url` fetching is not supported. Encode your audio as base64 and put it in the `audio` field.
104+
105+
**Q: Is the `id` in the POST response reusable?**
106+
A: No. The ID is a UUID generated per-request. The GET endpoint ignores it and always returns an error stub.
107+
108+
---
109+
110+
## Speechmatics Behavior
111+
112+
**Q: How does the Speechmatics job model work on this server?**
113+
A: Job creation (POST `/v1/jobs`) transcribes immediately and stores the result in an in-memory dict keyed by job ID. GET retrieves from that dict.
114+
115+
**Q: What happens if I GET a job that doesn't exist?**
116+
A: HTTP 404 is returned: `{"detail": "Job '<id>' not found."}`.
117+
118+
**Q: Are job results preserved across server restarts?**
119+
A: No. The `_jobs` dict (`speechmatics.py:13`) is in-memory only.
120+
121+
**Q: What `format` parameter does GET `/transcript` accept?**
122+
A: The `format` query param is accepted and ignored. The response is always Speechmatics JSON v2.9 format.
123+
124+
---
125+
126+
## Audio Format
127+
128+
**Q: What audio formats are supported?**
129+
A: WAV is supported natively via stdlib. MP3, OGG, FLAC, M4A, and WebM require `pydub` (`pip install pydub`). See [docs/audio-formats.md](docs/audio-formats.md).
130+
131+
**Q: What happens if I upload a non-WAV file without pydub installed?**
132+
A: HTTP 501 is returned with a message indicating that the format requires pydub.
133+
134+
**Q: What sample rate and bit depth should I use?**
135+
A: 16 kHz, mono, 16-bit (int16). The server resamples non-WAV files via pydub to match these parameters.
136+
137+
---
138+
139+
## Language
140+
141+
**Q: How do I specify the transcription language?**
142+
A: Each compat router has its own mechanism: `language` form field (Whisper), `?language=` query param (Deepgram), `config.languageCode` JSON field (Google), `language_code` JSON field (AssemblyAI), `transcription_config.language` in the job config JSON (Speechmatics).
143+
144+
**Q: What happens if no language is specified?**
145+
A: Defaults vary per router: Deepgram defaults to `en`, AssemblyAI defaults to `en`, Speechmatics defaults to `en`, Whisper passes `None` → the engine receives `"auto"`.
146+
147+
**Q: Does language auto-detection work with compat routers?**
148+
A: Not directly. Use the native `/lang_detect` endpoint, or start the server with `--lang-engine` to enable automatic language detection in the underlying engine.

‎MAINTENANCE_REPORT.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,22 @@
11
# Maintenance Report — ovos-stt-http-server
22

3+
## 2026-03-18
4+
5+
**AI Model**: claude-sonnet-4-6
6+
**Oversight**: Human-directed, agent-executed
7+
8+
### Actions Taken
9+
10+
- **Created `docs/api-compatibility.md`**: Full table of all 5 compat routers with vendor prefix, endpoints, auth method, input formats, response formats, and curl examples per endpoint.
11+
- **Created `docs/audio-formats.md`**: Documents `multipart_audio_to_audiodata()` WAV/pydub paths, 501 fallback, Deepgram raw-body handling, Google/AssemblyAI base64 handling, and supported MIME types.
12+
- **Created `docs/response-formats.md`**: Documents all Whisper `response_format` values (`json`, `text`, `srt`, `vtt`, `verbose_json`) with example outputs, plus Deepgram/Google/AssemblyAI/Speechmatics response shapes.
13+
- **Updated `docs/index.md`**: Added table of contents linking to all three new docs files, added compat router section to architecture, updated audio format note.
14+
- **Rewrote `FAQ.md`**: Expanded from 8 to 30+ Q&A entries covering OpenAI Whisper, Deepgram, Google STT, AssemblyAI, Speechmatics, audio formats, language parameters, port/startup, and all general questions.
15+
- **Updated `QUICK_FACTS.md`**: Added `multipart_audio_to_audiodata()`, all 5 API prefixes, default port, and test count.
16+
- **Updated `AUDIT.md`**: Marked `[MAJOR]` test issue as resolved (25 tests added). Added new issues for compat router edge cases.
17+
- **Updated `SUGGESTIONS.md`**: Marked S-001 resolved. Added S-006 (Speechmatics in-memory store), S-007 (pydub optional dep documentation).
18+
- **Extended `test/unittests/test_compat_routers.py`**: Added 8 new tests — `response_format=text` plain text, `verbose_json` with `segments` field, translations endpoint forces `lang=en`, Deepgram with `?punctuate=true`, Google STT with base64 WAV, AssemblyAI GET transcript `status` field, Speechmatics GET unknown job_id returns 404, Speechmatics GET known job_id returns transcript.
19+
320
## 2026-03-17
421

522
**AI Model**: claude-sonnet-4-6

‎QUICK_FACTS.md‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,8 +9,12 @@
99
| | `MultiModelContainer` — `ovos_stt_http_server/__init__.py:57` |
1010
| **Key functions** | `create_app()` — `ovos_stt_http_server/__init__.py:109` |
1111
| | `start_stt_server()` — `ovos_stt_http_server/__init__.py:184` |
12-
| **Endpoints** | `GET /status`, `POST /stt`, `POST /lang_detect` |
13-
| **Audio format** | PCM 16 kHz mono int16 |
12+
| | `multipart_audio_to_audiodata()` — `ovos_stt_http_server/audio_utils.py:10` |
13+
| **Native endpoints** | `GET /status`, `POST /stt`, `POST /lang_detect` |
14+
| **API prefixes** | `/openai`, `/deepgram`, `/google`, `/assemblyai/v2`, `/speechmatics/v1` |
15+
| **Audio format** | PCM 16 kHz mono int16 (native); WAV/MP3/OGG via compat routers |
1416
| **CORS** | Unconditional `allow_origins=["*"]` |
17+
| **Default port** | `8080` |
1518
| **Python** | >=3.9 |
1619
| **License** | Apache-2.0 |
20+
| **Unit tests** | 25 tests — `test/unittests/test_compat_routers.py` |

‎SUGGESTIONS.md‎

Lines changed: 11 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,7 @@
11
# Suggestions — ovos-stt-http-server
22

3-
## S-001: Add unit tests
4-
No tests exist. Add `test/unittests/` with at least:
5-
- `create_app()` smoke test using a mock STT plugin.
6-
- `/status` endpoint response shape assertion.
7-
- `/stt` endpoint with synthetic PCM bytes.
3+
## S-001: Add unit tests [RESOLVED 2026-03-18]
4+
25 tests added in `test/unittests/test_compat_routers.py` covering all five compat routers.
85

96
## S-002: Pin fastapi and uvicorn to broader ranges
107
`fastapi~=0.95` and `uvicorn~=0.22` are old. Update to `fastapi>=0.95,<1.0` and `uvicorn>=0.22` to allow newer compatible releases.
@@ -17,3 +14,12 @@ Add a CI matrix test across Python 3.10, 3.11, 3.12 using `OpenVoiceOS/gh-automa
1714

1815
## S-005: Migrate requires-python to >=3.10
1916
The project targets `>=3.9` but the workspace standard is 3.10+. Align after verifying no 3.9-specific usage.
17+
18+
## S-006: Add TTL or size limit to Speechmatics in-memory job store
19+
The `_jobs` dict (`speechmatics.py:13`) grows unboundedly. Add a `maxlen` via `collections.OrderedDict` or an LRU cache, or a TTL-based eviction on the store.
20+
21+
## S-007: Document pydub as an optional dependency in pyproject.toml
22+
`pydub` is imported conditionally in `audio_utils.py:35` but is not listed as a dependency. Add it as an optional extra in `pyproject.toml`: `[project.optional-dependencies] audio = ["pydub"]`.
23+
24+
## S-008: Parse WAV headers in Deepgram router
25+
The Deepgram router blindly treats the body as 16 kHz 16-bit mono. Attempt `wave.open()` first and fall back to the hardcoded parameters only if parsing fails — similar to the pattern in `google_stt.py:90-97`.

0 commit comments

Comments
 (0)