Speech audio preflight and REST/batch transcription diagnostics
For local audio header validation, Speech endpoint/Entra auth preflight, Fast
Transcription (2025-10-15), Batch Transcription (2025-10-15 / 2024-11-15)
and Batch Synthesis (2024-04-01). For native Speech SDK text logs, use
Speech SDK client diagnostics. Route Microsoft Foundry Voice
Agents (kind: voice / azd ai agent) to microsoft-foundry.
Workflow
- Confirm which Speech surface the app calls:
| Surface | Path & tier | Key public limits |
|---|---|---|
| Realtime STT / TTS | WebSocket / short REST (F0/S0) |
STT: F0 1, S0 100 concurrent (STT + translation shared), diarization <= 240 min. TTS: <= 10 min audio, <= 50 <voice>/<audio> tags, <= 64 KB WS SSML. |
| Fast Transcription | POST /speechtotext/transcriptions:transcribe?api-version=2025-10-15 (S0) |
Synchronous, < 500 MB, < 5 hours, shares 600 req/min with Batch STT. |
| Batch Transcription | POST /speechtotext/transcriptions:submit?api-version=2025-10-15 (S0) |
Async (contentContainerUrl or <= 1,000 contentUrls, <= 10,000 blobs/container), <= 1 GB/file, diarization <= 240 min/file, timeToLiveHours 6h..31d. |
| Batch Synthesis | PUT /texttospeech/batchsyntheses/{id}?api-version=2024-04-01 (S0) |
Payload <= 2 MB, <= 10,000 inputs, ID 3-64 chars ([A-Za-z0-9._-], alnum ends). Destination storage cannot be network-restricted (Long Audio retires 2027-04-01). |
Never ask for keys/SAS or paste transcripts/SSML. Check
node --version(Node.js 22+). If missing/older, follow audio checks without Node. Otherwise run the local inspector:node "<skill-directory>/scripts/inspect-speech-audio.mjs" --file "<local-audio-or-json>" --mode realtime-sdk& node "<skill-directory>\scripts\inspect-speech-audio.mjs" --file "<local-audio-or-json>" --mode realtime-sdkModes:
realtime-sdk,fast-transcription,batch-transcription,batch-transcription-files,batch-synthesis-job. Bash and PowerShell launchers use exit codes0report/--help,1file/JSON error,2usage error,3Node 22+ missing.Check common failure patterns:
SPXERR_INVALID_HEADER/NoMatchon.wav: compressed audio renamed.wav, non-PCMformatTag, missing/empty/truncateddatachunk, or leading all-zero PCM.- Entra ID / Private Link
401/403: needscustomSubdomainName,Cognitive Services Speech ContributororSpeech User, andaad#<resourceId>#<entraToken>on regional SDK hosts. Keys fail whendisableLocalAuth: true. - Batch
Succeededwith missing outputs: List Files has oneTranscriptionper successful input plus aTranscriptionReport, no per-file status. Runbatch-transcription-fileson the list, then on the downloaded report (failedTranscriptionsCount). - REST
429/499/5xx: SDK log analysis does not apply. Keep causes open from status codes; gather UTC times, region/endpoint, concurrency and response headers (no keys). A429within quota can occur while the service autoscales.