النسخ الفوري
ابثّ الصوت المباشر إلى HUMAIN Voice واعرض تسميات توضيحية تستقر في نص منسوخ نهائي وملف WebVTT.
تبث صوت PCM، وتطبع التسميات التوضيحية المباشرة كلما تغيرت، وتكتب recording.vtt من الكلمات النهائية. ثبّت SDK واضبط API_URL وAPI_KEY كما في البدء السريع. وتقرأ أمثلة Socket.IO أيضًا API_PATH الاختياري (إعدادات الاتصال).
تجهيز الصوت
حوّل التسجيل إلى PCM16 little-endian خام، بتردد 16 kHz، أحادي القناة:
ffmpeg -i recording.wav -f s16le -acodec pcm_s16le -ar 16000 -ac 1 recording.pcmيعيد الأمر أيضًا أخذ عينات صوت الهاتف بتردد 8 kHz إلى 16 kHz المطلوب. كل قطعة صوت حجمها 3,200 بايت تساوي 100 ms من الصوت. أرسل الصوت المباشر قطعة بعد قطعة فور وصوله؛ والتوقف لمدة 100 ms في المثال يعيد تشغيل الملف بإيقاع الزمن الفعلي فقط.
البث وعرض التسميات
يبث المثال recording.pcm في قطع حجمها 3,200 بايت، ويطبع كل نتيجة بالبادئة partial: أو speech-final: أو final:، وينتظر النتيجة النهائية حتى 5 ثوانٍ، ويكتب recording.vtt. يُطبع خطأ الخادم بالبادئة error: وينتهي التشغيل برمز خروج غير صفري.
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.حدّث تسمياتك التوضيحية بحسب العلامات في كل نتيجة (نتائج البث حالة وليست سجلًا):
| العلامات | الإجراء |
|---|---|
is_final وis_speech_final كلتاهما false | استبدل نص التسمية التوضيحية المؤقت. |
is_speech_final: true وis_final false | ثبّت الجملة المنطوقة وواصل البث. |
is_final: true | انتهى التدفق؛ ثبّت أي نص متبقٍ. |
لإنشاء ملف تسميات، اجمع كلمات كل نتيجة مثبّتة بترتيب وصولها ومررها إلى Subtitles (JavaScript، Python).
إنهاء التدفق
عند انتهاء الصوت، استدعِ close(5) في JavaScript أو close(timeout_seconds=5.0) في Python؛ فهو يرسل الإطار الأخير وينتظر is_final. قد تعود المهلة الافتراضية البالغة ثانية واحدة قبل وصول is_final، ويعود الإغلاق دون خطأ عند انتهاء المهلة، لذا افحص الخطأ الذي سجله معالج onError / on_error وهل وصل is_final.
التعافي من انقطاع التدفق
لا يمكن استئناف تدفق منقطع: احتفظ بالنص المثبّت، وأسقط النص المؤقت، وابدأ تدفقًا جديدًا.