وقتی متن دریافت‌شده از کاربر را داخل SSML می‌گذارید، باید روشن باشد کدام بخش «متن خواندنی» است و کدام بخش «ساختار مجاز». کنارهم‌چسباندن رشتهٔ خام با برچسب‌ها ممکن است XML را خراب کند یا ساختاری متفاوت از قصد برنامه بسازد. این تمرین یک سازندهٔ کوچک با درخت کنترل‌شده دارد؛ اعتبارسنج عمومی SSML یا اتصال به موتور گفتار نیست.
ورودیِ ما متن ساده است، نه سند XML
متن نمونهٔ اصیل چنین است: نام آزمایشی: الف & ب؛ <audio src="demo.wav"/> فقط متن است. عبارت شبیه audio باید بخشی از متن بماند؛ برنامه آن را به عنصر audio تبدیل نمی‌کند. با API ساخت درخت، متن در p.text قرار می‌گیرد و serializer نشانه‌های لازم را escape می‌کند؛ متن را با رشتهٔ باز و بستهٔ XML جمع نمی‌زنیم.
در خروجی، آمپرسند به & و علامت آغاز برچسبِ داخل متن به < تبدیل می‌شود. وقتی XML دوباره خوانده شود، متن اصلی بازمی‌گردد؛ escape کردن به معنی حذف کلمه یا تغییر معنای عمدی نیست. چاپ فایل را با شنیدنِ موتور اشتباه نگیریم؛ اینجا صدا ساخته نشده است.
کدام ساختار را خود برنامه می‌سازد؟
فقط ریشهٔ speak با namespace استاندارد، version=۱٫۱ و xml:lang=fa-IR، یک p برای متن و یک break با مدتِ کنترل‌شده می‌سازیم. مقدار نمونهٔ مکث۳۰۰میلی‌ثانیه است. این مقدار توصیهٔ شنیداری برای همهٔ متن‌ها نیست و مکث انتهایی قرار دارد؛ سازندهٔ حاضر ویرایشگر جمله‌بندی یا مکث میان واژه‌ها نیست.
در قرارداد محلی، متن غیرخالی تا۲۰۰۰نقطهٔ کد و مکث عدد صحیح۰تا۲۰۰۰میلی‌ثانیه پذیرفته می‌شود. این سقف‌ها انتخابِ این تمرین‌اند، نه محدودیت استاندارد یا تعرفهٔ اپراگو. bool در Python با وجود نسبتش به int پذیرفته نشده است. کنترل‌های XML نامعتبر و surrogateهای منفرد نیز رد می‌شوند. پایان خط CR و CRLF در این قرارداد صریحاً رد می‌شود؛ متنِ چندخطی باید LF داشته باشد. XML هنگام خواندن، CR را نرمال می‌کند؛ پذیرفتن آن با ادعای حفظ عین متن سازگار نیست. این کد خودش پایان خط را بی‌خبر بازنویسی نمی‌کند.
سه سطح کنترل را جدا کنیم
| سطح | آزمون این نمونه | هنوز ثابت نمی‌کند |
|---|---|---|
| متن در برابر ساختار | عبارت شبیه audio عنصر تازه نمی‌سازد | مناسب‌بودن محتوای جمله برای کاربرد |
| XML خوش‌ساخت | خروجی ساخته‌شده دوباره parse می‌شود | انطباق کامل با XSD یا همهٔ قواعد SSML |
| پشتیبانی موتور | آزمایش نشده | پذیرش زبان، صدا، برچسب و تلفظ در سرویس واقعی |
نام زبان فارسی در xml:lang به‌خودی‌خود وجود صدای فارسی در موتور را تضمین نمی‌کند. همچنین XML معتبر می‌تواند برای ابزار مقصد پشتیبانی‌نشده باشد. قبل از ارسال، حالت ورودی متن ساده یا SSML و فهرست عناصر مجازِ همان موتور را بخوانید.
چرا XML دلخواه کاربر را parse نکرده‌ایم؟
دامنهٔ کار این سازنده متن ساده و یک تنظیم عددی است؛ بنابراین نیازی به قبول سندِ دلخواه، DTD، entity یا نشانی فایل و شبکه در markup ورودی ندارد. کد فقط XMLی را دوباره parse می‌کند که خودش از درخت محدود ساخته است. این انتخاب را راه‌حل عمومیِ دریافت XML نامطمئن معرفی نکنید؛ آن مسئله سیاست و پردازشگر مخصوص می‌خواهد.
آزمون‌ها واقعاً کنترل می‌کنند که متن پس از رفت‌وبرگشت یکسان باشد، فقط سه نام عنصر مجاز وجود داشته باشد و ورودی‌های خالی، مکثِ bool، مکثِ بیش از سقف، NUL ، surrogate منفرد و دو حالت CR و CRLF رد شوند. هیچ فایل demo.wav خوانده یا در شبکه درخواست نشده است؛ نام آن فقط داخل متن آزمایشی است.
قدم بعد برای متن به گفتار
آشنایی با مکث و سرعت در SSML معنای عناصر گفتاری را توضیح می‌دهد؛ این نوشته مرز متن و ساختار را با کد نشان می‌دهد. برای دریافت صدای فارسی از اپراگو متن و نیاز اجرایی را با تیم مطرح کنید تا نوع ورودیِ قابل ارائه مشخص شود. این آموزش پشتیبانی SSML در محصول یا کیفیت شنیداری خروجی را اعلام نمی‌کند.
فایل تمرین و منبع
ساخت درخت کنترل‌شده از متن ساده؛ بدون تفسیر markup ورودی · XML نمونه؛ عبارت شبیه audio به‌صورت متن escape شده
منابع در ۳ نوامبر ۲۰۲۶ خوانده شدند؛ این تاریخ، تاریخ انتشار منبع نیست. مثال‌ها و فایل‌های این راهنما آموزشی و ساختهٔ تحریریه‌اند.