حزم SDK

Python

انسخ الصوت، وابنِ الخطوط الزمنية للمتحدثين، وولّف الكلام من Python باستخدام humain-voice 0.18.1.

التثبيت

python -m pip install humain-voice==0.18.1

اضبط عميلًا

لكل سير عمل عميله الخاص؛ استورد stt وtts وagent من humain_voice. يأخذ كل عميل هذه الوسائط المسماة:

الاسمالنوعالافتراضيالمعنى
api_urlstrمطلوبعنوان الخدمة الأساسي.
api_keystrمطلوبمفتاح API.
api_pathstr/socket.ioمسار Socket.IO. لكل عميل عدا النسخ الدفعي.
api_versionstrv1إصدار REST. لـBatchTranscribeClient فقط.

تقرأ الأمثلة هذه القيم من API_URL وAPI_KEY وAPI_PATH وAPI_VERSION؛ راجع إعدادات الاتصال.

سير العملالعميلالتنظيف بـ
النسخ الدفعيstt.BatchTranscribeClientclose()
النسخ السريعstt.FastTranscriptionClientclose()
النسخ الفوريstt.RealtimeClientdisconnect()
التمييز المباشرstt.RealtimeDiarizationClientdisconnect()
تحويل النص إلى كلامtts.TTSClientclose()
جلسات Voice Agentagent.AgentClientclose()

افتح كل عميل بـasync with؛ يتصل عملاء Socket.IO عند الدخول، فيفشل الاتصال هناك عند خطأ في المفتاح. يجب أن تكون دوال الاستدعاء المرتد دوال عادية غير حاجبة: لا ينتظرها SDK. قيم اللغات والنماذج في النماذج والأصوات.

المتغيرات المتزامنة وغير المتزامنة

طرق العميل كوروتينات. ولبعضها نظير حاجب بالملحق _sync:

العميلالطرق المتزامنة
BatchTranscribeClientsubmit_sync(), get_result_sync(), transcribe_sync(), close_sync()
FastTranscriptionClienttranscribe_sync(), close_sync()
RealtimeClientstart_stream_sync()؛ وفي التدفق send_sync(), close_sync(), stop_sync()
RealtimeDiarizationClientstart_stream_sync()؛ وفي التدفق send_sync(), close_sync()
TTSClientlist_voices_sync(), synthesize_sync(), close_sync()
AgentClientcreate_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 بالاسم فقط.

الاسمالنوعالافتراضيالمعنى
audiobytes أو مسار (str أو Path) أو ملف ثنائيمطلوبالصوت المراد رفعه.
langstt.Language أو strمطلوباللغة المنطوقة.
asrstt.BatchTranscriptionModel أو strNoneنموذج ASR.
diarizationBatchDiarizationNoneOn أو D1 أو D2 تسمّي المتحدثين. تعداد فقط.
itnboolNoneتطبيع النص العكسي.
redactBatchRedactNoneBatchRedact.On يفعّل الحجب. تعداد فقط.
save_resultboolFalseأبقِ النتيجة قابلة للقراءة بعد جلبها؛ راجع اقرأ النتيجة مرة أخرى. ليس في submit().
poll_intervalfloat2.0الثواني بين قراءات النتيجة. لـtranscribe() فقط.
timeout_secondsfloat300.0حد الاستعلام الدوري بالثواني. لـtranscribe() فقط.
on_progressCallable[[TranscriptionResponse], None]Noneتُستدعى عند كل قراءة للنتيجة. لـtranscribe() فقط.

استورد BatchDiarization وBatchRedact وTranscriptionResponse من humain_voice.stt.batchtranscription.

batch_transcription.py
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. يجمّع هذا المثال الكلمات في أدوار المتحدثين:

batch_speakers.py
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_sourcebytes أو ملف ثنائيمطلوبالمقطع المراد نسخه.
languagestt.Languageمطلوباللغة المنطوقة.
asr_modelstt.FastTranscriptionModel أو strمطلوبنموذج ASR.
on_responseقابل للاستدعاءNoneيستقبل النتائج الجزئية، ثم النهائية.
on_file_uploadقابل للاستدعاءNoneيستقبل إيصال الرفع.
on_errorقابل للاستدعاءNoneيستقبل ErrorResponse.
timeout_secondsfloat60.0انتظار النتيجة النهائية.
fast_transcription.py
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()languagestt.Languageمطلوباللغة المنطوقة.
start_stream()on_responseقابل للاستدعاءNoneيستقبل النتائج المؤقتة والنهائية.
start_stream()on_errorقابل للاستدعاءNoneيستقبل ErrorResponse.
stream.send()audio_bytesbytesمطلوبقطعة صوت واحدة.
stream.close()timeout_secondsfloat1.0انتظار is_final. مرّر 5.0.

يرسل المثال قطعًا من 3,200 بايت (100 ms) ويكتب التسميات التوضيحية من الكلمات النهائية. لإنشاء recording.pcm، راجع جهّز الصوت.

realtime_transcription.py
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.

realtime_diarization.py
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 عند توفره:

list_voices.py
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 بالاسم فقط.

الاسمالنوعالافتراضيالمعنى
textstrمطلوبالنص المراد نطقه.
voice_idstrNoneمعرّف الصوت من list_voices().
voice_referenceslist من {"text": str, "audio": str}Noneمقاطع مرجعية للاستنساخ؛ audio بصيغة WAV مشفرة base64.
modeltts.TtsModel أو strNone (Nebula)نموذج TTS.
timeout_secondsfloat أو NoneNoneانتظار كل قطعة تالية؛ None ينتظر إلى الأبد، فاضبطها دائمًا.
on_audioقابل للاستدعاءNoneيستقبل كل قطعة. لـsynthesize() فقط.
on_errorقابل للاستدعاءNoneيستقبل ErrorResponse.
request_iduuid.UUIDNoneمعرّف الطلب؛ يُولَّد عند حذفه.

يضيف هذا المثال ترويسة WAV بالوحدة wave ويكتب speech.wav:

tts_to_wav.py
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 -
tts_stream.py
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() طلب جلسة واحدًا:

الاسمالنوعالافتراضيالمعنى
participantdict يحمل identity، وname وgender اختياريينمطلوبالمستخدم الذي ينضم إلى المكالمة.
agentdictNoneprompt وintro وvoice_id وclient_tools وtool_acknowledgments، كما في الطلب.
variablesdict[str, str | int | float | bool]Noneقيم العناصر النائبة {{name}}.
idempotency_keystrNoneيُرسل كـIdempotency-Key، فتعيد إعادة المحاولة الجلسة الأولى.
timeout_secondsfloat10.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_secondsfloat6.0أطول تسمية.
max_gap_secondsfloat0.7الصمت الذي يبدأ تسمية جديدة.
min_duration_secondsfloat0.5أقصر تسمية.
max_chars_per_lineint42عرض السطر.
max_linesint2عدد الأسطر في التسمية.
split_on_speaker_changeboolTrueابدأ تسمية جديدة عند تغيّر المتحدث.
strictboolFalseارفع 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
BatchTranscribeAuthError401مثل ما سبق
BatchTranscribeRateLimitError429retry_after (بالثواني؛ None ما لم يكن Retry-After عددًا صحيحًا)
BatchTranscribeJobFailedErrorبلغت المهمة failederror, error_code
BatchTranscribeTimeoutErrorتجاوز transcribe() قيمة timeout_secondsjob_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:

batch_error_retry.py
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 ما لم يُذكر غير ذلك.

العميلالخيارالافتراضيالنطاق المسموح
BatchTranscribeClientpoll_interval2الانتظار بين قراءات النتيجة في transcribe().
BatchTranscribeClienttimeout_seconds300الاستعلام الدوري في transcribe() بعد الرفع. يرفع BatchTranscribeTimeoutError.
FastTranscriptionClienttimeout_seconds في transcribe()60انتظار النتيجة النهائية.
RealtimeClienttimeout_seconds في stream.close()1انتظار is_final؛ يعود دون خطأ عند انتهاء المهلة. مرّر close(timeout_seconds=5.0).
RealtimeDiarizationClienttimeout_seconds في stream.close()5انتظار التحديث النهائي؛ يعيد أفضل خط زمني معروف.
TTSClienttimeout_seconds في list_voices()Noneانتظار قائمة الأصوات.
TTSClienttimeout_seconds في synthesize() / synthesize_stream()Noneانتظار كل قطعة تالية. اضبطها دائمًا.

يطبّق الخادم مواعيده النهائية الخاصة لـTTS؛ راجع المهل.

الخطوات التالية

في هذه الصفحة