النماذج واللغات والأصوات
راجع كل قيمة لغة ونموذج تحويل الكلام إلى نص ومستوى تمييز ونموذج TTS وصوت في HUMAIN Voice، مع ثوابت SDK 0.18.1 المطابقة.
يأخذ كل سير عمل مجموعة مختلفة من المحددات. تنطبق اللغة على كل سير عمل لتحويل الكلام إلى نص عدا التمييز المباشر. وينطبق نموذج التعرف التلقائي على الكلام (ASR) على النسخ الدفعي والسريع فقط. وتنطبق مستويات التمييز على النسخ الدفعي. أما TTS فيأخذ نموذجًا وصوتًا. لاختيار سير العمل نفسه راجع المفاهيم.
اللغات
يصدّر SDK لـJavaScript وPython أعضاء Language نفسها.
| قيمة البروتوكول | JavaScript | Python | بايت اللغة | الكلام |
|---|---|---|---|---|
ar | Language.Ar | stt.Language.Ar | 0 | العربية |
en | Language.En | stt.Language.En | 1 | الإنجليزية |
codeswitch | Language.ArEn | stt.Language.ArEn | 2 | العربية والإنجليزية مختلطتان في تسجيل واحد |
auto | — | — | 255 | الافتراضي في الخدمة |
تُوضع قيمة البروتوكول في مسار URL للنسخ الدفعي وفي معاملات استعلام النسخ السريع وبث HTTP. وبايت اللغة هو البايت 17 في ترويسات إطارات النسخ الفوري (والبايت 16 في حزمة النسخ السريع المباشرة عبر Socket.IO). تتحقق إطارات التمييز منه لكنها تتجاهله.
تُحل auto إلى الافتراضي المضبوط للبيئة، وهو حاليًا نموذج التبديل بين العربية والإنجليزية. لا يملك SDK 0.18.1
ثابتًا لها، فأرسلها فقط من تكامل API مباشر. وعلى مساري النسخ السريع وبث HTTP، يعطي حذف اللغة
الأثر نفسه. إذا لم تعرف لغة الصوت فاستخدم codeswitch؛ فهي تتعامل مع العربية والإنجليزية
ومع الاثنتين معًا.
نماذج تحويل الكلام إلى نص
يقبل النسخ الدفعي والسريع مفتاح نموذج ASR. أما النسخ الفوري والتمييز المباشر فلا يأخذان نموذجًا:
تقبل startStream() / start_stream() لغة فقط، وتختار الخدمة المتعرّف بنفسها.
| المفتاح | عضو التعداد (BatchTranscriptionModel / FastTranscriptionModel) | اللغات | دفعي | سريع | الحالة |
|---|---|---|---|---|---|
bayan_cs_ar_en | BayanArEn | العربية والإنجليزية والتبديل بينهما | نعم | نعم | موصى به؛ يتبع أحدث إصدار |
bayan_cs_ar_en_v2 | BayanArEnV2 | العربية والإنجليزية والتبديل بينهما | نعم | نعم | مثبّت على الإصدار الحالي |
bayan_ar | BayanAr | العربية | نعم | نعم | حالي |
nida_8k_ar | NidaArTelephony | العربية، هاتفي بتردد 8 kHz | نعم | لا | حالي؛ للنسخ الدفعي فقط |
bayan_auto | — | أي لغة | نعم | نعم | الافتراضي لـauto؛ بلا ثابت في SDK، مرّر السلسلة |
nida_ar | NidaAr | — | نعم | نعم | مدعوم |
fast_en | FastEn | — | نعم | نعم | مدعوم |
استخدم تعدادات كل مسار: BatchTranscriptionModel للنسخ الدفعي وFastTranscriptionModel
للنسخ السريع، مثل BatchTranscriptionModel.BayanArEn (في Python:
stt.BatchTranscriptionModel.BayanArEn). كلاهما مُصدَّر من humain_voice.stt في Python.
وتقبل المعاملات asr وasr_model أيضًا سلسلة مفتاح عادية. يستبعد FastTranscriptionModel
العضو NidaArTelephony لأنه نموذج هاتفي للنسخ الدفعي فقط. أما التعداد الأقدم ASRModel
فيضم الأعضاء السبعة كلها في SDK ويبقى للتوافق.
| سير العمل | معامل النموذج |
|---|---|
| النسخ الدفعي | asr اختياري. عند حذفه تستخدم الخدمة الافتراضي المضبوط للغة. |
| النسخ السريع (SDK) | مطلوب: تأخذ transcribe() لغة ونموذجًا. |
| النسخ السريع (API مباشرة) | اختياري. يأخذ HTTP المعامل asr (وله الاسم البديل model)؛ وتأخذ حزمة Socket.IO المباشرة الحقل asr_model_key. عند حذفه أو تركه فارغًا تستخدم الخدمة الافتراضي للغة. |
| النسخ الفوري، التمييز المباشر | لا يوجد. |
يعيد المفتاح المجهول، أو عدم ضبط افتراضي للغة أو لـauto، الخطأ 400 ASR_MODEL_NOT_FOUND. وجود ثابت في
SDK لا يضمن أن النموذج مهيأ لمفتاحك؛ فعالج هذا الخطأ. راجع
رموز الأخطاء.
اختيار نموذج بحسب حالة الاستخدام
| حالة الاستخدام | اللغة | النموذج |
|---|---|---|
| كلام عربي أو إنجليزي أو مختلط (الافتراضي) | codeswitch | bayan_cs_ar_en |
| يجب ألا تتغير النتائج عند صدور إصدار جديد | codeswitch | bayan_cs_ar_en_v2 |
| تسجيلات عربية فقط | ar | bayan_ar |
| تسجيلات مكالمات هاتفية عربية بتردد 8 kHz | ar | nida_8k_ar (دفعي) |
| صوت مباشر | codeswitch | لا يوجد؛ يختار النسخ الفوري النموذج |
ITN والحجب خياران للنسخ الدفعي؛ راجع واجهة REST للنسخ الدفعي.
مستويات تمييز المتحدثين
اضبط المعامل diarization في مهمة نسخ دفعي لتسمية من تحدث ومتى. لا مستوى للتمييز المباشر:
تختار الخدمة النموذج.
| القيمة | ثابت SDK 0.18.1 | المعنى |
|---|---|---|
0 أو false | BatchDiarization.Off | معطّل. حذف المعامل يعطّل التمييز أيضًا. |
1 أو true | BatchDiarization.On | مفعّل بالمستوى الافتراضي، وهو حاليًا d1. |
d1 | BatchDiarization.D1 | توازن بين الدقة والسرعة. |
d2 | BatchDiarization.D2 | تسجيلات فيها أكثر من 4 متحدثين. الأبطأ. |
d3 | — | حتى 4 متحدثين. الأسرع. الصوت الأقصر من 1 s لا يعيد أي مقاطع. |
لكل مستوى حد أقصى خاص به لمدة الصوت؛ راجع حدود النسخ الدفعي.
لا يملك SDK 0.18.1 ثابتًا لـd3 ويقبل أعضاء BatchDiarization فقط. استخدم
BatchDiarization.On الذي يُحل إلى d1 اليوم، أو أرسل diarization=d3 عبر
واجهة REST للنسخ الدفعي لتثبيته. وفي Python، استورد BatchDiarization من
humain_voice.stt.batchtranscription.
تسميات المتحدثين نسبية إلى نتيجة واحدة؛ راجع الخطوط الزمنية للمتحدثين في المفاهيم.
تحويل النص إلى كلام
لتحويل النص إلى كلام نموذج واحد، هو nebula (TtsModel.Nebula في كلا SDK). يرسله SDK 0.18.1 عند
حذف model؛ وفي تكامل Socket.IO المباشر أرسل model: "nebula" صراحةً. الخرج
صوت PCM16 خام؛ ومعدلات العينات لكل مسار في المفاهيم.
يحتاج كل طلب إلى محدد صوت واحد بالضبط:
| المحدد | القيمة |
|---|---|
voice_id | قيمة id لصوت من قائمة الأصوات. |
voice_references | مقطع WAV أحادي القناة بصيغة PCM16 مشفر بـbase64 مع نصه المنسوخ، لتكييف الصوت مع متحدث. الحدود في حدود تحويل النص إلى كلام. |
قائمة الأصوات
تعيد listVoices() / list_voices() ملفات أصوات متعددة اللغات. بدون SDK، أرسل حدث
Socket.IO المسمى tts_voice_list؛ راجع قائمة الأصوات. لا يوجد
مسار HTTP لقائمة الأصوات، فتحصل تكاملات TTS عبر HTTP على المعرّفات بالطريقة نفسها. لكل عنصر:
| الحقل | المعنى |
|---|---|
id | UUID للملف. أرسله كـvoice_id. ترفض الخدمة معرّفات المتغيرات الفيزيائية الداخلية. |
label | اسم مقروء، مثل mul_youssef. اعرضه ولا تطابق عليه. |
profile.speaker.gender | male أو female. |
profile.speaker.dialect | وسم BCP-47 للهجة الأساسية للمتحدث، مثل arz. |
profile.languages | وسوم BCP-47 للغات التي يستطيع الصوت التحدث بها، مثل ["ar", "en"]. |
profile.emotions | المشاعر التي يستطيع الصوت التحدث بها، وأولها neutral. يغيب حيث لا تكون المشاعر وأسلوب الإلقاء مفعّلة. في SDK الإصدار 0.18.1، أو 0.19.0-beta.3 أو أحدث (في Python: الإصدار 0.18.1، أو 0.19.0b3 أو أحدث). |
profile.styles | أساليب الإلقاء التي يستطيع الصوت استخدامها، مثل ["news"]. يغيب حيث لا تكون مفعّلة أو لا يملك الصوت أي أسلوب. في SDK الإصدار 0.18.1، أو 0.19.0-beta.3 أو أحدث (في Python: الإصدار 0.18.1، أو 0.19.0b3 أو أحدث). |
الأصوات المتاحة وقت الكتابة، وكلها تتحدث العربية والإنجليزية:
| التسمية | اللهجة |
|---|---|
mul_nourah، mul_abdullah، mul_sara، mul_abdulaziz | ars (العربية السعودية) |
mul_fadi | apc (العربية الشامية) |
mul_yassin | ary (العربية المغربية) |
mul_youssef | arz (العربية المصرية) |
قد تختلف المعرّفات والقائمة من بيئة إلى أخرى، فابحث عنها بالمثال أدناه بدل تثبيتها في الكود. القائمة الفارغة نتيجة صالحة؛ لا تلجأ إلى معرّف مخمَّن.
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
2f66da2d-eb4d-4376-b2fe-5631cebe1db7 mul_fadi apc ar,en
af52a907-1086-46f7-8f5d-72317875d7bd mul_youssef arz ar,enاختيار اللغة في الصوت
لا تمرّر لغة إلى TTS. إذا احتوى text أي حرف بالخط العربي فسيتحدث الصوت بالعربية؛ وإلا
فبالإنجليزية. الأرقام وعلامات الترقيم والرموز التعبيرية والمسافات وحروف الخطوط الأخرى لا
تختار العربية.