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>audio = audio.set_channels(1)
audio = audio.set_frame_rate(16000)
audio = audio.set_sample_width(2)

audio.export(output_path, format="wav")
return output_path
</code></pre>

import os<br>import requests<br>from dotenv import load_dotenv<p></p>
<p>load_dotenv()</p>
<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>
<pre><code>if not api_key:
    raise ValueError("Missing SMALLEST_API_KEY in environment variables.")

url = "https://api.smallest.ai/waves/v1/pulse/get_text"

params = {
    "language": "en",
    "word_timestamps": "true",
    "diarize": "false",
}

headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "audio/wav",
}

with open(file_path, "rb") as audio_file:
    response = requests.post(
        url,
        headers=headers,
        params=params,
        data=audio_file,
        timeout=120,
    )

response.raise_for_status()
return response.json()
</code></pre>

import os<br>import requests<br>from dotenv import load_dotenv<p></p>
<p>load_dotenv()</p>
<p>def transcribe_audio_url(audio_url: str) -> dict:<br>"""<br>एक होस्ट किए गए ऑडियो URL को Smallest.ai Pulse STT पर भेजें<br>और JSON के रूप में ट्रांसक्रिप्शन प्रतिक्रिया वापस प्राप्त करें।<br>"""<br>api_key = os.getenv("SMALLEST_API_KEY")</p>
<pre><code>if not api_key:
    raise ValueError("पर्यावरण चरों में SMALLEST_API_KEY मौजूद नहीं है।")

url = "https://api.smallest.ai/waves/v1/pulse/get_text"

params = {
    "language": "en",
    "word_timestamps": "true",
    "diarize": "true",
}

headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json",
}

payload = {
    "url": audio_url,
}

response = requests.post(
    url,
    headers=headers,
    params=params,
    json=payload,
    timeout=120,
)

response.raise_for_status()
return response.json()
</code></pre>
<p>if <strong>name</strong> == "<strong>main</strong>":<br>result = transcribe_audio_url(<br>"<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>"<br>)</p>
<pre><code>print(result.get("transcription", ""))</code></pre><h2 dir="ltr">API प्रतिक्रिया को संभालना और संरचित डेटा निकालना</h2><p dir="ltr">ट्रांसक्रिप्शन प्रतिक्रिया आमतौर पर केवल एक ट्रांसक्रिप्ट फ़ील्ड से कहीं अधिक होती है। अच्छे API संरचित डेटा लौटाते हैं: शब्द समय (word timings), विश्वसनीयता स्कोर, पहचानी गई भाषा और कभी-कभी वक्ता का मेटाडेटा। यहाँ एक विशिष्ट प्रतिक्रिया रूप और उपयोगी भागों को निकालने का एक सरल तरीका दिया गया है:</p><pre data-language="JSX"><code>def parse_transcript(response: dict) -&gt; None:
"""
ट्रांसक्रिप्ट, शब्द-स्तरीय टाइमस्टैम्प,
विश्वसनीयता स्कोर और पहचानी गई भाषा को प्रिंट करें।
"""
full_text = response.get("transcription", "")
print(f"Transcript: {full_text}")

words = response.get("words", [])

for word in words:
    text = word.get("word", "")
    start = word.get("start")
    end = word.get("end")
    confidence = word.get("confidence")

    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 "?"
    )

    print(f"[{start_text} - {end_text}] {text} (confidence: {confidence_text})")

language = response.get("language", "unknown")
print(f"Detected language: {language}")</code></pre><p dir="auto">विश्वसनीयता (confidence) स्कोर को केवल सामान्य जानकारी न समझकर एक राउटिंग सिग्नल की तरह मानें। जब कोई शब्द ~0.7 से नीचे चला जाता है, तो मॉडल आपको बता रहा होता है कि वह केवल अनुमान लगा रहा है, अक्सर शोर, किसी अपरिचित संज्ञा या ओवरलैपिंग बातचीत के कारण। प्रोडक्शन में, कम-विश्वसनीयता वाले क्षेत्रों को बाद के सिस्टम में भेजने के बजाय मानव समीक्षा के लिए भेजना एक बेहतर विकल्प है।</p><p dir="ltr"><br></p><img alt="" src="https://framerusercontent.com/images/dtDKjP7q5nU1Oh0VCEyezcE20.png"><p dir="ltr"><em>एक ट्रांसक्रिप्शन API प्रतिक्रिया की संरचना: ट्रांसक्रिप्ट, शब्द-स्तरीय टाइमस्टैम्प और विश्वसनीयता स्कोर</em></p><h2 dir="ltr">स्पीकर डायराइजेशन: यह जानना कि किसने क्या कहा</h2><p dir="ltr">सिंगल-स्पीकर ऑडियो काफी आसान होता है। मीटिंग्स, पॉडकास्ट और सपोर्ट कॉल्स जैसी जगहों पर चीजें दिलचस्प हो जाती हैं, क्योंकि केवल "क्या कहा गया" पर्याप्त नहीं होता, बल्कि "किसने कहा" यह भी जानना जरूरी होता है। इसे डायराइजेशन कहा जाता है, और आप आमतौर पर अपने अनुरोध मापदंडों में `diarize: True` के साथ इसे सक्षम करते हैं।</p><p dir="ltr">जब डायराइजेशन सक्षम होता है, तो Pulse शब्द-स्तरीय और वाक्य-स्तरीय आउटपुट में स्पीकर लेबल जोड़ता है, जिससे आप ट्रांसक्रिप्ट को एक बातचीत के रूप में फिर से तैयार कर सकते हैं।</p><pre data-language="JSX"><code>def format_diarized_transcript(response: dict) -&gt; str:
"""
डायराइज्ड वाक्यों को एक पठनीय वक्ता-दर-वक्ता ट्रांसक्रिप्ट में प्रारूपित करें।
"""
utterances = response.get("utterances", [])
lines = []

for utterance in utterances:
    speaker = utterance.get("speaker", "unknown_speaker")
    text = utterance.get("text", "").strip()
    start = utterance.get("start", 0)

    if not text:
        continue

    lines.append(f"[{start:.1f}s] {speaker}: {text}")

return "\n".join(lines)</code></pre><p dir="auto">लेकिन एक पेंच है: जब लोग एक-दूसरे के ऊपर बोलते हैं तो डायराइजेशन का प्रदर्शन कमजोर हो जाता है। कॉल-सेंटर ऑडियो में टोका-टाकी आम है, और इसका सबसे साफ समाधान अक्सर इनपुट स्तर पर ही होता है (जब संभव हो तो अलग-अलग चैनलों का उपयोग करें और फिर ट्रांसक्राइब करें) बजाय इसके कि आप मॉडल से क्रॉस-टॉक को पूरी तरह से सुलझाने की उम्मीद करें। स्पीकर डायराइजेशन पाइपलाइन्स गाइड में बहु-वक्ता रणनीतियों के बारे में गहराई से बताया गया है।</p><h2 dir="ltr">लंबी ऑडियो फ़ाइलों को संभालना और चंकिंग रणनीतियाँ</h2><p dir="ltr">ट्रांसक्रिप्शन API आमतौर पर फ़ाइल के आकार या अवधि पर सीमाएं लागू करते हैं। भले ही आपका API ऐसा न करता हो, फिर भी एक ही अनुरोध में 90 मिनट की रिकॉर्डिंग भेजना समस्याओं को न्यौता देना है: एक भी टाइमआउट हुआ और आप वापस शून्य पर आ जाएंगे। लंबी ऑडियो को छोटे टुकड़ों (chunks) में विभाजित करना पाइपलाइन को लचीला बनाए रखने का मानक तरीका है।</p><p dir="ltr">लंबी ऑडियो फ़ाइलों के लिए एक मजबूत चंकिंग रणनीति:</p><ul dir="auto"><li data-preset-tag="p"><p>`pydub` के `make_chunks` तरीके का उपयोग करके ऑडियो को 30-60 सेकंड के खंडों में विभाजित करें</p></li><li data-preset-tag="p"><p>सीमाओं पर शब्दों को कटने से बचाने के लिए टुकड़ों के बीच 1-2 सेकंड का ओवरलैप जोड़ें</p></li><li data-preset-tag="p"><p>प्रत्येक टुकड़े को स्वतंत्र रूप से ट्रांसक्राइब करें और परिणामों को क्रम से एकत्र करें</p></li><li data-preset-tag="p"><p>एक साधारण स्ट्रिंग संरेखण (alignment) जांच का उपयोग करके ओवरलैप क्षेत्र में डुप्लिकेट शब्दों को हटाकर ट्रांसक्रिप्ट को मर्ज करें</p></li><li data-preset-tag="p"><p>मूल फ़ाइल में इसकी शुरुआती स्थिति के आधार पर प्रत्येक टुकड़े के शब्द टाइमस्टैम्प को ऑफ़सेट करके वैश्विक टाइमस्टैम्प को सुरक्षित रखें</p></li></ul><pre data-language="JSX"><code>from pydub import AudioSegment
</code></pre>
<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>लंबी ऑडियो को ओवरलैपिंग टुकड़ों में विभाजित करें।<br>डिफ़ॉल्ट: 2-सेकंड के ओवरलैप के साथ 60-सेकंड के टुकड़े।<br>"""<br>audio = AudioSegment.from_file(input_path)<br>chunk_paths = []</p>
<pre><code>start = 0
chunk_index = 0

while start &lt; len(audio):
    end = min(start + chunk_length_ms, len(audio))
    chunk = audio[start:end]

    chunk_path = f"{output_dir}/chunk_{chunk_index:04d}.wav"
    chunk.export(chunk_path, format="wav")

    chunk_paths.append(chunk_path)

    if end == len(audio):
        break

    start = end - overlap_ms
    chunk_index += 1

return chunk_paths</code></pre><p dir="auto">यह ओवरलैप "आमतौर पर काम करता है" और सीमाओं पर अनुमानित रूप से काम करने वाले सिस्टम के बीच का अंतर है। इसके बिना, सीमा पर आने वाले शब्द कट जाते हैं और या तो गायब हो जाते हैं या विकृत होकर वापस आते हैं। एक सेकंड का ओवरलैप प्रसंस्करण लागत को बमुश्किल ही बदलता है, लेकिन यह त्रुटियों की एक पूरी श्रेणी को समाप्त कर देता है। यदि आप लहजे (accents), कोड-स्विचिंग या बहुभाषी ऑडियो से निपट रहे हैं, तो बहुभाषी ऑडियो के लिए स्पीच-टू-टेक्स्ट गाइड इन अतिरिक्त चुनौतियों को विस्तार से बताती है।</p><p dir="ltr"><br></p><img alt="" src="https://framerusercontent.com/images/kNmRu0cKJzv6BL8WUs5gs9a6DpM.png"><p dir="ltr"><em>ओवरलैपिंग खंडों के साथ लंबी ऑडियो को विभाजित करना स्प्लिट पॉइंट पर होने वाली गलतियों को रोकता है</em></p><h2 dir="ltr">उत्पादन संबंधी विचार: त्रुटि प्रबंधन (Error Handling), पुनः प्रयास (Retries), और लागत नियंत्रण</h2><p dir="ltr">लैपटॉप पर चलने वाली स्क्रिप्ट सिर्फ एक डेमो है; उत्पादन (production) वह जगह है जहाँ वास्तविक चुनौतियाँ सामने आती हैं। दर सीमाएं (Rate limits) लागू होती हैं, नेटवर्क में उतार-चढ़ाव होता है, और उपयोगकर्ता ऐसे प्रारूपों में ऑडियो अपलोड करते हैं जिनकी आपने योजना नहीं बनाई थी (या ऐसी रिकॉर्डिंग जो बहुत अधिक लंबी होती हैं)। यदि आप इन तीन चीजों की पहले से योजना बना लेते हैं, तो बाकी सब सिर्फ इंजीनियरिंग है।</p><p dir="ltr">दर सीमाओं और अस्थायी विफलताओं के लिए, एक्सपोनेंशियल बैकऑफ़ का उपयोग करें। `tenacity` इसे व्यवस्थित रखता है: `@retry(wait=wait_exponential(multiplier=1, min=2, max=30), stop=stop_after_attempt(5))`। इस डेकोरेटर को अपने API कॉल पर लागू करें और आप बिना खुद की पुनः प्रयास प्रणाली लिखे अधिकांश अस्थायी समस्याओं को आसानी से संभाल लेंगे।</p><pre data-language="JSX"><code>pip install tenacity
</code></pre>
<p>import os<br>import requests<br>from dotenv import load_dotenv<br>from tenacity import retry, stop_after_attempt, wait_exponential</p>
<p>load_dotenv()</p>
<p>@retry(<br>wait=wait_exponential(multiplier=1, min=2, max=30),<br>stop=stop_after_attempt(5),<br>)<br>def transcribe_with_retries(file_path: str) -> dict:<br>"""<br>अस्थायी API या नेटवर्क विफलताओं के लिए पुनः प्रयासों के साथ ऑडियो ट्रांसक्राइब करें।<br>"""<br>api_key = os.getenv("SMALLEST_API_KEY")</p>
<pre><code>if not api_key:
    raise ValueError("पर्यावरण चरों में SMALLEST_API_KEY मौजूद नहीं है।")

url = "https://api.smallest.ai/waves/v1/pulse/get_text"

params = {
    "language": "en",
    "word_timestamps": "true",
    "diarize": "false",
}

headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "audio/wav",
}

with open(file_path, "rb") as audio_file:
    response = requests.post(
        url,
        headers=headers,
        params=params,
        data=audio_file,
        timeout=120,
    )

response.raise_for_status()
return response.json()</code></pre><p dir="auto">लागत उत्पादन में आने वाली एक और अप्रत्याशित चुनौती है। अधिकांश ट्रांसक्रिप्शन API प्रति मिनट के हिसाब से शुल्क लेते हैं, जिसका अर्थ है कि बिना सोचे-समझे इसे चलाना जल्दी ही महंगा साबित हो सकता है। दो आदतें खर्च को नियंत्रण में रखती हैं: अपलोड करने से पहले अवधि की जांच करें (और ऐप स्तर पर अपनी सीमा से अधिक की फ़ाइलों को अस्वीकार करें), और परिणामों को कैश करें ताकि एक ही फ़ाइल दो बार ट्रांसक्राइब न हो। ऑडियो का एक कंटेंट हैश एक व्यावहारिक कैश कुंजी बनाता है।</p><p dir="ltr">यदि आप बड़े पैमाने पर निर्माण कर रहे हैं, तो स्पीच-टू-टेक्स्ट गाइड उच्च-थ्रूपुट आर्किटेक्चर, एसिंक वर्कर्स, कतारों (queues) और उन पैटर्नों पर चर्चा करती है जो लंबे समय तक चलने वाली पाइपलाइनों को स्थिर रखते हैं। </p><h2 dir="ltr">अधिकांश डेवलपर्स ट्रांसक्रिप्शन सटीकता के बारे में क्या गलत समझते हैं</h2><p dir="ltr">5% WER सुनने में बहुत छोटा लगता है जब तक कि आप इसका अनुवाद न करें: इसका मतलब है कि लगभग हर 20 में से 1 शब्द गलत है। 500 शब्दों की मीटिंग सारांश में, यह लगभग 25 त्रुटियां हैं। यहाँ तक कि अत्याधुनिक मॉडल्स भी शोर-शराबे वाली, स्वाभाविक बातचीत के दौरान साफ-सुथरी बेंचमार्क स्थितियों की तुलना में काफी अधिक शब्द त्रुटि दर (कभी-कभी 20% से अधिक) दिखाते हैं, यही वजह है कि अपने खुद के ऑडियो पर परीक्षण करना अनिवार्य है।</p><p dir="ltr">इसलिए पूरी गंभीरता से बेंचमार्क जांच करें। अपने API का परीक्षण उस ऑडियो पर करें जो आपके वास्तविक उत्पाद से मेल खाता हो, न कि साफ-सुथरे डेमो क्लिप्स पर। वास्तविक वातावरण से 10-15 मिनट का ऑडियो लें, सटीकता मापें और उसके बाद ही कोई निर्णय लें। विशिष्ट शब्द ही वह जगह हैं जहाँ सामान्य मॉडल सबसे अधिक लड़खड़ाते हैं - जैसे चिकित्सा शब्द, उत्पाद के नाम या आंतरिक संक्षिप्त नाम (acronyms)। यदि आपका सेवा प्रदाता कस्टम शब्दावली या डोमेन अनुकूलन प्रदान करता है, तो विशिष्ट शब्दावली शामिल होने पर इसका उपयोग करें।</p><h2 dir="ltr">सारांश और अगले कदम</h2><p dir="ltr">पायथन में एक भरोसेमंद ऑडियो-टू-टेक्स्ट पाइपलाइन आमतौर पर चार नियमों पर टिकी होती है: API के पास जाने से पहले ऑडियो को नॉर्मलाइज़ करें, प्रतिक्रिया को संरचित डेटा के रूप में मानें (न कि केवल एक स्ट्रिंग के रूप में), लंबी रिकॉर्डिंग को ओवरलैप के साथ विभाजित करें, और पुनः प्रयास व त्रुटि प्रबंधन को बुनियादी विशेषता के रूप में शामिल करें।</p><p dir="ltr">यहाँ दिए गए कोड स्निपेट्स को जानबूझकर छोटा रखा गया है ताकि आप उन्हें बिना किसी बड़े बदलाव के अपने सिस्टम में जोड़ सकें। जैसे-जैसे इसका उपयोग बढ़ेगा, आप शायद एसिंक प्रोसेसिंग, एक जॉब कतार और परिणामों के लिए सुरक्षित स्टोरेज जोड़ेंगे, लेकिन मूल प्रवाह नहीं बदलता है।</p><p dir="ltr">यदि आप स्पीच-टू-टेक्स्ट प्रदाताओं की तुलना कर रहे हैं, तो Smallest.ai का Pulse विशेष रूप से उन डेवलपर्स के लिए बनाया गया है जो कम-विलंबता, ट्रांसक्रिप्शन गुणवत्ता और आसानी से एकीकृत होने वाले API को प्राथमिकता देते हैं। यह डिफ़ॉल्ट रूप से स्ट्रीमिंग ट्रांसक्रिप्शन, स्पीकर डायराइजेशन, शब्द-स्तरीय टाइमस्टैम्प और बहुभाषी ऑडियो का समर्थन करता है, जो ऊपर बताए गए उत्पादन पैटर्नों के अनुकूल है। आज ही पायथन में ऑडियो ट्रांसक्राइब करना शुरू करने के लिए Pulse और Waves API का अन्वेषण करें।</p><p dir="ltr"><br></p><img alt="" src="https://framerusercontent.com/images/3mHIcVXitoVvibRxtOXPqtKysgs.png"><p dir="ltr"><em>पायथन में प्रोडक्शन-रेडी ट्रांसक्रिप्शन पाइपलाइन के चार मुख्य स्तंभ</em></p>
</code></pre>