حزم SDK

JavaScript وTypeScript

انسخ الصوت، وابنِ الخطوط الزمنية للمتحدثين، وولّف الكلام من Node.js أو Bun باستخدام @humain-voice/sdk 0.18.1.

التثبيت

npm install @humain-voice/[email protected]

اضبط عميلًا

لكل سير عمل عميله الخاص. يأخذ مُنشئ كل عميل كائن خيارات واحدًا:

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

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

سير العملالعميلالتنظيف بـ
النسخ الدفعيBatchTranscribeClientclose()
النسخ السريعFastTranscriptionClientclose()
النسخ الفوريRealtimeClientdisconnect()
التمييز المباشرRealtimeDiarizationClientdisconnect()
تحويل النص إلى كلامTTSClientclose()
جلسات Voice AgentAgentClient (من @humain-voice/sdk/agent)لا شيء للإغلاق

يتصل عملاء Socket.IO عند أول استخدام؛ استدعِ connect() أولًا ليفشل الاتصال مبكرًا عند خطأ في المفتاح أو العنوان. نظّف الموارد في finally. قيم اللغات والنماذج في النماذج والأصوات.

النسخ الدفعي

يرفع transcribe(audio, lang, options) ملفًا كاملًا، ويستعلم دوريًا حتى تصبح المهمة done، ثم يعيد النص المنسوخ مع إزاحات الكلمات. للاستعلام الدوري من عامل خلفي، استدعِ submit(audio, lang, options)، ثم getResult(jobId, lang, { saveResult }) حتى تصبح الحالة done أو failed أو cleared (راجع النسخ الدفعي مهمة).

الاسمالنوعالافتراضيالمعنى
audioArrayBuffer أو Uint8Array أو Blob أو Fileمطلوبالصوت المراد رفعه.
langLanguage أو stringمطلوباللغة المنطوقة.
asrBatchTranscriptionModel أو stringغير معيّننموذج ASR.
diarizationBatchDiarizationغير معيّنOn أو D1 أو D2 تسمّي المتحدثين.
itnbooleanغير معيّنتطبيع النص العكسي.
redactBatchRedactغير معيّنBatchRedact.On يفعّل الحجب.
saveResultbooleanfalseأبقِ النتيجة قابلة للقراءة بعد جلبها؛ راجع اقرأ النتيجة مرة أخرى. ليس في submit().
pollIntervalnumber2الثواني بين قراءات النتيجة. لـtranscribe() فقط.
timeoutnumber300حد الاستعلام الدوري بالثواني. لـtranscribe() فقط.
onProgress(status: TranscriptionResponse) => voidغير معيّنتُستدعى عند كل قراءة للنتيجة. لـtranscribe() فقط.
batch-transcription.ts
import { readFile, writeFile } from 'node:fs/promises';

import {
  BatchDiarization,
  BatchTranscribeClient,
  BatchTranscriptionModel,
  Language,
  Subtitles,
} from '@humain-voice/sdk';

function requiredEnv(name: 'API_KEY' | 'API_URL'): string {
  const value = process.env[name];
  if (!value) throw new Error(`${name} is required`);
  return value;
}

async function main(): Promise<void> {
  const inputPath = process.argv[2] ?? 'recording.wav';
  const outputPath = process.argv[3] ?? 'recording.vtt';
  const client = new BatchTranscribeClient({
    api_url: requiredEnv('API_URL'),
    api_key: requiredEnv('API_KEY'),
    api_version: process.env.API_VERSION ?? 'v1',
  });

  try {
    const result = await client.transcribe(
      await readFile(inputPath),
      Language.ArEn,
      {
        asr: BatchTranscriptionModel.BayanArEn,
        diarization: BatchDiarization.On,
        saveResult: true,
        pollInterval: 2,
        timeout: 300,
        onProgress: ({ status }) => console.info('status:', status),
      },
    );

    console.info(result.results?.transcript ?? '');
    await writeFile(outputPath, Subtitles.fromResponse(result).toVtt(), 'utf8');
  } finally {
    await client.close();
  }
}

void main().catch((error: unknown) => {
  console.error(error);
  process.exitCode = 1;
});

الخرج المتوقع (توضيحي):

status: queued
status: processing
status: done
Hello and welcome to the meeting.

عند تفعيل diarization، تحمل كل إزاحة كلمة تسمية speaker. يجمّع هذا المثال الكلمات في أدوار المتحدثين:

batch-speakers.ts
import { readFile } from 'node:fs/promises';

import {
  BatchDiarization,
  BatchTranscribeClient,
  BatchTranscriptionModel,
  Language,
} from '@humain-voice/sdk';

function requiredEnv(name: 'API_KEY' | 'API_URL'): string {
  const value = process.env[name];
  if (!value) throw new Error(`${name} is required`);
  return value;
}

async function main(): Promise<void> {
  const inputPath = process.argv[2] ?? 'recording.wav';
  const client = new BatchTranscribeClient({
    api_url: requiredEnv('API_URL'),
    api_key: requiredEnv('API_KEY'),
    api_version: process.env.API_VERSION ?? 'v1',
  });

  try {
    const result = await client.transcribe(await readFile(inputPath), Language.ArEn, {
      asr: BatchTranscriptionModel.BayanArEn,
      diarization: BatchDiarization.On,
      saveResult: true,
      timeout: 300,
      onProgress: ({ status }) => console.info('status:', status),
    });

    const turns: { speaker: string; words: string[] }[] = [];
    for (const offset of result.results?.offsets ?? []) {
      const speaker = offset.speaker ?? 'UNKNOWN_SPEAKER';
      const last = turns[turns.length - 1];
      if (last?.speaker === speaker) last.words.push(offset.word);
      else turns.push({ speaker, words: [offset.word] });
    }
    for (const turn of turns) console.info(`${turn.speaker}: ${turn.words.join(' ')}`);
  } finally {
    await client.close();
  }
}

void main().catch((error: unknown) => {
  console.error(error);
  process.exitCode = 1;
});

الخرج المتوقع (توضيحي؛ التسميات سلاسل معتمة):

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, options) مقطعًا واحدًا قصيرًا كاملًا عبر Socket.IO، ويكتمل بالنتيجة النهائية. لا يضع SDK موعدًا نهائيًا، فغلّف الاستدعاء بموعدك الخاص كما يفعل المثال. أرسل التسجيلات الأطول إلى النسخ الدفعي؛ راجع حدود النسخ السريع.

الاسمالنوعالافتراضيالمعنى
audio_sourceArrayBuffer أو Uint8Array أو Blobمطلوبالمقطع المراد نسخه.
languageLanguageمطلوباللغة المنطوقة.
asr_modelFastTranscriptionModel أو stringمطلوبنموذج ASR.
onResponseدالةغير معيّنتستقبل النتائج الجزئية، ثم النهائية.
onFileUploadدالةغير معيّنتستقبل إيصال الرفع.
onErrorدالةغير معيّنتستقبل ErrorResponse.
fast-transcription.ts
import { readFile, writeFile } from 'node:fs/promises';

import {
  FastTranscriptionClient,
  FastTranscriptionModel,
  Language,
  Subtitles,
} from '@humain-voice/sdk';

function requiredEnv(name: 'API_KEY' | 'API_URL'): string {
  const value = process.env[name];
  if (!value) throw new Error(`${name} is required`);
  return value;
}

function socketPath(): { api_path?: string } {
  const value = process.env.API_PATH;
  return value ? { api_path: value } : {};
}

async function withDeadline<T>(operation: Promise<T>, milliseconds: number): Promise<T> {
  let timer: ReturnType<typeof setTimeout> | undefined;
  try {
    return await Promise.race([
      operation,
      new Promise<never>((_, reject) => {
        timer = setTimeout(
          () => reject(new Error('Fast transcription deadline exceeded')),
          milliseconds,
        );
      }),
    ]);
  } finally {
    if (timer) clearTimeout(timer);
  }
}

async function main(): Promise<void> {
  const inputPath = process.argv[2] ?? 'recording.wav';
  const outputPath = process.argv[3] ?? 'recording.vtt';
  const client = new FastTranscriptionClient({
    api_url: requiredEnv('API_URL'),
    api_key: requiredEnv('API_KEY'),
    ...socketPath(),
  });

  try {
    await client.connect();
    const result = await withDeadline(
      client.transcribe(
        await readFile(inputPath),
        Language.ArEn,
        FastTranscriptionModel.BayanArEn,
        {
          onFileUpload: (response) => console.info('status:', 'uploaded', response?.id),
          onResponse: (response) => {
            console.info(response.is_final ? 'final:' : 'partial:', response.transcription);
          },
          onError: (error) => console.error('error:', error.code, error.message),
        },
      ),
      60_000,
    );

    if (!result) throw new Error('Fast transcription ended without a final result');
    await writeFile(outputPath, Subtitles.fromResponse(result).toVtt(), 'utf8');
  } finally {
    await client.close();
  }
}

void main().catch((error: unknown) => {
  console.error(error);
  process.exitCode = 1;
});

الخرج المتوقع (توضيحي):

status: uploaded 3f1c2a9e-5b7d-4e8a-9c41-0d2e6f8b7a15
partial: Hello and
final: Hello and welcome to the meeting.

النسخ الفوري

يفتح RealtimeClient.startStream(language, options) تدفقًا. أرسل صوت PCM16 بترتيب little-endian وبتردد 16 kHz، أحادي القناة، عبر stream.send()، ثم استدعِ stream.close() لانتظار is_final؛ أما stream.stop() فتنهي دون انتظار. راجع نتائج البث حالة وليست سجلًا.

الاستدعاءالمعاملالنوعالافتراضيالمعنى
startStream()languageLanguageمطلوباللغة المنطوقة.
startStream()onResponseدالةغير معيّنتستقبل النتائج المؤقتة والنهائية.
startStream()onErrorدالةغير معيّنتستقبل ErrorResponse.
stream.send()audioBytesUint8Arrayمطلوبقطعة صوت واحدة.
stream.close()timeoutSecondsnumber1انتظار is_final. مرّر 5.

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

realtime-transcription.ts
import { readFile, writeFile } from 'node:fs/promises';

import {
  type ErrorResponse,
  Language,
  RealtimeClient,
  Subtitles,
  type WordSegment,
} from '@humain-voice/sdk';

const CHUNK_BYTES = 3_200; // 100 ms of PCM16LE, 16 kHz, mono audio.

function requiredEnv(name: 'API_KEY' | 'API_URL'): string {
  const value = process.env[name];
  if (!value) throw new Error(`${name} is required`);
  return value;
}

function socketPath(): { api_path?: string } {
  const value = process.env.API_PATH;
  return value ? { api_path: value } : {};
}

async function pause(milliseconds: number): Promise<void> {
  await new Promise<void>((resolve) => setTimeout(resolve, milliseconds));
}

async function main(): Promise<void> {
  const inputPath = process.argv[2] ?? 'recording.pcm';
  const outputPath = process.argv[3] ?? 'recording.vtt';
  const client = new RealtimeClient({
    api_url: requiredEnv('API_URL'),
    api_key: requiredEnv('API_KEY'),
    ...socketPath(),
  });
  const finalizedWords: WordSegment[] = [];
  let serverError: ErrorResponse | undefined;
  let protocolFinalObserved = false;

  try {
    const stream = await client.startStream(Language.ArEn, {
      onResponse: (response) => {
        const kind = response.is_final
          ? 'final'
          : response.is_speech_final
            ? 'speech-final'
            : 'partial';
        console.info(`${kind}:`, response.transcription);
        if (response.is_final) protocolFinalObserved = true;
        if (response.is_final || response.is_speech_final) {
          // seq is not guaranteed to increase, so keep words in arrival order.
          finalizedWords.push(...response.words);
        }
      },
      onError: (error) => {
        console.error('error:', error.code, error.message);
        serverError = error;
      },
    });

    const pcm = await readFile(inputPath);
    try {
      for (let offset = 0; offset < pcm.length; offset += CHUNK_BYTES) {
        if (serverError) break;
        await stream.send(pcm.subarray(offset, offset + CHUNK_BYTES));
        await pause(100);
      }
      // Resolves (does not throw) if is_final has not arrived within 5 s.
      if (!serverError) await stream.close(5);
    } catch (error: unknown) {
      // The SDK drops the stream on a server error, so send() and close() throw.
      if (!serverError) throw error;
    }
    if (serverError) {
      throw new Error(serverError.message ?? serverError.code ?? 'Realtime stream failed');
    }
    if (!protocolFinalObserved) {
      throw new Error('Realtime stream ended before protocol is_final');
    }
    await writeFile(outputPath, Subtitles.fromWords(finalizedWords).toVtt(), 'utf8');
  } finally {
    await client.disconnect();
  }
}

void main().catch((error: unknown) => {
  console.error(error);
  process.exitCode = 1;
});

الخرج المتوقع (توضيحي):

partial: Hello and
speech-final: Hello and welcome to the meeting.
partial: Let's start
final: Let's start with the agenda.

التمييز المباشر

يبلّغ RealtimeDiarizationClient.startStream({ onUpdate }) عمّن يتحدث أثناء send() لصوت PCM بصيغة النسخ الفوري على قطع من 15,360 بايت (480 ms)، وهي DIARIZATION_RECOMMENDED_CHUNK_BYTES. يحمل كل تحديث الخط الزمني الكامل في segments والمقاطع النهائية الجديدة في newlyFinalized. يكتمل stream.close(5) بالخط الزمني النهائي، ويحوّله toRttm() إلى RTTM.

realtime-diarization.ts
import { readFile, writeFile } from 'node:fs/promises';

import {
  DIARIZATION_RECOMMENDED_CHUNK_BYTES,
  RealtimeDiarizationClient,
  type SpeakerSegment,
  toRttm,
} from '@humain-voice/sdk';

function requiredEnv(name: 'API_KEY' | 'API_URL'): string {
  const value = process.env[name];
  if (!value) throw new Error(`${name} is required`);
  return value;
}

function socketPath(): { api_path?: string } {
  const value = process.env.API_PATH;
  return value ? { api_path: value } : {};
}

async function pause(milliseconds: number): Promise<void> {
  await new Promise<void>((resolve) => setTimeout(resolve, milliseconds));
}

async function main(): Promise<void> {
  const inputPath = process.argv[2] ?? 'recording.pcm';
  const outputPath = process.argv[3] ?? 'recording.rttm';
  const client = new RealtimeDiarizationClient({
    api_url: requiredEnv('API_URL'),
    api_key: requiredEnv('API_KEY'),
    ...socketPath(),
  });

  try {
    let finalObserved = false;
    const stream = await client.startStream({
      onError: (error) => console.error('error:', error.code, error.message),
      onUpdate: (update) => {
        finalObserved ||= update.isFinal;
        for (const segment of update.newlyFinalized) {
          console.info(segment.speaker, segment.start_time, segment.end_time);
        }
      },
    });
    const pcm = await readFile(inputPath);

    if (pcm.length === 0 || pcm.length % 2 !== 0) {
      throw new Error('Input must be nonempty PCM16 with an even byte length');
    }
    for (
      let offset = 0;
      offset < pcm.length;
      offset += DIARIZATION_RECOMMENDED_CHUNK_BYTES
    ) {
      await stream.send(
        pcm.subarray(offset, offset + DIARIZATION_RECOMMENDED_CHUNK_BYTES),
      );
      await pause(480);
    }

    // Returns the best-known timeline after 5 s even without a final update.
    const timeline: SpeakerSegment[] = await stream.close(5);
    const destination = finalObserved ? outputPath : `${outputPath}.partial`;
    await writeFile(destination, toRttm(timeline, 'recording'), 'utf8');
    if (!finalObserved) {
      console.info(
        'status:',
        `Final result not observed; wrote incomplete output to ${destination}`,
      );
    }
  } finally {
    await client.disconnect();
  }
}

void main().catch((error: unknown) => {
  console.error(error);
  process.exitCode = 1;
});

الخرج المتوقع (توضيحي):

SPEAKER_01 0 3.84
SPEAKER_02 3.84 7.2
SPEAKER_01 7.2 11.52

تحويل النص إلى كلام

يعيد TTSClient صوت PCM16 خامًا بترتيب little-endian أحادي القناة بتردد getSampleRate(model) Hz (24,000 للنموذج الافتراضي TtsModel.Nebula). يكتمل listVoices({ timeoutSeconds }) بكائنات { id, label, profile? }:

list-voices.ts
import { TTSClient } from '@humain-voice/sdk';

function requiredEnv(name: 'API_KEY' | 'API_URL'): string {
  const value = process.env[name];
  if (!value) throw new Error(`${name} is required`);
  return value;
}

function socketPath(): { api_path?: string } {
  const value = process.env.API_PATH;
  return value ? { api_path: value } : {};
}

async function main(): Promise<void> {
  const client = new TTSClient({
    api_url: requiredEnv('API_URL'),
    api_key: requiredEnv('API_KEY'),
    ...socketPath(),
  });

  try {
    for (const voice of await client.listVoices({ timeoutSeconds: 5 })) {
      const dialect = voice.profile?.speaker.dialect ?? '';
      const languages = voice.profile?.languages.join(',') ?? '';
      console.info(voice.id, voice.label, dialect, languages);
    }
  } finally {
    await client.close();
  }
}

void main().catch((error: unknown) => {
  console.error(error);
  process.exitCode = 1;
});

الخرج المتوقع (توضيحي؛ تختلف المعرّفات بحسب البيئة):

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.0-beta.3 أو أحدث، قد يحوي profile أيضًا emotions وstyles (string[]). ويغيبان حيث لا تكون المشاعر وأسلوب الإلقاء مفعّلة؛ راجع قائمة الأصوات.

يكتمل synthesize(text, options) بالمقطع كاملًا في Uint8Array واحد؛ ويُنتج synthesizeStream(text, options) قطعًا بالشكل { id, is_last, audio }. مرّر واحدًا فقط من voice_id أو voice_references.

الاسمالنوعالافتراضيالمعنى
textstringمطلوبالنص المراد نطقه.
voice_idstringغير معيّنمعرّف الصوت من listVoices().
voice_references{ text: string; audio: string }[]غير معيّنمقاطع مرجعية للاستنساخ؛ audio بصيغة WAV مشفرة base64.
modelTtsModel أو stringTtsModel.Nebulaنموذج TTS.
timeoutSecondsnumber30انتظار كل قطعة تالية؛ 0 يعطّله.
onAudioدالةغير معيّنتستقبل كل قطعة. لـsynthesize() فقط.
onErrorدالةغير معيّنتستقبل ErrorResponse.
request_idstringمولّدمعرّف الطلب.

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

tts-to-wav.ts
import { writeFile } from 'node:fs/promises';

import {
  TTSClient,
  TtsModel,
  getSampleRate,
} from '@humain-voice/sdk';

function requiredEnv(name: 'API_KEY' | 'API_URL'): string {
  const value = process.env[name];
  if (!value) throw new Error(`${name} is required`);
  return value;
}

function socketPath(): { api_path?: string } {
  const value = process.env.API_PATH;
  return value ? { api_path: value } : {};
}

function pcm16ToWav(pcm: Uint8Array, sampleRate: number): Buffer {
  const header = Buffer.alloc(44);
  header.write('RIFF', 0);
  header.writeUInt32LE(36 + pcm.byteLength, 4);
  header.write('WAVE', 8);
  header.write('fmt ', 12);
  header.writeUInt32LE(16, 16);
  header.writeUInt16LE(1, 20); // Linear PCM.
  header.writeUInt16LE(1, 22); // Mono.
  header.writeUInt32LE(sampleRate, 24);
  header.writeUInt32LE(sampleRate * 2, 28);
  header.writeUInt16LE(2, 32);
  header.writeUInt16LE(16, 34);
  header.write('data', 36);
  header.writeUInt32LE(pcm.byteLength, 40);

  return Buffer.concat([
    header,
    Buffer.from(pcm.buffer, pcm.byteOffset, pcm.byteLength),
  ]);
}

async function main(): Promise<void> {
  const text = process.argv[2] ?? 'Hello from HUMAIN Voice';
  const outputPath = process.argv[3] ?? 'speech.wav';
  const client = new TTSClient({
    api_url: requiredEnv('API_URL'),
    api_key: requiredEnv('API_KEY'),
    ...socketPath(),
  });

  try {
    const voices = await client.listVoices({ timeoutSeconds: 5 });
    const voice = voices.find((candidate) => candidate.profile) ?? voices[0];
    if (!voice) throw new Error('No TTS voices are available');
    if (voice.profile) {
      console.info(
        'status:',
        'voice',
        voice.label,
        voice.profile.speaker.dialect,
        voice.profile.languages,
      );
    }

    const model = TtsModel.Nebula;
    const pcm = await client.synthesize(text, {
      voice_id: voice.id,
      model,
      // Inactivity timeout per audio chunk, not a total deadline.
      timeoutSeconds: 30,
      onError: (error) => console.error('error:', error.code, error.message),
    });

    await writeFile(outputPath, pcm16ToWav(pcm, getSampleRate(model)));
  } finally {
    await client.close();
  }
}

void main().catch((error: unknown) => {
  console.error(error);
  process.exitCode = 1;
});

الخرج المتوقع (توضيحي):

status: voice mul_nourah ars [ 'ar', 'en' ]

يبث هذا المثال الصوت إلى stdout:

node tts-stream.ts "Hello from HUMAIN Voice" | ffplay -f s16le -ar 24000 -ch_layout mono -
tts-stream.ts
import { TTSClient, TtsModel, getSampleRate } from '@humain-voice/sdk';

function requiredEnv(name: 'API_KEY' | 'API_URL'): string {
  const value = process.env[name];
  if (!value) throw new Error(`${name} is required`);
  return value;
}

function socketPath(): { api_path?: string } {
  const value = process.env.API_PATH;
  return value ? { api_path: value } : {};
}

async function main(): Promise<void> {
  const text = process.argv[2] ?? 'Hello from HUMAIN Voice';
  const model = TtsModel.Nebula;
  const client = new TTSClient({
    api_url: requiredEnv('API_URL'),
    api_key: requiredEnv('API_KEY'),
    ...socketPath(),
  });

  try {
    const [voice] = await client.listVoices({ timeoutSeconds: 5 });
    if (!voice) throw new Error('No TTS voices are available');

    // Audio goes to stdout, so logs go to stderr.
    console.error('status: sample rate', getSampleRate(model));
    for await (const chunk of client.synthesizeStream(text, {
      voice_id: voice.id,
      model,
      timeoutSeconds: 30,
      onError: (error) => console.error('error:', error.code, error.message),
    })) {
      process.stdout.write(chunk.audio);
    }
  } finally {
    await client.close();
  }
}

void main().catch((error: unknown) => {
  console.error(error);
  process.exitCode = 1;
});

الخرج المتوقع على stderr (توضيحي):

status: sample rate 24000

راجع مخرجات الكلام لاختيار الوضع، و النماذج والأصوات للأصوات.

جلسات Voice Agent

يبدأ AgentClient، المستورد من @humain-voice/sdk/agent، جلسات Voice Agent من خادمك. ويحتاج الإصدار التجريبي:

npm install @humain-voice/[email protected]

يأخذ api_url وapi_key ولا يحتفظ باتصال، فلا شيء لإغلاقه. يرسل createSession(options) طلب جلسة واحدًا:

الاسمالنوعالافتراضيالمعنى
participant{ identity: string; name?: string; gender?: 'male' | 'female' }مطلوبالمستخدم الذي ينضم إلى المكالمة.
agentAgentConfigغير مضبوطprompt وintro وvoiceId وclientTools وtoolAcknowledgments (مع afterMs). تُرسل parameters للأداة دون تغيير.
variablesRecord<string, string | number | boolean>غير مضبوطقيم العناصر النائبة {{name}}.
idempotencyKeystringغير مضبوطيُرسل كـIdempotency-Key، فتعيد إعادة المحاولة الجلسة الأولى.
timeoutSecondsnumber10مهلة الطلب.

يعيد AgentSessionCredentials يحمل serverUrl وparticipantToken وsessionId وexpiresAt (Date) وeffective وlimits. وتستخدم effective وlimits أسماء camelCase، والحد null يعني عدم وجود حد. ويعيد tokenResponse() القيمة { server_url, participant_token } لإرسالها إلى المتصفح:

import { AgentClient, AgentError } from '@humain-voice/sdk/agent';

const agent = new AgentClient({ api_url: process.env.API_URL!, api_key: process.env.API_KEY! });

try {
  const session = await agent.createSession({
    participant: { identity: 'user-123' },
    agent: { prompt: 'You help {{name}} with their orders.', intro: 'Hi {{name}}!' },
    variables: { name: 'Sara' },
  });
  console.log('session:', session.sessionId, session.expiresAt.toISOString());
} catch (err) {
  if (err instanceof AgentError) console.error('error:', err.code, err.statusCode, err.data);
  throw err;
}

يطلق الطلب الفاشل AgentError يحمل statusCode وcode وretryable وretryAfter (بالثواني) وdata؛ ومشكلات التحقق في data.errors. وAgentAuthError (401) وAgentRateLimitError (429) صنفان فرعيان منه، كما في أخطاء النسخ الدفعي. أما جانب المتصفح فهو @humain-voice/agent.

التسميات التوضيحية

يبني Subtitles.fromResponse(result, options) التسميات من نتيجة النسخ الدفعي أو السريع؛ ويقبل Subtitles.fromWords(words, options) أي قائمة كلمات. يحوّلها toVtt(options) وtoSrt(options) إلى الصيغتين المقابلتين، ويقبلان maxCharsPerLine وmaxLines وstrict.

الاسمالنوعالافتراضيالمعنى
maxDurationSecondsnumber6أطول تسمية.
maxGapSecondsnumber0.7الصمت الذي يبدأ تسمية جديدة.
minDurationSecondsnumber0.5أقصر تسمية.
maxCharsPerLinenumber42عرض السطر.
maxLinesnumber2عدد الأسطر في التسمية.
splitOnSpeakerChangebooleantrueابدأ تسمية جديدة عند تغيّر المتحدث.
strictbooleanfalseارمِ SubtitleError عند توقيت معطوب بدل إصلاحه أو تخطيه.

للتسميات التوضيحية المباشرة، اجمع words من كل نتيجة is_speech_final وis_final، ثم استدعِ Subtitles.fromWords() كما يفعل مثال النسخ الفوري.

الأخطاء

ترمي طرق النسخ الدفعي أصنافًا فرعية من BatchTranscribeError:

الصنفمتىالحقول
BatchTranscribeErrorأي استجابة غير 2xx، أو api_url / api_key فارغstatusCode, code, retryable, jobId, capacity, rawBody
BatchTranscribeAuthError401مثل ما سبق
BatchTranscribeRateLimitError429retryAfter (بالثواني؛ غير معيّن ما لم يكن Retry-After عددًا صحيحًا)
BatchTranscribeJobFailedErrorبلغت المهمة failederror, errorCode
BatchTranscribeTimeoutErrorتجاوز transcribe() قيمة timeoutjobId, elapsed

تُرمى TypeError عند أعطال الشبكة من fetch؛ أعد محاولتها في قراءات getResult(). يمرّر عملاء Socket.IO ErrorResponse إلى onError: تفرّع على code وretryable، واقرأ retry_after_seconds وdata وretry_scope (القيمة new_stream تعني افتح تدفقًا جديدًا). تَرمي مكررات التمييز DiarizationStreamError، وتكون response فيه هي ErrorResponse. الرموز وقواعد إعادة المحاولة في الأخطاء والحدود.

يعيد هذا المثال محاولة قراءة نتيجة دفعية، بما في ذلك بعد فشل الشبكة، مع التراجع و saveResult: true:

batch-error-retry.ts
import {
  BatchTranscribeClient,
  BatchTranscribeError,
  BatchTranscribeRateLimitError,
  Language,
  type TranscriptionResponse,
} from '@humain-voice/sdk';

function requiredEnv(name: 'API_KEY' | 'API_URL'): string {
  const value = process.env[name];
  if (!value) throw new Error(`${name} is required`);
  return value;
}

async function pause(milliseconds: number): Promise<void> {
  await new Promise<void>((resolve) => setTimeout(resolve, milliseconds));
}

async function getResultWithRetry(
  client: BatchTranscribeClient,
  jobId: string,
  attempts = 5,
): Promise<TranscriptionResponse> {
  for (let attempt = 1; attempt <= attempts; attempt += 1) {
    try {
      // saveResult keeps the stored result readable for a retry.
      return await client.getResult(jobId, Language.ArEn, { saveResult: true });
    } catch (error: unknown) {
      let retryable: boolean;
      let serverDelayMs = 0;
      if (error instanceof BatchTranscribeError) {
        retryable = error instanceof BatchTranscribeRateLimitError || error.retryable === true;
        if (error instanceof BatchTranscribeRateLimitError && error.retryAfter !== undefined) {
          serverDelayMs = error.retryAfter * 1_000;
        }
        console.error('error:', error.code ?? '', error.statusCode ?? '', error.capacity ?? '');
      } else if (error instanceof TypeError) {
        // fetch reports network failures as TypeError; a result read is safe to retry.
        retryable = true;
        console.error('error:', 'network', error.message);
      } else {
        throw error;
      }
      if (!retryable || attempt === attempts) throw error;

      const exponentialDelayMs = 500 * 2 ** (attempt - 1);
      await pause(Math.max(serverDelayMs, exponentialDelayMs) + Math.random() * 250);
    }
  }

  throw new Error('Retry loop exhausted');
}

async function main(): Promise<void> {
  const jobId = process.argv[2];
  if (!jobId) throw new Error('Pass a batch job ID as the first argument');

  const client = new BatchTranscribeClient({
    api_url: requiredEnv('API_URL'),
    api_key: requiredEnv('API_KEY'),
    api_version: process.env.API_VERSION ?? 'v1',
  });
  try {
    const result = await getResultWithRetry(client, jobId);
    console.info('status:', result.status);
    console.info(result.results?.transcript ?? '');
  } finally {
    await client.close();
  }
}

void main().catch((error: unknown) => {
  console.error(error);
  process.exitCode = 1;
});

مرّر معرّف المهمة وسيطًا أول. الخرج المتوقع (توضيحي):

error: SERVER_INTERNAL 500
status: done
Hello and welcome to the meeting.

أعد محاولة submit() عند 429 أو 503 فقط. بعد 500 أو مهلة أو انقطاع اتصال قد تكون المهمة موجودة؛ راجع إعادة المحاولة والتكرار.

المهل والقيم الافتراضية

القيم بالثواني.

العميلالخيارالافتراضيالنطاق المسموح
BatchTranscribeClientpollInterval2الانتظار بين قراءات النتيجة في transcribe().
BatchTranscribeClienttimeout300الاستعلام الدوري في transcribe() بعد الرفع. يرمي BatchTranscribeTimeoutError.
FastTranscriptionClientلا شيءلا شيءلا مهلة في SDK؛ طبّق موعدك النهائي.
RealtimeClienttimeoutSeconds في stream.close()1انتظار is_final؛ يكتمل دون خطأ عند انتهاء المهلة. مرّر close(5).
RealtimeDiarizationClienttimeoutSeconds في stream.close()5انتظار التحديث النهائي؛ يكتمل بأفضل خط زمني معروف.
TTSClienttimeoutSeconds في listVoices()5انتظار قائمة الأصوات.
TTSClienttimeoutSeconds في synthesize() / synthesizeStream()30انتظار كل قطعة تالية. 0 يعطّله.

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

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

في هذه الصفحة