ریئل ٹائم ٹیکسٹ ٹو اسپیچ (TTS)
متن کو بتدریج اسٹریم کریں اور فوری طور پر خام PCM یا MP3 آڈیو بائٹس حاصل کریں
ریئل ٹائم ٹیکسٹ ٹو اسپیچ اسٹریمنگ کے لیے دو طرفہ WebSocket کنکشن قائم کرتا ہے۔ متن کے حصے بتدریج بھیجیں (LLM آؤٹ پٹ کے لیے بہترین) اور مسلسل بائنری آڈیو اسٹریمز حاصل کریں۔ کریڈٹس کا حساب HTTP اینڈ پوائنٹ کی طرح ہی لگایا جاتا ہے۔
انتہائی کم تاخیر (~200ms ٹائم ٹو فرسٹ بائٹ) حاصل کرنے کے لیے، یقینی بنائیں کہ آپ کے متن کے حصے واضح رموزِ اوقاف (ختمہ .، فجائیہ نشان !، یا سوالیہ نشان ؟) پر ختم ہوں۔ مصنوعی ذہانت بہترین انسانی لب و لہجہ یقینی بنانے کے لیے جملے کی حد شناخت ہونے تک متن کو قدرتی طور پر بفر کرتی ہے۔
تصدیق
WebSocket ہینڈ شیک کے دوران Authorization ہیڈر استعمال کرتے ہوئے تصدیق کریں:
Authorization: Bearer YOUR_API_KEY
کنکشن کی ترتیب
جڑنے کے بعد، اپنی مطلوبہ ترتیبات کے ساتھ ابتدائی پیغام بھیجیں:
{
"type": "init",
"voice_id": 1710,
"prerecording": 1,
"language": "ar",
"output_format": "pcm_24000",
"voice_settings": {
"temperature": 25,
"similarity": 100,
"expressiveness": 0,
"speed": 1.0,
"fast_mode": 2
}
}
ابتدائی پیرامیٹرز
| پیرامیٹر | لازمی | قسم | تفصیل |
|---|---|---|---|
| type | لازمی | اسٹرنگ (string) | ابتدائی پیغام کے لیے لازمی طور پر "init" ہونا چاہیے۔ |
| voice_id | لازمی | عددی (integer) | وائس ID از آوازوں کی فہرست. |
| output_format | اختیاری | اسٹرنگ (string) | مطلوبہ آڈیو فارمیٹ۔ ڈیفالٹ pcm_24000 ہے۔ اختیارات میں شامل ہیں:
|
| prerecording | اختیاری | عددی (integer) | 1 (نارمل، ڈیفالٹ)، 2 (AI بہتری / عربی تشکیل) یا 3 (AI شاعر)۔ کریڈٹ کی لاگت پر اثر انداز ہوتا ہے۔ 2 اور 3 صرف عربی مواد کے لیے دستیاب ہیں؛ language دیکھیں۔ |
| language | اختیاری | اسٹرنگ (string) | مواد کی زبان بطور ISO 639-1 کوڈ، مثال کے طور پر ar یا en (علاقائی کوڈز جیسے ar-JO قابل قبول ہیں)۔ یہ طے کرتا ہے کہ کون سے پری ریکارڈنگ موڈز کی اجازت ہے اور اسے آواز کو نہیں بھیجا جاتا۔ موڈز 2 اور 3 صرف عربی (ar) کے لیے دستیاب ہیں۔ اگر language چھوڑ دیا جائے تو 2 اور 3 کا مطلب عربی ہی لیا جاتا ہے، تاکہ موجودہ انٹیگریشنز کام کرتی رہیں۔ 2 یا 3 کے ساتھ کوئی دوسری زبان، یا کوئی نامعلوم کوڈ دینے پر ایرر پیغام ملتا ہے اور اسٹریم شروع نہیں ہوتی۔ |
| voice_settings | اختیاری | آبجیکٹ (object) | آواز کی تخصیص کے اختیارات۔ نیچے آواز کی ترتیبات کا سیکشن دیکھیں۔ |
آواز کی ترتیبات کا آبجیکٹ
اسٹریمنگ دونوں انجنوں کے ساتھ اپنے فی حرف ریٹ پر کام کرتی ہے، جسے موڈ سے ضرب دیا جاتا ہے: emotion (ڈیفالٹ) اور fast_mode ×1، quality اور studio ×2۔ ایڈوانسڈ انجن کی آوازوں کی لاگت ×1.5 ہے۔
- اسٹینڈرڈ انجن کی آوازیں ہر موڈ میں اسٹریم ہوتی ہیں: emotion (ڈیفالٹ، سب سے کم تاخیر)، quality، اور studio۔ fast_mode کم تاخیر والے ماڈل پر منتقل کر دیتا ہے۔
- ایڈوانسڈ انجن کی آوازیں جملہ بہ جملہ اسٹریم ہوتی ہیں: ہر جملے کی آڈیو اس کے مکمل ہوتے ہی شروع ہو جاتی ہے۔ pcm_* یا mp3_* آؤٹ پٹ فارمیٹس استعمال کریں (ان آوازوں کے لیے Opus دستیاب نہیں ہے)۔
معیاری انجن کی آوازیں
| پیرامیٹر | قسم | رینج | ڈیفالٹ | تفصیل |
|---|---|---|---|---|
| mode | اسٹرنگ (string) | emotion, quality, studio | emotion | اختیاری۔ emotion (جذبات اور لہجہ، ×1)، quality (معیاری جذبات اور لہجہ، ×2) یا studio (اسٹوڈیو کوالٹی، ×2)۔ emotion اور quality میں صرف temperature اور similarity لاگو ہوتے ہیں۔ |
| temperature | عددی (integer) | 0 – 100 | 25 | کم = مستحکم اور قابلِ پیش گوئی، زیادہ = تخلیقی اور متنوع۔ |
| similarity | عددی (integer) | 0 – 100 | 100 | آواز اصل وائس کلون سے کس حد تک مشابہت رکھتی ہے۔ |
| speed | اعشاری عدد (float) | 0.5 – 2.0 | 1.0 | پلے بیک اسپیڈ ملٹی پلائر۔ |
| fast_mode | عددی (integer) | 0, 1, or 2 | 0 | 1 یا 2 کم لیٹنسی ماڈل (×1 کریڈٹس) پر منتقل کرتا ہے اور mode کو اوور رائیڈ کرتا ہے۔ 0 = بند۔ |
ایڈوانسڈ انجن کی آوازیں
| پیرامیٹر | قسم | قدریں | تفصیل |
|---|---|---|---|
| context | اسٹرنگ (string) | 500 حروف تک | سب سے مضبوط کنٹرول۔ لہجہ، احساس، موڈ یا مقصد بیان کریں۔ |
| setting | اسٹرنگ (string) | 500 حروف تک | منظر اور موڈ۔ |
| style | اسٹرنگ (string) | neutral, warm, energetic, serious, cheerful, poetic | ادائیگی کا مجموعی انداز۔ |
| pace | اسٹرنگ (string) | slow, normal, fast | بولنے کی رفتار۔ |
مشورہ: تیز ترین پہلی آڈیو حاصل کرنے کے لیے مکمل جملے (جو . ! ? یا نئی لائن پر ختم ہوں) بھیجیں۔
اسٹریمنگ پائپ لائن
1. متن کے ٹکڑے بھیجیں
جیسے جیسے آپ کا LLM متن تیار کرے، اسے بتدریج بھیجیں:
{"type": "text", "data": "مرحبا بكم."}
سرور فوری طور پر اس ٹکڑے کو پروسیس کرے گا، اس لمبائی کے مخصوص کریڈٹس کاٹے گا، اور واپس آڈیو اسٹریم کرنا شروع کر دے گا۔
2. تکمیل کا اشارہ دیں (روکیں)
جب آپ کے متن کی تیاری مکمل ہو جائے تو روکنے کا سگنل بھیجیں:
{"type": "stop"}
سرور اپنے بفر میں موجود بقیہ متن کی سنتھیسز مکمل کرے گا، آڈیو کے آخری بائٹس آپ کو بھیجے گا، اور اسٹریمنگ کے اختتام کا سگنل بھیج دے گا۔
پیغامات کی وصولی
سرور WebSocket کے ذریعے دو طرح کے فریم بھیجتا ہے:
1. بائنری آڈیو ٹکڑے (PCM / MP3)
خام آڈیو بائٹس جیسے ہی تیار ہوتے ہیں تیزی سے اسٹریم کیے جاتے ہیں۔ فارمیٹ آپ کے مطلوبہ output_format پر منحصر ہے (ڈیفالٹ 24kHz پر 16-bit PCM ہے)۔ اگر آپ نے MP3 کی درخواست کی ہے، تو آپ ان بائٹس کو براہِ راست فائل میں لکھ سکتے ہیں۔
2. JSON کنٹرول پیغامات
ابتدائی تیاری مکمل:
{"status": "ready", "message": "شروع ہو چکا ہے اور متن وصول کرنے کے لیے تیار ہے۔"}
اسٹریمنگ کا اختتام (محفوظ بندش کا سگنل):
{"type": "end_of_stream"}
جب آپ کو یہ پیغام موصول ہوتا ہے، تو یہ ریاضیاتی طور پر یقینی بناتا ہے کہ آڈیو کے 100% ٹکڑے پہنچا دیے گئے ہیں۔ اب آپ کلائنٹ سائیڈ پر WebSocket کنکشن کو محفوظ طریقے سے بند کر سکتے ہیں۔
اسٹریمنگ کے دوران خرابی:
{"error": "سٹریم کے دوران ناکافی کریڈٹس"}
پروڈکشن کے لیے تیار مثالیں
# pip install websockets
import asyncio
import websockets
import json
API_KEY = "YOUR_API_KEY"
url = "wss://api.moknah.io/api/v1/tts/ws/"
async def stream_tts():
headers = {"Authorization": f"Bearer {API_KEY}"}
async with websockets.connect(url, additional_headers=headers) as ws:
# 1. Initialize session (Requesting MP3 so we can save to file)
await ws.send(json.dumps({
"type": "init",
"voice_id": 1710,
"output_format": "mp3_44100_128",
"voice_settings": {"fast_mode": 2}
}))
print(f"Server: {await ws.recv()}")
# 2. Receiver Task
async def receive_audio():
with open("audio.mp3", "wb") as f:
async for msg in ws:
if isinstance(msg, bytes):
f.write(msg)
else:
data = json.loads(msg)
if data.get("type") == "end_of_stream":
print("✅ Stream finished safely.")
await ws.close()
break
receiver = asyncio.create_task(receive_audio())
# 3. Send Text
for chunk in ["مرحبا بكم.", "في منصة مُكنة."]:
await ws.send(json.dumps({"type": "text", "data": chunk}))
await asyncio.sleep(0.5)
# 4. Signal Stop
await ws.send(json.dumps({"type": "stop"}))
await receiver
asyncio.run(stream_tts())
// npm install ws
const WebSocket = require('ws');
const fs = require('fs');
const API_KEY = "YOUR_API_KEY";
const ws = new WebSocket('wss://api.moknah.io/api/v1/tts/ws/', {
headers: { "Authorization": `Bearer ${API_KEY}` }
});
const audioStream = fs.createWriteStream('audio.mp3');
ws.on('open', function open() {
// Requesting MP3 to safely write to an MP3 file
ws.send(JSON.stringify({
type: "init",
voice_id: 1710,
output_format: "mp3_44100_128",
voice_settings: { fast_mode: 2 }
}));
});
ws.on('message', function incoming(data, isBinary) {
if (isBinary) {
audioStream.write(data); // Save MP3 chunks
} else {
const msg = JSON.parse(data.toString());
if (msg.status === 'ready') {
console.log("Ready! Sending text...");
ws.send(JSON.stringify({ type: "text", data: "مرحبا بكم." }));
setTimeout(() => ws.send(JSON.stringify({ type: "text", data: "في منصة مُكة." })), 500);
setTimeout(() => ws.send(JSON.stringify({ type: "stop" })), 1000);
} else if (msg.type === 'end_of_stream') {
console.log("✅ All audio received. Closing connection.");
ws.close();
}
}
});
<?php
// composer require textalk/websocket
require 'vendor/autoload.php';
use WebSocket\Client;
$apiKey = "YOUR_API_KEY";
$client = new Client("wss://api.moknah.io/api/v1/tts/ws/", [
'headers' => ['Authorization' => "Bearer $apiKey"],
'timeout' => 60
]);
// 1. Initialize (Requesting MP3 format)
$client->text(json_encode([
"type" => "init",
"voice_id" => 1710,
"output_format" => "mp3_44100_128",
"voice_settings" => ["fast_mode" => 2]
]));
echo "Server: " . $client->receive() . "\n";
// 2. Send Text Chunks
$client->text(json_encode(["type" => "text", "data" => "مرحبا بكم."]));
$client->text(json_encode(["type" => "text", "data" => "في منصة مُكنة."]));
$client->text(json_encode(["type" => "stop"]));
// 3. Receive Audio & Control Messages
$audioFile = fopen("audio.mp3", "wb");
while (true) {
$message = $client->receive();
$decoded = json_decode($message, true);
if ($decoded && isset($decoded['type']) && $decoded['type'] == 'end_of_stream') {
echo "✅ Stream finished successfully.\n";
break;
} elseif (!$decoded) {
// If it can't be decoded as JSON, it's our binary MP3 audio chunk
fwrite($audioFile, $message);
}
}
fclose($audioFile);
$client->close();
?>
# Standard cURL does not support bidirectional WebSockets easily.
# Use 'websocat' to test WebSockets from the command line:
websocat wss://api.moknah.io/api/v1/tts/ws/ \
-H "Authorization: Bearer YOUR_API_KEY"
# Once connected, paste the JSON payloads interactively:
{"type": "init", "voice_id": 1710, "output_format": "mp3_44100_128"}
{"type": "text", "data": "مرحبا بكم."}
{"type": "stop"}
بندش کے کوڈز اور خرابیاں
WebSocket کنکشن ان معیاری کوڈز میں سے کسی ایک کے ساتھ بند ہو سکتا ہے:
| کوڈ | قسم | تفصیل |
|---|---|---|
1000 |
SUCCESS | اسٹریم قدرتی طور پر مکمل ہو گئی۔ |
3011 |
GENERATION_ERROR | اپ سٹریم API پر آڈیو جنریشن ناکام ہو گئی۔ درخواست دوبارہ کوشش کریں۔ |
4001 |
MISSING_API_KEY | Authorization ہیڈر میں کوئی API کلید فراہم نہیں کی گئی۔ |
4002 |
AUTH_FAILED | غلط کلید، غیر فعال اکاؤنٹ، ناکافی ابتدائی کریڈٹس، یا IP پابندی۔ |
4290 |
CONCURRENT_LIMIT | صارف کے پاس پہلے سے ہی ایک فعال TTS WebSocket کنکشن موجود ہے۔ فی صارف حد 1 ہے۔ |
API سے متعلق سوالات یا مسائل کے لیے، ہم سے یہاں رابطہ کریں api@moknah.io.