Python
انسخ الصوت، وابنِ الخطوط الزمنية للمتحدثين، وولّف الكلام من Python باستخدام humain-voice 0.18.1.
التثبيت
python -m pip install humain-voice==0.18.1اضبط عميلًا
لكل سير عمل عميله الخاص؛ استورد stt وtts وagent من humain_voice. يأخذ كل عميل
هذه الوسائط المسماة:
| الاسم | النوع | الافتراضي | المعنى |
|---|---|---|---|
api_url | str | مطلوب | عنوان الخدمة الأساسي. |
api_key | str | مطلوب | مفتاح API. |
api_path | str | /socket.io | مسار Socket.IO. لكل عميل عدا النسخ الدفعي. |
api_version | str | v1 | إصدار REST. لـBatchTranscribeClient فقط. |
تقرأ الأمثلة هذه القيم من API_URL وAPI_KEY وAPI_PATH وAPI_VERSION؛ راجع
إعدادات الاتصال.
| سير العمل | العميل | التنظيف بـ |
|---|---|---|
| النسخ الدفعي | stt.BatchTranscribeClient | close() |
| النسخ السريع | stt.FastTranscriptionClient | close() |
| النسخ الفوري | stt.RealtimeClient | disconnect() |
| التمييز المباشر | stt.RealtimeDiarizationClient | disconnect() |
| تحويل النص إلى كلام | tts.TTSClient | close() |
| جلسات Voice Agent | agent.AgentClient | close() |
افتح كل عميل بـasync with؛ يتصل عملاء Socket.IO عند الدخول، فيفشل الاتصال هناك عند خطأ في المفتاح.
يجب أن تكون دوال الاستدعاء المرتد دوال عادية غير حاجبة: لا ينتظرها SDK. قيم اللغات والنماذج
في النماذج والأصوات.
المتغيرات المتزامنة وغير المتزامنة
طرق العميل كوروتينات. ولبعضها نظير حاجب بالملحق _sync:
| العميل | الطرق المتزامنة |
|---|---|
BatchTranscribeClient | submit_sync(), get_result_sync(), transcribe_sync(), close_sync() |
FastTranscriptionClient | transcribe_sync(), close_sync() |
RealtimeClient | start_stream_sync()؛ وفي التدفق send_sync(), close_sync(), stop_sync() |
RealtimeDiarizationClient | start_stream_sync()؛ وفي التدفق send_sync(), close_sync() |
TTSClient | list_voices_sync(), synthesize_sync(), close_sync() |
AgentClient | create_session_sync(), close_sync() |
استخدم طرق _sync من الشيفرة المتزامنة فقط، مع with عادية، ولا تخلطها مع
الكوروتينات على العميل نفسه.
النسخ الدفعي
يرفع transcribe(audio, lang, ...) ملفًا كاملًا، ويستعلم دوريًا حتى تصبح المهمة done، ثم يعيد
النص المنسوخ مع إزاحات الكلمات. للاستعلام الدوري من عامل خلفي، استدعِ submit(audio, lang, ...)، ثم
get_result(job_id, lang, save_result=False) حتى تصبح الحالة done أو failed أو cleared (راجع
النسخ الدفعي مهمة). الوسائط بعد lang بالاسم فقط.
| الاسم | النوع | الافتراضي | المعنى |
|---|---|---|---|
audio | bytes أو مسار (str أو Path) أو ملف ثنائي | مطلوب | الصوت المراد رفعه. |
lang | stt.Language أو str | مطلوب | اللغة المنطوقة. |
asr | stt.BatchTranscriptionModel أو str | None | نموذج ASR. |
diarization | BatchDiarization | None | On أو D1 أو D2 تسمّي المتحدثين. تعداد فقط. |
itn | bool | None | تطبيع النص العكسي. |
redact | BatchRedact | None | BatchRedact.On يفعّل الحجب. تعداد فقط. |
save_result | bool | False | أبقِ النتيجة قابلة للقراءة بعد جلبها؛ راجع اقرأ النتيجة مرة أخرى. ليس في submit(). |
poll_interval | float | 2.0 | الثواني بين قراءات النتيجة. لـtranscribe() فقط. |
timeout_seconds | float | 300.0 | حد الاستعلام الدوري بالثواني. لـtranscribe() فقط. |
on_progress | Callable[[TranscriptionResponse], None] | None | تُستدعى عند كل قراءة للنتيجة. لـtranscribe() فقط. |
استورد BatchDiarization وBatchRedact وTranscriptionResponse من
humain_voice.stt.batchtranscription.
from __future__ import annotations
import asyncio
import os
import sys
from pathlib import Path
from humain_voice import stt
from humain_voice.stt.batchtranscription import BatchDiarization
def required_env(name: str) -> str:
value = os.environ.get(name)
if not value:
raise RuntimeError(f"{name} is required")
return value
async def main() -> None:
input_path = Path(sys.argv[1] if len(sys.argv) > 1 else "recording.wav")
output_path = Path(sys.argv[2] if len(sys.argv) > 2 else "recording.vtt")
async with stt.BatchTranscribeClient(
api_url=required_env("API_URL"),
api_key=required_env("API_KEY"),
api_version=os.environ.get("API_VERSION", "v1"),
) as client:
result = await client.transcribe(
input_path,
lang=stt.Language.ArEn,
asr=stt.BatchTranscriptionModel.BayanArEn,
diarization=BatchDiarization.On,
save_result=True,
poll_interval=2.0,
timeout_seconds=300.0,
on_progress=lambda response: print("status:", response.status.value),
)
print(result.results.transcript if result.results else "")
output_path.write_text(
stt.Subtitles.from_response(result).to_vtt(),
encoding="utf-8",
)
if __name__ == "__main__":
asyncio.run(main())
الخرج المتوقع (توضيحي):
status: queued
status: processing
status: done
Hello and welcome to the meeting.عند تفعيل diarization، تحمل كل إزاحة كلمة تسمية speaker. يجمّع هذا المثال الكلمات في
أدوار المتحدثين:
from __future__ import annotations
import asyncio
import os
import sys
from pathlib import Path
from humain_voice import stt
from humain_voice.stt.batchtranscription import BatchDiarization
def required_env(name: str) -> str:
value = os.environ.get(name)
if not value:
raise RuntimeError(f"{name} is required")
return value
async def main() -> None:
input_path = Path(sys.argv[1] if len(sys.argv) > 1 else "recording.wav")
async with stt.BatchTranscribeClient(
api_url=required_env("API_URL"),
api_key=required_env("API_KEY"),
api_version=os.environ.get("API_VERSION", "v1"),
) as client:
result = await client.transcribe(
input_path,
lang=stt.Language.ArEn,
asr=stt.BatchTranscriptionModel.BayanArEn,
diarization=BatchDiarization.On,
save_result=True,
timeout_seconds=300.0,
on_progress=lambda response: print("status:", response.status.value),
)
turns: list[tuple[str, list[str]]] = []
for offset in result.results.offsets if result.results else []:
speaker = offset.speaker or "UNKNOWN_SPEAKER"
if turns and turns[-1][0] == speaker:
turns[-1][1].append(offset.word)
else:
turns.append((speaker, [offset.word]))
for speaker, words in turns:
print(f"{speaker}: {' '.join(words)}")
if __name__ == "__main__":
asyncio.run(main())
الخرج المتوقع (توضيحي؛ التسميات سلاسل معتمة):
status: processing
status: done
SPEAKER_1: Hello and welcome to the meeting.
SPEAKER_2: Thanks for having me.النسخ السريع
يرسل FastTranscriptionClient.transcribe(audio_source, language, asr_model, ...) مقطعًا واحدًا قصيرًا
كاملًا عبر Socket.IO ويعيد النتيجة النهائية. أرسل التسجيلات الأطول إلى النسخ الدفعي؛ راجع
حدود النسخ السريع.
| الاسم | النوع | الافتراضي | المعنى |
|---|---|---|---|
audio_source | bytes أو ملف ثنائي | مطلوب | المقطع المراد نسخه. |
language | stt.Language | مطلوب | اللغة المنطوقة. |
asr_model | stt.FastTranscriptionModel أو str | مطلوب | نموذج ASR. |
on_response | قابل للاستدعاء | None | يستقبل النتائج الجزئية، ثم النهائية. |
on_file_upload | قابل للاستدعاء | None | يستقبل إيصال الرفع. |
on_error | قابل للاستدعاء | None | يستقبل ErrorResponse. |
timeout_seconds | float | 60.0 | انتظار النتيجة النهائية. |
from __future__ import annotations
import asyncio
import os
import sys
from pathlib import Path
from humain_voice import stt
def required_env(name: str) -> str:
value = os.environ.get(name)
if not value:
raise RuntimeError(f"{name} is required")
return value
def handle_response(response: stt.FtTranscribeResponse) -> None:
kind = "final" if response.is_final else "partial"
print(f"{kind}:", response.transcription)
def handle_upload(response: stt.FileUploadedResponse) -> None:
print("status:", "uploaded", response.id)
def handle_error(error: stt.ErrorResponse | None) -> None:
if error is not None:
print("error:", error.code, error.message, file=sys.stderr)
async def main() -> None:
input_path = Path(sys.argv[1] if len(sys.argv) > 1 else "recording.wav")
output_path = Path(sys.argv[2] if len(sys.argv) > 2 else "recording.vtt")
async with stt.FastTranscriptionClient(
api_url=required_env("API_URL"),
api_key=required_env("API_KEY"),
api_path=os.environ.get("API_PATH"),
) as client:
result = await client.transcribe(
input_path.read_bytes(),
stt.Language.ArEn,
stt.FastTranscriptionModel.BayanArEn,
on_response=handle_response,
on_file_upload=handle_upload,
on_error=handle_error,
timeout_seconds=60.0,
)
if result is None:
raise RuntimeError("Fast transcription ended without a final result")
output_path.write_text(
stt.Subtitles.from_response(result).to_vtt(),
encoding="utf-8",
)
if __name__ == "__main__":
asyncio.run(main())
الخرج المتوقع (توضيحي):
status: uploaded 3f1c2a9e-5b7d-4e8a-9c41-0d2e6f8b7a15
partial: Hello and
final: Hello and welcome to the meeting.النسخ الفوري
يفتح RealtimeClient.start_stream(language, ...) تدفقًا. أرسل صوت PCM16 بترتيب little-endian وبتردد 16 kHz، أحادي
القناة، عبر stream.send()، ثم استدعِ stream.close() لانتظار is_final؛ أما stream.stop() فتنهي
دون انتظار. راجع نتائج البث حالة وليست سجلًا.
| الاستدعاء | المعامل | النوع | الافتراضي | المعنى |
|---|---|---|---|---|
start_stream() | language | stt.Language | مطلوب | اللغة المنطوقة. |
start_stream() | on_response | قابل للاستدعاء | None | يستقبل النتائج المؤقتة والنهائية. |
start_stream() | on_error | قابل للاستدعاء | None | يستقبل ErrorResponse. |
stream.send() | audio_bytes | bytes | مطلوب | قطعة صوت واحدة. |
stream.close() | timeout_seconds | float | 1.0 | انتظار is_final. مرّر 5.0. |
يرسل المثال قطعًا من 3,200 بايت (100 ms) ويكتب التسميات التوضيحية من الكلمات النهائية. لإنشاء
recording.pcm، راجع جهّز الصوت.
from __future__ import annotations
import asyncio
import os
import sys
from pathlib import Path
from humain_voice import stt
CHUNK_BYTES = 3_200 # 100 ms of PCM16LE, 16 kHz, mono audio.
def required_env(name: str) -> str:
value = os.environ.get(name)
if not value:
raise RuntimeError(f"{name} is required")
return value
async def main() -> None:
input_path = Path(sys.argv[1] if len(sys.argv) > 1 else "recording.pcm")
output_path = Path(sys.argv[2] if len(sys.argv) > 2 else "recording.vtt")
finalized_words: list[stt.WordSegment] = []
server_error: stt.ErrorResponse | None = None
protocol_final_observed = False
def handle_response(response: stt.RtTranscribeResponse) -> None:
nonlocal protocol_final_observed
if response.is_final:
kind = "final"
elif response.is_speech_final:
kind = "speech-final"
else:
kind = "partial"
print(f"{kind}:", response.transcription)
if response.is_final:
protocol_final_observed = True
if response.is_final or response.is_speech_final:
# seq is not guaranteed to increase, so keep words in arrival order.
finalized_words.extend(response.words)
def handle_error(error: stt.ErrorResponse | None) -> None:
nonlocal server_error
if error is not None:
print("error:", error.code, error.message, file=sys.stderr)
server_error = error
async with stt.RealtimeClient(
api_url=required_env("API_URL"),
api_key=required_env("API_KEY"),
api_path=os.environ.get("API_PATH"),
) as client:
stream = await client.start_stream(
language=stt.Language.ArEn,
on_response=handle_response,
on_error=handle_error,
)
pcm = input_path.read_bytes()
try:
for offset in range(0, len(pcm), CHUNK_BYTES):
if server_error is not None:
break
await stream.send(pcm[offset : offset + CHUNK_BYTES])
await asyncio.sleep(0.1)
# Returns (does not raise) if is_final has not arrived within 5 s.
if server_error is None:
await stream.close(timeout_seconds=5.0)
except Exception:
# The SDK drops the stream on a server error, so send() and close() raise.
if server_error is None:
raise
if server_error is not None:
raise RuntimeError(server_error.message or server_error.code or "Realtime stream failed")
if not protocol_final_observed:
raise RuntimeError("Realtime stream ended before protocol is_final")
output_path.write_text(
stt.Subtitles.from_words(finalized_words).to_vtt(),
encoding="utf-8",
)
if __name__ == "__main__":
asyncio.run(main())
الخرج المتوقع (توضيحي):
partial: Hello and
speech-final: Hello and welcome to the meeting.
partial: Let's start
final: Let's start with the agenda.التمييز المباشر
يبلّغ RealtimeDiarizationClient.start_stream(on_update=...) عمّن يتحدث أثناء send() لصوت PCM
بصيغة النسخ الفوري على قطع من 15,360 بايت (480 ms)، وهي DIARIZATION_RECOMMENDED_CHUNK_BYTES. يحمل كل
DiarizationUpdate الخط الزمني الكامل في segments والمقاطع النهائية الجديدة في
newly_finalized. يعيد stream.close(timeout_seconds=5.0) الخط الزمني النهائي، ويحوّله
stt.to_rttm() إلى RTTM.
from __future__ import annotations
import asyncio
import os
import sys
from pathlib import Path
from humain_voice import stt
from humain_voice.stt.constants import DIARIZATION_RECOMMENDED_CHUNK_BYTES
def required_env(name: str) -> str:
value = os.environ.get(name)
if not value:
raise RuntimeError(f"{name} is required")
return value
def handle_error(error: stt.ErrorResponse | None) -> None:
if error is not None:
print("error:", error.code, error.message, file=sys.stderr)
async def main() -> None:
input_path = Path(sys.argv[1] if len(sys.argv) > 1 else "recording.pcm")
output_path = Path(sys.argv[2] if len(sys.argv) > 2 else "recording.rttm")
async with stt.RealtimeDiarizationClient(
api_url=required_env("API_URL"),
api_key=required_env("API_KEY"),
api_path=os.environ.get("API_PATH"),
) as client:
final_observed = False
def on_update(update: stt.DiarizationUpdate) -> None:
nonlocal final_observed
final_observed = final_observed or update.is_final
for segment in update.newly_finalized:
print(segment.speaker, segment.start_time, segment.end_time)
stream = await client.start_stream(
on_update=on_update,
on_error=handle_error,
)
pcm = input_path.read_bytes()
if not pcm or len(pcm) % 2:
raise ValueError("Input must be nonempty PCM16 with an even byte length")
for offset in range(0, len(pcm), DIARIZATION_RECOMMENDED_CHUNK_BYTES):
await stream.send(
pcm[offset : offset + DIARIZATION_RECOMMENDED_CHUNK_BYTES]
)
await asyncio.sleep(0.48)
# Returns the best-known timeline after 5 s even without a final update.
timeline = await stream.close(timeout_seconds=5.0)
destination = output_path if final_observed else Path(f"{output_path}.partial")
destination.write_text(stt.to_rttm(timeline, uri="recording"), encoding="utf-8")
if not final_observed:
print("status:", f"Final result not observed; wrote incomplete output to {destination}")
if __name__ == "__main__":
asyncio.run(main())
الخرج المتوقع (توضيحي):
SPEAKER_01 0.0 3.84
SPEAKER_02 3.84 7.2
SPEAKER_01 7.2 11.52تحويل النص إلى كلام
يعيد TTSClient صوت PCM16 خامًا بترتيب little-endian أحادي القناة بتردد tts.get_sample_rate(model) Hz (24,000
للنموذج الافتراضي TtsModel.Nebula). يعيد list_voices(timeout_seconds=None) قواميس تحوي
id وlabel، وكذلك profile عند توفره:
from __future__ import annotations
import asyncio
import os
from humain_voice import tts
def required_env(name: str) -> str:
value = os.environ.get(name)
if not value:
raise RuntimeError(f"{name} is required")
return value
async def main() -> None:
async with tts.TTSClient(
api_url=required_env("API_URL"),
api_key=required_env("API_KEY"),
api_path=os.environ.get("API_PATH"),
) as client:
for voice in await client.list_voices(timeout_seconds=5.0):
dialect = ""
languages = ""
if profile := voice.get("profile"):
dialect = profile["speaker"]["dialect"]
languages = ",".join(profile["languages"])
print(voice["id"], voice["label"], dialect, languages)
if __name__ == "__main__":
asyncio.run(main())
الخرج المتوقع (توضيحي؛ تختلف المعرّفات بحسب البيئة):
42e38a63-849a-481a-b5bf-3c1b7a985de3 mul_nourah ars ar,en
af52a907-1086-46f7-8f5d-72317875d7bd mul_youssef arz ar,enفي الإصدار 0.18.1، أو 0.19.0b3 أو أحدث، قد يحوي profile أيضًا emotions وstyles (list[str]). ويغيبان حيث
لا تكون المشاعر وأسلوب الإلقاء مفعّلة، فاقرأهما بـprofile.get("emotions")؛ راجع
قائمة الأصوات.
يعيد synthesize(text, voice_id, ...) المقطع كاملًا بنوع bytes؛
ويُنتج synthesize_stream(text, voice_id, ...) قطع TtsAudioResponse (id وis_last و
audio). مرّر واحدًا فقط من voice_id أو voice_references. الوسائط بعد voice_id
بالاسم فقط.
| الاسم | النوع | الافتراضي | المعنى |
|---|---|---|---|
text | str | مطلوب | النص المراد نطقه. |
voice_id | str | None | معرّف الصوت من list_voices(). |
voice_references | list من {"text": str, "audio": str} | None | مقاطع مرجعية للاستنساخ؛ audio بصيغة WAV مشفرة base64. |
model | tts.TtsModel أو str | None (Nebula) | نموذج TTS. |
timeout_seconds | float أو None | None | انتظار كل قطعة تالية؛ None ينتظر إلى الأبد، فاضبطها دائمًا. |
on_audio | قابل للاستدعاء | None | يستقبل كل قطعة. لـsynthesize() فقط. |
on_error | قابل للاستدعاء | None | يستقبل ErrorResponse. |
request_id | uuid.UUID | None | معرّف الطلب؛ يُولَّد عند حذفه. |
يضيف هذا المثال ترويسة WAV بالوحدة wave ويكتب speech.wav:
from __future__ import annotations
import asyncio
import os
import sys
import wave
from pathlib import Path
from humain_voice import stt, tts
def required_env(name: str) -> str:
value = os.environ.get(name)
if not value:
raise RuntimeError(f"{name} is required")
return value
def write_pcm16_wav(path: Path, pcm: bytes, sample_rate: int) -> None:
with wave.open(str(path), "wb") as wav_file:
wav_file.setnchannels(1)
wav_file.setsampwidth(2)
wav_file.setframerate(sample_rate)
wav_file.writeframes(pcm)
def handle_error(error: stt.ErrorResponse | None) -> None:
if error is not None:
print("error:", error.code, error.message, file=sys.stderr)
async def main() -> None:
text = sys.argv[1] if len(sys.argv) > 1 else "Hello from HUMAIN Voice"
output_path = Path(sys.argv[2] if len(sys.argv) > 2 else "speech.wav")
async with tts.TTSClient(
api_url=required_env("API_URL"),
api_key=required_env("API_KEY"),
api_path=os.environ.get("API_PATH"),
) as client:
voices = await client.list_voices(timeout_seconds=5.0)
if not voices:
raise RuntimeError("No TTS voices are available")
voice = next((item for item in voices if item.get("profile")), voices[0])
if profile := voice.get("profile"):
print(
"status:",
"voice",
voice["label"],
profile["speaker"]["dialect"],
profile["languages"],
)
model = tts.TtsModel.Nebula
pcm = await client.synthesize(
text,
voice_id=voice["id"],
model=model,
# Inactivity timeout per audio chunk, not a total deadline.
timeout_seconds=30.0,
on_error=handle_error,
)
write_pcm16_wav(output_path, pcm, tts.get_sample_rate(model))
if __name__ == "__main__":
asyncio.run(main())
الخرج المتوقع (توضيحي):
status: voice mul_nourah ars ['ar', 'en']يبث هذا المثال الصوت إلى stdout:
python tts_stream.py "Hello from HUMAIN Voice" | ffplay -f s16le -ar 24000 -ch_layout mono -from __future__ import annotations
import asyncio
import os
import sys
from humain_voice import stt, tts
def required_env(name: str) -> str:
value = os.environ.get(name)
if not value:
raise RuntimeError(f"{name} is required")
return value
def handle_error(error: stt.ErrorResponse | None) -> None:
if error is not None:
print("error:", error.code, error.message, file=sys.stderr)
async def main() -> None:
text = sys.argv[1] if len(sys.argv) > 1 else "Hello from HUMAIN Voice"
model = tts.TtsModel.Nebula
async with tts.TTSClient(
api_url=required_env("API_URL"),
api_key=required_env("API_KEY"),
api_path=os.environ.get("API_PATH"),
) as client:
voices = await client.list_voices(timeout_seconds=5.0)
if not voices:
raise RuntimeError("No TTS voices are available")
# Audio goes to stdout, so logs go to stderr.
print("status: sample rate", tts.get_sample_rate(model), file=sys.stderr)
async for chunk in client.synthesize_stream(
text,
voice_id=voices[0]["id"],
model=model,
timeout_seconds=30.0,
on_error=handle_error,
):
sys.stdout.buffer.write(chunk.audio)
sys.stdout.buffer.flush()
if __name__ == "__main__":
asyncio.run(main())
الخرج المتوقع على stderr (توضيحي):
status: sample rate 24000راجع مخرجات الكلام لاختيار الوضع، و النماذج والأصوات للأصوات.
جلسات Voice Agent
يبدأ agent.AgentClient جلسات Voice Agent من خادمك. ويحتاج الإصدار التجريبي:
python -m pip install humain-voice==0.19.0b2يأخذ api_url وapi_key. ويرسل create_session()
طلب جلسة واحدًا:
| الاسم | النوع | الافتراضي | المعنى |
|---|---|---|---|
participant | dict يحمل identity، وname وgender اختياريين | مطلوب | المستخدم الذي ينضم إلى المكالمة. |
agent | dict | None | prompt وintro وvoice_id وclient_tools وtool_acknowledgments، كما في الطلب. |
variables | dict[str, str | int | float | bool] | None | قيم العناصر النائبة {{name}}. |
idempotency_key | str | None | يُرسل كـIdempotency-Key، فتعيد إعادة المحاولة الجلسة الأولى. |
timeout_seconds | float | 10.0 | مهلة الطلب. |
يعيد AgentSessionCredentials يحمل server_url وparticipant_token وsession_id
وexpires_at (datetime) وeffective (كائن effective من الاستجابة بصيغة dict) وlimits
(max_duration_s وidle_timeout_s؛ وتعني None عدم وجود حد). ويعيد token_response() القيمتين
server_url وparticipant_token لإرسالهما إلى المتصفح:
import asyncio
import os
from humain_voice.agent import AgentClient, AgentError
async def main() -> None:
async with AgentClient(api_url=os.environ["API_URL"], api_key=os.environ["API_KEY"]) as agent:
try:
session = await agent.create_session(
participant={"identity": "user-123"},
agent={"prompt": "You help {{name}} with their orders.", "intro": "Hi {{name}}!"},
variables={"name": "Sara"},
)
except AgentError as err:
print("error:", err.code, err.status_code, err.data)
raise
print("session:", session.session_id, session.expires_at.isoformat())
asyncio.run(main())يرفع الطلب الفاشل AgentError يحمل status_code وcode وretryable
وretry_after (بالثواني) وdata؛ ومشكلات التحقق في data["errors"].
وAgentAuthError (401) وAgentRateLimitError (429) صنفان فرعيان منه، كما في أخطاء النسخ الدفعي. أما جانب المتصفح
فهو @humain-voice/agent.
التسميات التوضيحية
يبني stt.Subtitles.from_response(result, **options) التسميات من نتيجة النسخ الدفعي أو السريع؛
ويقبل stt.Subtitles.from_words(words, **options) أي قائمة كلمات. يحوّلها to_vtt(**options) و
to_srt(**options) إلى الصيغتين المقابلتين، ويقبلان max_chars_per_line وmax_lines وstrict.
| الاسم | النوع | الافتراضي | المعنى |
|---|---|---|---|
max_duration_seconds | float | 6.0 | أطول تسمية. |
max_gap_seconds | float | 0.7 | الصمت الذي يبدأ تسمية جديدة. |
min_duration_seconds | float | 0.5 | أقصر تسمية. |
max_chars_per_line | int | 42 | عرض السطر. |
max_lines | int | 2 | عدد الأسطر في التسمية. |
split_on_speaker_change | bool | True | ابدأ تسمية جديدة عند تغيّر المتحدث. |
strict | bool | False | ارفع SubtitleError عند توقيت معطوب بدل إصلاحه أو تخطيه. |
للتسميات التوضيحية المباشرة، اجمع words من كل نتيجة is_speech_final وis_final، ثم
استدعِ Subtitles.from_words() كما يفعل مثال النسخ الفوري.
الأخطاء
ترفع طرق النسخ الدفعي أصنافًا فرعية من stt.BatchTranscribeError:
| الصنف | متى | السمات |
|---|---|---|
BatchTranscribeError | أي استجابة غير 2xx، أو api_url / api_key فارغ | status_code, code, retryable, job_id, capacity, raw_body |
BatchTranscribeAuthError | 401 | مثل ما سبق |
BatchTranscribeRateLimitError | 429 | retry_after (بالثواني؛ None ما لم يكن Retry-After عددًا صحيحًا) |
BatchTranscribeJobFailedError | بلغت المهمة failed | error, error_code |
BatchTranscribeTimeoutError | تجاوز transcribe() قيمة timeout_seconds | job_id, elapsed_seconds |
ترفع أعطال الشبكة aiohttp.ClientError أو asyncio.TimeoutError؛ أعد محاولتها في القراءات.
يمرّر عملاء Socket.IO ErrorResponse إلى on_error: تفرّع على code (الثوابت في
humain_voice.errors) وretryable، واقرأ retry_after_seconds وdata وretry_scope
(القيمة new_stream تعني افتح تدفقًا جديدًا). ترفع مكررات التمييز DiarizationStreamError، وتكون
response فيه هي ErrorResponse. الرموز وقواعد إعادة المحاولة في
الأخطاء والحدود.
يعيد هذا المثال محاولة قراءة نتيجة دفعية مع التراجع وsave_result=True:
from __future__ import annotations
import asyncio
import os
import random
import sys
import aiohttp
from humain_voice import stt
from humain_voice.stt.batchtranscription import TranscriptionResponse
def required_env(name: str) -> str:
value = os.environ.get(name)
if not value:
raise RuntimeError(f"{name} is required")
return value
async def get_result_with_retry(
client: stt.BatchTranscribeClient,
job_id: str,
attempts: int = 5,
) -> TranscriptionResponse:
for attempt in range(1, attempts + 1):
try:
# save_result keeps the stored result readable for a retry.
return await client.get_result(
job_id, stt.Language.ArEn, save_result=True
)
except stt.BatchTranscribeError as error:
retryable = (
isinstance(error, stt.BatchTranscribeRateLimitError)
or error.retryable is True
)
server_delay = 0.0
if isinstance(error, stt.BatchTranscribeRateLimitError):
server_delay = error.retry_after or 0
print(
"error:",
error.code or "",
error.status_code or "",
"" if error.capacity is None else error.capacity,
file=sys.stderr,
)
if not retryable or attempt == attempts:
raise
except (aiohttp.ClientError, asyncio.TimeoutError) as error:
# Network failures aren't SDK errors; a result read is safe to retry.
server_delay = 0.0
print("error:", "network", error, file=sys.stderr)
if attempt == attempts:
raise
exponential_delay = 0.5 * 2 ** (attempt - 1)
await asyncio.sleep(max(server_delay, exponential_delay) + random.random() * 0.25)
raise RuntimeError("Retry loop exhausted")
async def main() -> None:
if len(sys.argv) < 2:
raise RuntimeError("Pass a batch job ID as the first argument")
async with stt.BatchTranscribeClient(
api_url=required_env("API_URL"),
api_key=required_env("API_KEY"),
api_version=os.environ.get("API_VERSION", "v1"),
) as client:
result = await get_result_with_retry(client, sys.argv[1])
print("status:", result.status.value)
print(result.results.transcript if result.results else "")
if __name__ == "__main__":
asyncio.run(main())
مرّر معرّف المهمة وسيطًا أول. الخرج المتوقع (توضيحي):
error: SERVER_INTERNAL 500
status: done
Hello and welcome to the meeting.أعد محاولة submit() عند 429 أو 503 فقط. بعد 500 أو مهلة أو انقطاع اتصال قد تكون المهمة
موجودة؛ راجع إعادة المحاولة والتكرار.
المهل والقيم الافتراضية
القيم بالثواني. تؤدي المهل المنتهية إلى asyncio.TimeoutError ما لم يُذكر غير ذلك.
| العميل | الخيار | الافتراضي | النطاق المسموح |
|---|---|---|---|
BatchTranscribeClient | poll_interval | 2 | الانتظار بين قراءات النتيجة في transcribe(). |
BatchTranscribeClient | timeout_seconds | 300 | الاستعلام الدوري في transcribe() بعد الرفع. يرفع BatchTranscribeTimeoutError. |
FastTranscriptionClient | timeout_seconds في transcribe() | 60 | انتظار النتيجة النهائية. |
RealtimeClient | timeout_seconds في stream.close() | 1 | انتظار is_final؛ يعود دون خطأ عند انتهاء المهلة. مرّر close(timeout_seconds=5.0). |
RealtimeDiarizationClient | timeout_seconds في stream.close() | 5 | انتظار التحديث النهائي؛ يعيد أفضل خط زمني معروف. |
TTSClient | timeout_seconds في list_voices() | None | انتظار قائمة الأصوات. |
TTSClient | timeout_seconds في synthesize() / synthesize_stream() | None | انتظار كل قطعة تالية. اضبطها دائمًا. |
يطبّق الخادم مواعيده النهائية الخاصة لـTTS؛ راجع المهل.