JavaScript وTypeScript
انسخ الصوت، وابنِ الخطوط الزمنية للمتحدثين، وولّف الكلام من Node.js أو Bun باستخدام @humain-voice/sdk 0.18.1.
التثبيت
npm install @humain-voice/[email protected]اضبط عميلًا
لكل سير عمل عميله الخاص. يأخذ مُنشئ كل عميل كائن خيارات واحدًا:
| الاسم | النوع | الافتراضي | المعنى |
|---|---|---|---|
api_url | string | مطلوب | عنوان الخدمة الأساسي. |
api_key | string | مطلوب | مفتاح API. |
api_path | string | /socket.io | مسار Socket.IO. لكل عميل عدا النسخ الدفعي. |
api_version | string | v1 | إصدار REST. لـBatchTranscribeClient فقط. |
تقرأ الأمثلة هذه القيم من API_URL وAPI_KEY وAPI_PATH وAPI_VERSION؛ راجع
إعدادات الاتصال.
| سير العمل | العميل | التنظيف بـ |
|---|---|---|
| النسخ الدفعي | BatchTranscribeClient | close() |
| النسخ السريع | FastTranscriptionClient | close() |
| النسخ الفوري | RealtimeClient | disconnect() |
| التمييز المباشر | RealtimeDiarizationClient | disconnect() |
| تحويل النص إلى كلام | TTSClient | close() |
| جلسات Voice Agent | AgentClient (من @humain-voice/sdk/agent) | لا شيء للإغلاق |
يتصل عملاء Socket.IO عند أول استخدام؛ استدعِ connect() أولًا ليفشل الاتصال مبكرًا عند خطأ في المفتاح أو العنوان.
نظّف الموارد في finally. قيم اللغات والنماذج في النماذج والأصوات.
النسخ الدفعي
يرفع transcribe(audio, lang, options) ملفًا كاملًا، ويستعلم دوريًا حتى تصبح المهمة done، ثم
يعيد النص المنسوخ مع إزاحات الكلمات. للاستعلام الدوري من عامل خلفي، استدعِ submit(audio, lang, options)،
ثم getResult(jobId, lang, { saveResult }) حتى تصبح الحالة done أو failed أو cleared (راجع
النسخ الدفعي مهمة).
| الاسم | النوع | الافتراضي | المعنى |
|---|---|---|---|
audio | ArrayBuffer أو Uint8Array أو Blob أو File | مطلوب | الصوت المراد رفعه. |
lang | Language أو string | مطلوب | اللغة المنطوقة. |
asr | BatchTranscriptionModel أو string | غير معيّن | نموذج ASR. |
diarization | BatchDiarization | غير معيّن | On أو D1 أو D2 تسمّي المتحدثين. |
itn | boolean | غير معيّن | تطبيع النص العكسي. |
redact | BatchRedact | غير معيّن | BatchRedact.On يفعّل الحجب. |
saveResult | boolean | false | أبقِ النتيجة قابلة للقراءة بعد جلبها؛ راجع اقرأ النتيجة مرة أخرى. ليس في submit(). |
pollInterval | number | 2 | الثواني بين قراءات النتيجة. لـtranscribe() فقط. |
timeout | number | 300 | حد الاستعلام الدوري بالثواني. لـtranscribe() فقط. |
onProgress | (status: TranscriptionResponse) => void | غير معيّن | تُستدعى عند كل قراءة للنتيجة. لـtranscribe() فقط. |
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. يجمّع هذا المثال الكلمات في
أدوار المتحدثين:
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_source | ArrayBuffer أو Uint8Array أو Blob | مطلوب | المقطع المراد نسخه. |
language | Language | مطلوب | اللغة المنطوقة. |
asr_model | FastTranscriptionModel أو string | مطلوب | نموذج ASR. |
onResponse | دالة | غير معيّن | تستقبل النتائج الجزئية، ثم النهائية. |
onFileUpload | دالة | غير معيّن | تستقبل إيصال الرفع. |
onError | دالة | غير معيّن | تستقبل ErrorResponse. |
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() | language | Language | مطلوب | اللغة المنطوقة. |
startStream() | onResponse | دالة | غير معيّن | تستقبل النتائج المؤقتة والنهائية. |
startStream() | onError | دالة | غير معيّن | تستقبل ErrorResponse. |
stream.send() | audioBytes | Uint8Array | مطلوب | قطعة صوت واحدة. |
stream.close() | timeoutSeconds | number | 1 | انتظار is_final. مرّر 5. |
يرسل المثال قطعًا من 3,200 بايت (100 ms) ويكتب التسميات التوضيحية من الكلمات النهائية. لإنشاء
recording.pcm، راجع جهّز الصوت.
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.
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? }:
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.
| الاسم | النوع | الافتراضي | المعنى |
|---|---|---|---|
text | string | مطلوب | النص المراد نطقه. |
voice_id | string | غير معيّن | معرّف الصوت من listVoices(). |
voice_references | { text: string; audio: string }[] | غير معيّن | مقاطع مرجعية للاستنساخ؛ audio بصيغة WAV مشفرة base64. |
model | TtsModel أو string | TtsModel.Nebula | نموذج TTS. |
timeoutSeconds | number | 30 | انتظار كل قطعة تالية؛ 0 يعطّله. |
onAudio | دالة | غير معيّن | تستقبل كل قطعة. لـsynthesize() فقط. |
onError | دالة | غير معيّن | تستقبل ErrorResponse. |
request_id | string | مولّد | معرّف الطلب. |
يضيف هذا المثال ترويسة WAV ويكتب speech.wav:
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 -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' } | مطلوب | المستخدم الذي ينضم إلى المكالمة. |
agent | AgentConfig | غير مضبوط | prompt وintro وvoiceId وclientTools وtoolAcknowledgments (مع afterMs). تُرسل parameters للأداة دون تغيير. |
variables | Record<string, string | number | boolean> | غير مضبوط | قيم العناصر النائبة {{name}}. |
idempotencyKey | string | غير مضبوط | يُرسل كـIdempotency-Key، فتعيد إعادة المحاولة الجلسة الأولى. |
timeoutSeconds | number | 10 | مهلة الطلب. |
يعيد 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.
| الاسم | النوع | الافتراضي | المعنى |
|---|---|---|---|
maxDurationSeconds | number | 6 | أطول تسمية. |
maxGapSeconds | number | 0.7 | الصمت الذي يبدأ تسمية جديدة. |
minDurationSeconds | number | 0.5 | أقصر تسمية. |
maxCharsPerLine | number | 42 | عرض السطر. |
maxLines | number | 2 | عدد الأسطر في التسمية. |
splitOnSpeakerChange | boolean | true | ابدأ تسمية جديدة عند تغيّر المتحدث. |
strict | boolean | false | ارمِ SubtitleError عند توقيت معطوب بدل إصلاحه أو تخطيه. |
للتسميات التوضيحية المباشرة، اجمع words من كل نتيجة is_speech_final وis_final، ثم
استدعِ Subtitles.fromWords() كما يفعل مثال النسخ الفوري.
الأخطاء
ترمي طرق النسخ الدفعي أصنافًا فرعية من BatchTranscribeError:
| الصنف | متى | الحقول |
|---|---|---|
BatchTranscribeError | أي استجابة غير 2xx، أو api_url / api_key فارغ | statusCode, code, retryable, jobId, capacity, rawBody |
BatchTranscribeAuthError | 401 | مثل ما سبق |
BatchTranscribeRateLimitError | 429 | retryAfter (بالثواني؛ غير معيّن ما لم يكن Retry-After عددًا صحيحًا) |
BatchTranscribeJobFailedError | بلغت المهمة failed | error, errorCode |
BatchTranscribeTimeoutError | تجاوز transcribe() قيمة timeout | jobId, elapsed |
تُرمى TypeError عند أعطال الشبكة من fetch؛ أعد محاولتها في قراءات getResult(). يمرّر عملاء Socket.IO
ErrorResponse إلى onError: تفرّع على code وretryable، واقرأ
retry_after_seconds وdata وretry_scope (القيمة new_stream تعني افتح تدفقًا جديدًا). تَرمي
مكررات التمييز DiarizationStreamError، وتكون response فيه هي ErrorResponse. الرموز وقواعد
إعادة المحاولة في الأخطاء والحدود.
يعيد هذا المثال محاولة قراءة نتيجة دفعية، بما في ذلك بعد فشل الشبكة، مع التراجع و
saveResult: true:
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 أو مهلة أو انقطاع اتصال قد تكون المهمة
موجودة؛ راجع إعادة المحاولة والتكرار.
المهل والقيم الافتراضية
القيم بالثواني.
| العميل | الخيار | الافتراضي | النطاق المسموح |
|---|---|---|---|
BatchTranscribeClient | pollInterval | 2 | الانتظار بين قراءات النتيجة في transcribe(). |
BatchTranscribeClient | timeout | 300 | الاستعلام الدوري في transcribe() بعد الرفع. يرمي BatchTranscribeTimeoutError. |
FastTranscriptionClient | لا شيء | لا شيء | لا مهلة في SDK؛ طبّق موعدك النهائي. |
RealtimeClient | timeoutSeconds في stream.close() | 1 | انتظار is_final؛ يكتمل دون خطأ عند انتهاء المهلة. مرّر close(5). |
RealtimeDiarizationClient | timeoutSeconds في stream.close() | 5 | انتظار التحديث النهائي؛ يكتمل بأفضل خط زمني معروف. |
TTSClient | timeoutSeconds في listVoices() | 5 | انتظار قائمة الأصوات. |
TTSClient | timeoutSeconds في synthesize() / synthesizeStream() | 30 | انتظار كل قطعة تالية. 0 يعطّله. |
يطبّق الخادم مواعيده النهائية الخاصة لـTTS؛ راجع المهل.