audio_path = "preprocessed_audio.wav"

response = transcribe_audio(audio_path)

transcript = response.get("transcription", "")
words = response.get("words", [])
utterances = response.get("utterances", [])
language = response.get("language", "unknown")

print("Transcript:", transcript)
print("Detected language:", language)
print("Word count:", len(words))
print("Speaker turns:", len(utterances))

python -m venv stt-env
# macOS / Linux
source stt-env/bin/activate
# Windows
stt-env\Scripts\activate
pip install requests python-dotenv pydub

SMALLEST_API_KEY=your_api_key_here
from dotenv import load_dotenv

from pydub import AudioSegment<p></p>
<p>def preprocess_audio(input_path: str, output_path: str) -> str:<br>"""<br>Convert an audio file to mono, 16 kHz, 16-bit PCM WAV.<br>This format is commonly preferred for speech-to-text pipelines.<br>"""<br>audio = AudioSegment.from_file(input_path)</p>
<pre><code>

import os<br>import requests<br>from dotenv import load_dotenv<p></p><br><p>load_dotenv()</p><br><p>def transcribe_audio(file_path: str) -> dict:<br>"""<br>Send a local audio file to Smallest.ai Pulse STT<br>and return the transcription response as JSON.<br>"""<br>api_key = os.getenv("SMALLEST_API_KEY")</p><br><pre><code>if not api_key:<br>raise ValueError("Missing SMALLEST_API_KEY in environment variables.")<p></p>
<p>url = "<a href="https://api.smallest.ai/waves/v1/pulse/get_text" data-framer-link="Link:{"url":"https://api.smallest.ai/waves/v1/pulse/get_text","type":"url"}">https://api.smallest.ai/waves/v1/pulse/get_text</a>"</p>
<p>params = {<br>"language": "en",<br>"word_timestamps": "true",<br>"diarize": "false",<br>}</p>
<p>headers = {<br>"Authorization": f"Bearer {api_key}",<br>"Content-Type": "audio/wav",<br>}</p>
<p>with open(file_path, "rb") as audio_file:<br>response = requests.post(<br>url,<br>headers=headers,<br>params=params,<br>data=audio_file,<br>timeout=120,<br>)</p>

import os<br>import requests<br>from dotenv import load_dotenv<p></p><br><p>load_dotenv()</p><br><p>def transcribe_audio_url(audio_url: str) -> dict:<br>"""<br>Send a hosted audio URL to Smallest.ai Pulse STT<br>and return the transcription response as JSON.<br>"""<br>api_key = os.getenv("SMALLEST_API_KEY")</p><br><pre><code>if not api_key:<br>raise ValueError("Missing SMALLEST_API_KEY in environment variables.")<p></p>
<p>url = "<a href="https://api.smallest.ai/waves/v1/pulse/get_text" data-framer-link="Link:{"url":"https://api.smallest.ai/waves/v1/pulse/get_text","type":"url"}">https://api.smallest.ai/waves/v1/pulse/get_text</a>"</p>
<p>params = {<br>"language": "en",<br>"word_timestamps": "true",<br>"diarize": "true",<br>}</p>
<p>headers = {<br>"Authorization": f"Bearer {api_key}",<br>"Content-Type": "application/json",<br>}</p>
<p>payload = {<br>"url": audio_url,<br>}</p>
<p>response = requests.post(<br>url,<br>headers=headers,<br>params=params,<br>json=payload,<br>timeout=120,<br>)</p>
<p>response.raise_for_status()<br>return response.json()<br></code></pre><br><p>if <strong>name</strong> == "<strong>main</strong>":<br>result = transcribe_audio_url(<br>"<a href="<a href="https://example.com/audio/sample.wav" data-framer-link="Link:{"url":"https://example.com/audio/sample.wav","type":"url"}">https://example.com/audio/sample.wav</a>" data-framer-link="Link:{"url":"<a href="https://example.com/audio/sample.wav%22,%22type%22:%22url%22%7D%22&gt;https://example.com/audio/sample.wav&lt;/a&gt;%22&lt;br&gt;)&lt;/p" data-framer-link="Link:{"url":"https://example.com/audio/sample.wav%22,%22type%22:%22url%22%7D%22&gt;https://example.com/audio/sample.wav&lt;/a&gt;%22&lt;br&gt;)&lt;/p","type":"url"}">https://example.com/audio/sample.wav","type":"url"}"&gt;https://example.com/audio/sample.wav&lt;/a&gt;"&lt;br&gt;)&lt;/p</a>><br><pre><code>print(result.get("transcription", ""))</code></pre><h2 dir="ltr">Handling the API Response and Extracting Structured Data</h2><p dir="ltr">A transcription response is usually more than a single transcript field. Good APIs return structure: word timings, confidence scores, detected language, and sometimes speaker metadata. Here’s a typical response shape and a simple way to pull the useful parts out:</p><pre data-language="JSX"><code>def parse_transcript(response: dict) -&gt; None:<br>"""<br>Print the transcript, word-level timestamps,<br>confidence scores, and detected language.<br>"""<br>full_text = response.get("transcription", "")<br>print(f"Transcript: {full_text}")</p>
<p>words = response.get("words", [])</p>
<p>for word in words:<br>text = word.get("word", "")<br>start = word.get("start")<br>end = word.get("end")<br>confidence = word.get("confidence")</p>
<pre><code>start_text = f"{start:.2f}s" if isinstance(start, (int, float)) else "?"
end_text = f"{end:.2f}s" if isinstance(end, (int, float)) else "?"
confidence_text = (
    f"{confidence:.2f}" if isinstance(confidence, (int, float)) else "?"
)
<p>print(f"[{start_text} - {end_text}] {text} (confidence: {confidence_text})")<br></code></pre><br><p>language = response.get("language", "unknown")<br>print(f"Detected language: {language}")</code></pre><p dir="auto">Treat confidence scores as a routing signal, not trivia. When a word drops below ~0.7, the model is telling you it’s guessing, often because of noise, an unfamiliar proper noun, or overlapping speech. In production, low-confidence spans are a good place to trigger human review instead of letting uncertainty leak into downstream systems.</p><p dir="ltr"><br></p><img alt="" src="<a href="<a href="https://framerusercontent.com/images/dtDKjP7q5nU1Oh0VCEyezcE20.png%22&amp;gt;&amp;lt;p" data-framer-link="Link:{"url":"https://framerusercontent.com/images/dtDKjP7q5nU1Oh0VCEyezcE20.png%22&amp;gt;&amp;lt;p","type":"url"}">https://framerusercontent.com/images/dtDKjP7q5nU1Oh0VCEyezcE20.png%22&amp;gt;&amp;lt;p</a>" data-framer-link="Link:{"url":"<a href="https://framerusercontent.com/images/dtDKjP7q5nU1Oh0VCEyezcE20.png%22&amp;gt;&amp;lt;p%22,%22type%22:%22url%22%7D%22&gt;https://framerusercontent.com/images/dtDKjP7q5nU1Oh0VCEyezcE20.png%22&amp;gt;&amp;lt;p&lt;/a" data-framer-link="Link:{"url":"https://framerusercontent.com/images/dtDKjP7q5nU1Oh0VCEyezcE20.png%22&amp;gt;&amp;lt;p%22,%22type%22:%22url%22%7D%22&gt;https://framerusercontent.com/images/dtDKjP7q5nU1Oh0VCEyezcE20.png%22&amp;gt;&amp;lt;p&lt;/a","type":"url"}">https://framerusercontent.com/images/dtDKjP7q5nU1Oh0VCEyezcE20.png%22&amp;gt;&amp;lt;p","type":"url"}"&gt;https://framerusercontent.com/images/dtDKjP7q5nU1Oh0VCEyezcE20.png"&amp;gt;&amp;lt;p&lt;/a</a>> dir="ltr"><em>Anatomy of a transcription API response: transcript, word-level timestamps, and confidence scores</em></p><h2 dir="ltr">Speaker Diarization: Knowing Who Said What</h2><p dir="ltr">Single-speaker audio is the easy mode. Meetings, podcasts, and support calls are where things get interesting, because “what was said” isn’t enough, you need “who said it.” That’s diarization, and you typically switch it on with <code>diarize: True</code> in your request parameters.</p><p dir="ltr">When diarization is enabled, Pulse adds speaker labels to word-level and utterance-level output, so you can rebuild the transcript as a conversation.</p><pre data-language="JSX"><code>def format_diarized_transcript(response: dict) -&gt; str:<br>"""<br>Format diarized utterances into a readable speaker-by-speaker transcript.<br>"""<br>utterances = response.get("utterances", [])<br>lines = []</p><br><p>for utterance in utterances:<br>speaker = utterance.get("speaker", "unknown_speaker")<br>text = utterance.get("text", "").strip()<br>start = utterance.get("start", 0)</p><br><pre><code>if not text:<br>continue</p>
<p>lines.append(f"[{start:.1f}s] {speaker}: {text}")<br></code></pre><br><p>return "\n".join(lines)</code></pre><p dir="auto">There’s a catch: diarization gets worse when people talk over each other. In call-center audio, interruptions are common, and the cleanest fix is often upstream (separate channels when you have them, then transcribe) rather than expecting the model to untangle cross-talk perfectly. The <a href="/blog/from-raw-audio-to-structured-dialogue-a-guide-to-speaker-diarization-pipelines">speaker diarization pipelines guide</a> goes deeper on multi-speaker strategies.</p><h2 dir="ltr">Handling Long Audio Files and Chunking Strategies</h2><p dir="ltr">Transcription APIs usually impose limits on file size or duration. Even if yours doesn’t, pushing a 90-minute recording through a single request is asking for trouble: one timeout and you’re back at zero. Chunking long audio into smaller pieces is the standard way to keep the pipeline resilient.</p><p dir="ltr">A robust chunking strategy for long audio files:</p><ul dir="auto"><li data-preset-tag="p"><p>Split audio into segments of 30-60 seconds using <code>pydub</code>'s <code>make_chunks</code> method</p></li><li data-preset-tag="p"><p>Add a 1-2 second overlap between chunks to avoid cutting words at boundaries</p></li><li data-preset-tag="p"><p>Transcribe each chunk independently and collect results in order</p></li><li data-preset-tag="p"><p>Merge transcripts by removing duplicate words in the overlap region using a simple string alignment check</p></li><li data-preset-tag="p"><p>Preserve global timestamps by offsetting each chunk's word timestamps by its start position in the original file</p></li></ul><pre data-language="JSX"><code>from pydub import AudioSegment<br></code></pre><br><p>def split_audio_with_overlap(<br>input_path: str,<br>output_dir: str,<br>chunk_length_ms: int = 60_000,<br>overlap_ms: int = 2_000,<br>) -> list[str]:<br>"""<br>Split long audio into overlapping chunks.<br>Default: 60-second chunks with 2-second overlap.<br>"""<br>audio = AudioSegment.from_file(input_path)<br>chunk_paths = []</p><br><pre><code>start = 0<br>chunk_index = 0</p><br><p>while start &lt; len(audio):<br>end = min(start + chunk_length_ms, len(audio))<br>chunk = audio[start:end]</p><br><pre><code>chunk_path = f"{output_dir}/chunk_{chunk_index:04d}.wav"<br>chunk.export(chunk_path, format="wav")</p>
<p>chunk_paths.append(chunk_path)</p>
<p>if end == len(audio):<br>break</p>