نمونه کدهای اتصال

وب‌سرویس ابری آریانا مبتنی بر استاندارد REST و بر پایه پروتکل HTTP طراحی شده است.

برای استفاده از سرویس ابری آریانا نیاز به دریافت کد کاربری (APIKey) دارید. برای این می‌توانید به وبسایت عصر گویش پرداز مراجعه نموده و پس از ثبت نام در سایت، از آدرس http://asr-gooyesh.com/fa/arianacloud-dashboard کد کاربری خود را دریافت نمایید و از شارژ رایگان اولیه استفاده نمایند.

متد GET

http://api.farsireader.com/ArianaCloudService/ReadTextGET?APIKey={KEY}&Text={TEXT}&Speaker={SPEAKER}&Format={FORMAT}&GainLevel={GAIN}&PitchLevel={PITCH}&PunctuationLevel={PUNCTUATION}&SpeechSpeedLevel={SPEED}&ToneLevel={TONE}&Quality={QUALITY}&BeginningSilence={SEC}&EndingSilence={SEC}&Base64Encode={TYPE}

مثال:

http://api.farsireader.com/ArianaCloudService/ReadTextGET?APIKey=XYZ&Text=hello&Speaker=Female1&Format=mp3&GainLevel=0&PitchLevel=0&PunctuationLevel=0&SpeechSpeedLevel=0&ToneLevel=0 uality=normal&BeginningSilence=0&EndingSilence=0&Base64Encode=0

یا به طور خلاصه:

http://api.farsireader.com/ArianaCloudService/ReadTextGET?APIKey=XYZ&Text=hello&Speaker=Female1&Format=mp3

در متد GET پارامترهای Text و Format باید به فرمت URL Encoded تبدیل شوند. برای مثال، عبارت “تست” به صورت “%D8%AA%D8%B3%D8%AA” ارسال می‌شود.

همچنین توجه شود که در این متد، با رسیدن هر درخواست به سرور، شارژ حساب کاربری به تعداد مجموع کلمات (هر پیام معادل حداکثر 25 کلمه) کسر خواهد شد. در بعضی مرورگرها و یا ابزارهای دانلود، رایج است که برای تسریع بارگذاری فایل، درخواست‌های (Connection) مکرر و همزمان به سمت سرور ارسال می‌شود که هر کدام از این درخواست‌ها باعث کسر شارژ از حساب کاربری خواهد شد. بنابراین توصیه می‌شود فایل صوتی حاصل از متد GET را فقط با یک Connection دانلود نمایید.

متد POST

http://api.farsireader.com/ArianaCloudService/ReadText

فرمت ورود داده‌ها بدین شکل است:

Content-type: application/json

{
“Text”:”متن درخواستی”,
“Speaker”:”Female1″,
“PitchLevel”:”0″,
“PunctuationLevel”:”0″,
“SpeechSpeedLevel”:”0″,
“ToneLevel”:”0″,
“GainLevel”:”0″,
“BeginningSilence”:”0″,
“EndingSilence”:”0″,
“Format”:”mp3″,
“Base64Encode”:”0″,
“Quality”:”normal”,
“APIKey”:”mykey”
}

توجه شود که حتماً در Header درخواست POST، نوع داده (Content-type) به صورت application/json مشخص گردد.

سرویس آریانا پس از پردازش متن درخواستی، صوت تبدیل شده را در جواب به صورت Byte Stream ارسال می‌نماید.
درخواست پردازش متن به صورت غیر هم‌زمان (Blocking) بوده و کلاینت موظف است تا اتمام پردازش متن و آماده شدن کامل صوت، منتظر پاسخ بماند. لذا نیاز است پارامتر Timeout در کلاینت به مقدار مناسبی تنظیم شود تا درخواست POST قبل از اتمام پردازش قطع نشود. مقدار پیشنهادی این پارامتر برای متن طولانی، حداقل 120 ثانیه است.

شرح پارامترها

Textمتن درخواستی برای پردازش
Speakerگوینده متن
مقادیر: Female1, Male2, Male1 (پیش‌فرض Female1)
انتخاب پیش‌فرض: ” (empty string)
PitchLevelمیزان زیر و بمی صدا
مقادیر: 1 تا 10 (پیش‌فرض 4)
انتخاب پیش‌فرض: 0
PunctuationLevelسطح خواندن علائم نگارشی
مقادیر: 1 تا 3 (پیش‌فرض 2)
انتخاب پیش‌فرض: 0
SpeechSpeedLevelسرعت خواندن
مقادیر: 1 تا 10 (پیش‌فرض 5)
انتخاب پیش‌فرض: 0
ToneLevelتن صدا
مقادیر: 1 تا 19 (پیش‌فرض 10)
انتخاب پیش‌فرض: 0
GainLevelبلندی صدا
مقادیر: 1 تا 5 (پیش‌فرض 3)
انتخاب پیش‌فرض: 0
BeginningSilenceتعداد ثانیه های سکوت ابتدای صوت
مقادیر: 0 تا 5 (پیش‌فرض 0)
EndingSilenceتعداد ثانیه های سکوت انتهای صوت
مقادیر: 0 تا 5 (پیش‌فرض 0)
Formatمقادیر فرمت گفتار تبدیل شده:

wav16: Wave 16KHz Mono 16bit
alaw16: Wave 16KHz Mono a-law 8bit
mlaw16: Wave 16KHz Mono mu-law 8bit
wav8: Wave 8KHz Mono 16bit
alaw8: Wave 8KHz Mono a-law 8bit
mlaw8: Wave 8KHz Mono mu-law 8bit
mp3: MP3 32Kbps Mono
ogg: OGG (Opus) 32Kbps Mono
raw16: Raw Wave 16KHz Mono 16bit, Without 44 Bytes Wave Header

(پیش‌فرض wav16)
انتخاب پیش‌فرض: ” (empty string)

Qualityکیفیت صدای ساخته شده
مقادیر:
normal: صدا با کیفیت نرمال – پیش فرض
low: صدا با کیفیت کم‌تر و زمان ساخت سریع‌تر
Base64Encodeاستفاده از Base64 Encoding در ارسال متن ورودی و بافر صوتی خروجی
مقادیر: 0 تا 4 (پیش‌فرض 0)
مقادیر 0 و 1 از Base64 Encoding استفاده نمی‌شود.
مقدار 2 برای ارسال متن ورودی از Base64 Encoding استفاده شده است.
مقدار 3 برای ارسال بافر صوتی خروجی از Base64 Encoding استفاده می‌شود.
مقدار 4 برای ارسال متن ورودی و بافر صوتی خروجی از Base64 Encoding استفاده می‌شود.
APIKeyکد کاربری استفاده از سرویس ابری آریانا که در پنل کاربری در سایت قابل دسترسی است.

انتخاب پیش‌فرض، مقداری را انتخاب می‌کند که در آریانا کنسول در قسمت Speech/Text Defaults تعیین شده است.

اتصال به سرویس REST آریانا

وب‌سرویس آریانا مبتنی بر استاندارد REST و بر پایه پروتکل HTTP طراحی شده است. دسترسی به این سرویس از طریق متد تشریح شده در ذیل ممکن است. برنامه‌های نمونه شامل تمام قابلیت‌های موجود در سرویس آریانا به همراه سورس‌کد مربوطه در پوشه نصب آریانا قابل دسترس هستند.

آدرس متد

http://{ServerIP}:{ServerPort}/ArianaRESTService/ReadText/

مقدار پیش فرض Server Port تنظیم شده در کنسول آریانا، 1385 است.

ساختارهای فراخوانی

فراخوانی متد توسط HTTP POST انجام می‌شود.
فرمت ورود داده‌ها بدین شکل است:

Content-type: application/json

{
“Text”:”متن درخواستی”,
“Speaker”:”Female1″,
“PitchLevel”:”0″,
“PunctuationLevel”:”0″,
“SpeechSpeedLevel“:”0“,
“ToneLevel”:”0“,
“GainLevel”:”0“,
“BeginningSilence”:”0“,
“EndingSilence”:”0“,
“Format”:”mp3″,
“Quality”:”normal”,
“Base64Encode“:”0”,
“Username”:”test”,
“Password”:”test”
}

توجه شود که حتماً در Header درخواست POST، نوع داده (Content-type) به صورت application/json مشخص گردد.

سرویس آریانا پس از پردازش متن درخواستی، صوت تبدیل شده را در جواب به صورت Byte Stream ارسال می‌نماید.
درخواست پردازش متن به صورت غیر هم‌زمان (Blocking) بوده و کلاینت موظف است تا اتمام پردازش متن و آماده شدن کامل صوت، منتظر پاسخ بماند. لذا نیاز است پارامتر Timeout در کلاینت به مقدار مناسبی تنظیم شود تا درخواست POST قبل از اتمام پردازش قطع نشود. مقدار پیشنهادی این پارامتر برای متن طولانی، حداقل 120 ثانیه است.

شرح پارامترها

Textمتن درخواستی برای پردازش
Speakerگوینده متن
مقادیر: Female1, Male1 (پیش‌فرض Female1)
انتخاب پیش‌فرض: ” (empty string)
PitchLevelمیزان زیر و بمی صدا
مقادیر: 1 تا 10 (پیش‌فرض 4)
انتخاب پیش‌فرض: 0
PunctuationLevelسطح خواندن علائم نگارشی
مقادیر: 1 تا 3 (پیش‌فرض 2)
انتخاب پیش‌فرض: 0
SpeechSpeedLevelسرعت خواندن
مقادیر: 1 تا 10 (پیش‌فرض 5)
انتخاب پیش‌فرض: 0
ToneLevelتن صدا
مقادیر: 1 تا 19 (پیش‌فرض 10)
انتخاب پیش‌فرض: 0
GainLevelبلندی
مقادیر: 1 تا 5 (پیش‌فرض 3)
انتخاب پیش‌فرض: 0
BeginningSilenceتعداد ثانیه های سکوت ابتدای صوت
مقادیر: 0 تا 5 (پیش‌فرض 0)
EndingSilenceتعداد ثانیه های سکوت انتهای صوت
مقادیر: 0 تا 5 (پیش‌فرض 0)
Formatفرمت گفتار تبدیل شده
مقادیر:

wav16: Wave 16KHz Mono 16bit
alaw16: Wave 16KHz Mono a-law 8bit
mlaw16: Wave 16KHz Mono mu-law 8bit
wav8: Wave 8KHz Mono 16bit
alaw8: Wave 8KHz Mono a-law 8bit
mlaw8: Wave 8KHz Mono mu-law 8bit
mp3: MP3 32Kbps Mono
ogg: OGG (Opus) 32Kbps Mono
raw16: Raw Wave 16KHz Mono 16bit, Without 44 Bytes Wave Header

(پیش‌فرض wav16)
انتخاب پیش‌فرض: ” (empty string)

Qualityکیفیت صدای ساخته شده
مقادیر:
normal: صدا با کیفیت نرمال – پیش فرض
low: صدا با کیفیت کم‌تر و زمان ساخت سریع‌تر
Base64Encodeاستفاده از Base64 Encoding در ارسال متن ورودی و بافر صوتی خروجی
مقادیر: 0 تا 4 (پیش‌فرض 0)
مقادیر 0 و 1 از Base64 Encoding استفاده نمی‌شود.
مقدار 2 برای ارسال متن ورودی از Base64 Encoding استفاده شده است.
مقدار 3 برای ارسال بافر صوتی خروجی از Base64 Encoding استفاده می‌شود.
مقدار 4 برای ارسال متن ورودی و بافر صوتی خروجی از Base64 Encoding استفاده می‌شود.
Username/ Passwordنام کاربری و گذرواژه تعریف شده در تنظیمات آریانا کنسول

انتخاب پیش‌فرض، مقداری را انتخاب می‌کند که در آریانا کنسول در قسمت Speech/Text Defaults تعیین شده است.