اگر realtime فارسی می‌خواهی، Speechmatics را با این کد اجرا کن

برای توسعه‌دهندهٔ پایتون که می‌خواهد صدای میکروفن را به متن فارسی زنده تبدیل کند، این نمونه مستقیماً به WebSocket بلادرنگ Speechmatics وصل می‌شود. خروجی موقت و متن نهایی را در ترمینال می‌بینی.

نتیجهٔ عملی: با اسکریپت زیر، توسعه‌دهندهٔ پایتون می‌تواند صدای میکروفن را با زبان fa به سرویس realtime Speechmatics بفرستد و «متن موقت» و «متن نهایی» فارسی را همان لحظه در ترمینال ببیند. تنها پیش‌نیازها یک API key معتبر Speechmatics، میکروفن، و Python 3 هستند.

مسئلهٔ دقیق: میکروفن محلی را به متن فارسی زنده تبدیل کن

این راهنما برای توسعه‌دهندهٔ پایتون است که می‌خواهد پیش از ساخت رابط وب یا محصول کامل، مسیر اصلی را آزمایش کند: صوت خام میکروفن → WebSocket → متن فارسی. این انتخاب عمداً فایل صوتی، ضبط دائمی، ترجمه و تشخیص گوینده را کنار می‌گذارد تا بتوانی اتصال realtime فارسی را جداگانه و قابل‌مشاهده بررسی کنی.

در WebSocket بلادرنگ، ابتدا پیام StartRecognition شامل فرمت صوت و تنظیمات رونویسی ارسال می‌شود. سپس بایت‌های صوت PCM به‌صورت پیام باینری می‌روند. پاسخ‌های AddPartialTranscript هنوز ممکن است تغییر کنند؛ AddTranscript را باید متن نهایی‌شدهٔ بخش گفتار دانست. بنابراین در رابط کاربری واقعی، متن موقت و نهایی را در یک متغیر واحد بدون سیاست جایگزینی ذخیره نکن.

راه‌اندازی و اجرای نمونه

یک API key را از حساب Speechmatics بگیر و آن را فقط در متغیر محیطی نگه دار، نه در کد یا مخزن Git. نمونه از websocket-client برای اتصال WebSocket و از sounddevice برای خواندن بافرهای خام میکروفن استفاده می‌کند. نرخ ۱۶۰۰۰، تک‌کاناله و int16 عمداً با audio_format ارسالی یکسان انتخاب شده‌اند؛ ناسازگاری این دو، یکی از علت‌های رایج خروجی بی‌معنا یا خطای سرویس است.

```python
# file: realtime_fa.py
# Input: صدای گفتار فارسی از میکروفن پیش‌فرض، مثلاً: «سلام، امروز هوا خوب است.»
# Expected output (نمونه):
# [partial] سلام امروز
# [final] سلام، امروز هوا خوب است.
#
# Install:
# python -m pip install sounddevice websocket-client
# Run (Linux/macOS):
# SPEECHMATICS_API_KEY='YOUR_KEY' python realtime_fa.py
# Run (PowerShell):
# $env:SPEECHMATICS_API_KEY='YOUR_KEY'; python realtime_fa.py

import json
import os
import threading

import sounddevice as sd
import websocket

API_KEY = os.environ["SPEECHMATICS_API_KEY"]
URL = "wss://eu2.rt.speechmatics.com/v2"
SAMPLE_RATE = 16000
CHANNELS = 1
BLOCKSIZE = 3200 # 200 ms at 16 kHz


def transcript_text(message):
# Speechmatics returns recognized tokens in results.
tokens = []
for result in message.get("results", []):
alternatives = result.get("alternatives", [])
if alternatives:
tokens.append(alternatives[0].get("content", ""))
return " ".join(token for token in tokens if token).strip()


def receive_messages(ws):
try:
while True:
raw = ws.recv()
if not raw:
return
message = json.loads(raw)
kind = message.get("message")
if kind in ("AddPartialTranscript", "AddTranscript"):
label = "partial" if kind == "AddPartialTranscript" else "final"
text = transcript_text(message)
if text:
print(f"[{label}] {text}", flush=True)
elif kind == "Error":
print("Speechmatics error:", message, flush=True)
return
except Exception as error:
print("Receive stopped:", error, flush=True)


ws = websocket.create_connection(
URL,
header={"Authorization": f"Bearer {API_KEY}"},
)

ws.send(json.dumps({
"message": "StartRecognition",
"audio_format": {
"type": "raw",
"encoding": "pcm_s16le",
"sample_rate": SAMPLE_RATE,
},
"transcription_config": {
"language": "fa",
"enable_partials": True,
"max_delay": 2,
},
}))

threading.Thread(target=receive_messages, args=(ws,), daemon=True).start()
print("اکنون فارسی صحبت کن؛ برای پایان Ctrl+C بزن.")

try:
def send_audio(indata, frames, time, status):
if status:
print("Audio status:", status, flush=True)
ws.send(bytes(indata), opcode=websocket.ABNF.OPCODE_BINARY)

with sd.RawInputStream(
samplerate=SAMPLE_RATE,
blocksize=BLOCKSIZE,
channels=CHANNELS,
dtype="int16",
callback=send_audio,
):
threading.Event().wait()
except KeyboardInterrupt:
print("\nدر حال بستن جریان صوت…")
finally:
try:
ws.send(json.dumps({"message": "EndOfStream"}))
finally:
ws.close()
```

پس از نصب وابستگی‌ها، دستور اجرا را با کلید خودت بزن و یک جملهٔ کوتاه فارسی بگو. اگر اتصال و مجوز درست باشند، ابتدا ممکن است چند خط partial ببینی و پس از مکث در گفتار، یک خط final ظاهر می‌شود. خروجی دقیق به گفتار، نویز، و تصمیم نهایی سرویس وابسته است؛ متن درج‌شده در کامنت کد فقط شکل مورد انتظار خروجی را نشان می‌دهد، نه یک تضمین واژه‌به‌واژه.

چرا این جزئیات مهم‌اند

کلید language برابر fa است؛ پیش از تکیه بر آن در محصول، صفحهٔ زبان‌های پشتیبانی‌شده را بررسی کن، چون پشتیبانی ویژگی‌ها می‌تواند میان زبان‌ها و مدل‌ها فرق داشته باشد. enable_partials برای تجربهٔ زنده لازم است، اما متن آن ناپایدار است: کاربر ممکن است ابتدا یک عبارت ببیند و با رسیدن صوت بیشتر همان عبارت اصلاح شود. برای ثبت یادداشت، زیرنویس یا ارسال به پایگاه داده، AddTranscript انتخاب امن‌تر است.

max_delay=2 یک مصالحهٔ مشخص است: تأخیر کمتر، متن زودتر می‌دهد اما فرصت کمتری برای کامل‌شدن عبارت دارد؛ تأخیر بیشتر معمولاً متن باثبات‌تری می‌دهد اما حس زنده‌بودن را کم می‌کند. برای نمایش زیرنویس تعاملی، ابتدا همین مقدار را آزمایش کن. برای یادداشت جلسه که چند ثانیه تأخیر قابل‌قبول دارد، مقدار بالاتر می‌تواند انتخاب بهتری باشد. هیچ عدد ثابتی برای همهٔ میکروفن‌ها، شبکه‌ها و سبک‌های گفتار درست نیست.

خطاهای رایج و زمانی که این راه غلط است

اگر برنامه با خطای دستگاه صوتی اجرا نشد، میکروفن پیش‌فرض احتمالاً نرخ ۱۶ کیلوهرتز را نمی‌پذیرد. در آن وضعیت، این اسکریپت را با تغییر تصادفی sample_rate «درست» نکن؛ audio_format و فرمت دادهٔ واقعی باید با هم منطبق بمانند. یا دستگاه/تنظیم صوتی مناسب انتخاب کن، یا پیش از ارسال، صوت را با یک مرحلهٔ resampling معتبر به PCM شانزده‌بیتی ۱۶ کیلوهرتز تبدیل کن.

این نمونه برای اثبات مسیر فنی است، نه برای اجرای production. callback میکروفن مستقیماً روی WebSocket می‌نویسد؛ اگر شبکه کند شود، ممکن است ارسال صوت عقب بماند. در برنامهٔ واقعی، صوت را در صف محدود قرار بده، ارسال شبکه را در نخ یا task جدا انجام بده، سیاست حذف یا توقف هنگام پرشدن صف تعریف کن، و اتصال مجدد را با شروع یک جلسهٔ تشخیص تازه مدیریت کن. همچنین کلید را هرگز به کلاینت مرورگر یا logها نفرست.

اگر ورودی تو فایل صوتی از پیش ضبط‌شده است و «همین لحظه» به خروجی نیاز نداری، realtime انتخاب نادرستی است: پردازش batch معمولاً کنترل ساده‌تری بر فایل، تکرارپذیری و مدیریت خطا می‌دهد. اگر برعکس، هدف مرورگر است، صدای مرورگر اغلب با فرمت و نرخ دیگری می‌آید و این کد پایتونِ میکروفن محلی را نباید مستقیم به JavaScript کپی کرد. در آن حالت، قرارداد WebSocket و تبدیل صوت را برای محیط مرورگر جداگانه پیاده‌سازی کن.

انتخاب بین اتصال خام و SDK

اتصال خام این مقاله برای دیباگ‌کردن مفید است: دقیقاً می‌بینی چه پیام شروعی، چه بایت صوتی و چه پیام پایانی ردوبدل می‌شود و تنها دو وابستگی کوچک داری. در مقابل، اگر محصولت به مدیریت اتصال، الگوهای سطح بالاتر یا نگهداری کمتر از جزئیات پروتکل نیاز دارد، ابتدا مخزن رسمی speechmatics-python را بررسی کن. معیار تصمیم فقط این است: برای یک آزمایش و فهم پروتکل، اتصال خام شفاف‌تر است؛ برای کد محصولی که می‌خواهی با API رسمی همگام بماند، SDK رسمی معمولاً نقطهٔ شروع مناسب‌تری است.

منابع

Speechmatics Python SDK repository — https://github.com/speechmatics/speechmatics-python
Speechmatics real-time transcription API reference — https://docs.speechmatics.com/api-ref/realtime-transcription
Speechmatics supported languages — https://docs.speechmatics.com/features/supported-languages
websocket-client documentation — https://websocket-client.readthedocs.io/en/latest/
python-sounddevice documentation — https://python-sounddevice.readthedocs.io/

No comments yet