Sarvam Transcribe

Sarvam Transcription

Use scripts/transcribe.py for voice notes up to five minutes. It calls Sarvam's saaras:v3 Speech-to-Text REST API and uses overlapping chunks for audio longer than the synchronous endpoint's 30-second limit.

Workflow

1. Confirm the requested files and preserve their chronological order.
2. A request to transcribe with Sarvam authorizes uploading only those files to Sarvam AI. Otherwise, tell the user that the audio will be sent to Sarvam before running the script.
3. Choose the output:
   • transcribe: normalized text in the original script (default).
   • translate: English translation.
   • verbatim: word-for-word native-script transcript.
   • translit: Roman-script transliteration.
   • codemix: Indic words in native script and English words in Latin script.
4. Use a known BCP-47 language code when reliable, such as hi-IN or ml-IN; otherwise use unknown. Always specify the language for clips under three seconds, where auto-detection may lack enough signal. For Hinglish, prefer hi-IN --mode codemix.
5. Run one billable pass by default:

python3 <skill-directory>/scripts/transcribe.py \
  --language hi-IN --mode transcribe "/absolute/path/to/message.opus"

Multiple files are supported:

python3 <skill-directory>/scripts/transcribe.py \
  --language unknown file1.opus file2.opus

6. Return the transcript per file. Preserve names, numbers, and uncertainty. Never repair unclear words by inventing details. Do not summarize unless the user asks separately — and never via Sarvam LLM APIs; this skill is speech-to-text only (saaras:v3).
7. When the user requests an English translation, make a second pass:

python3 <skill-directory>/scripts/transcribe.py \
  --language hi-IN --mode translate "/absolute/path/to/message.opus"

8. Compare names, numbers, and other identifiers across the native transcript and English pass. Flag every discrepancy and ask the user to verify it from the audio; never silently select or normalize one version. Each pass is separately billable.

Authentication

The script reads SARVAM_API_KEY, then macOS Keychain service sarvam-api-key. Never ask the user to paste the key into chat or commit it. Never print or store the key.

If no key is configured, direct the user to create one at https://dashboard.sarvam.ai/.

macOS Keychain (zsh):

read -s "SARVAM_API_KEY?Sarvam API key: "; echo
security add-generic-password -U -a "$USER" -s sarvam-api-key -w "$SARVAM_API_KEY"
unset SARVAM_API_KEY

Elsewhere:

export SARVAM_API_KEY="your-key"

Scope and limits

• Requires Python 3.9+, ffmpeg, and ffprobe.
• The synchronous REST endpoint rejects audio over 30 seconds. This utility keeps every overlapping request below that limit.
• Supported formats: WAV, MP3, AAC, AIFF, OGG, OPUS, FLAC, MP4/M4A, AMR, WMA, and WebM. Not .oga: WhatsApp exporters (including wacli media download) often write voice notes as .oga; remux first (ffmpeg -y -i msg.oga -c copy msg.ogg) then pass the .ogg to this script.
• This utility rejects audio longer than five minutes. For clips just over that limit, split with ffmpeg into ≤4.5m chunks and run one pass per chunk (same --language / --mode), then concatenate transcripts in order. Prefer this over a Batch STT client unless the user needs diarization or timestamps. Example: ffmpeg -y -i long.m4a -f segment -segment_time 270 -c copy /tmp/chunk_%02d.m4a
• Audio is uploaded to Sarvam and each pass may be billable. Automatic POST retries are disabled so an ambiguous timeout cannot duplicate cost.
• Raw PCM requires an explicit codec and is intentionally outside this simple utility's scope.

Sources

• REST endpoint: https://docs.sarvam.ai/api-reference/speech-to-text/transcribe
• Quickstart: https://docs.sarvam.ai/api/getting-started/quickstart
• API selection: https://docs.sarvam.ai/api/api-guides-tutorials/speech-to-text/which-api-to-use