SSML (Dialogflow)

عند عرض ردّ على "مساعد Google"، يمكنك استخدام مجموعة فرعية من لغة ترميز تركيب الكلام (SSML) في ردودك من باستخدام SSML، يمكنك جعل ردود محادثتك تبدو طبيعية أكثر خطاب. يوضح ما يلي مثالاً على ترميز SSML وكيفية قراءته مرة أخرى بواسطة مساعد Google

function saySSML(conv) {
  const ssml = '<speak>' +
    'Here are <say-as interpret-as="characters">SSML</say-as> samples. ' +
    'I can pause <break time="3" />. ' +
    'I can play a sound <audio src="https://www.example.com/MY_WAVE_FILE.wav">your wave file</audio>. ' +
    'I can speak in cardinals. Your position is <say-as interpret-as="cardinal">10</say-as> in line. ' +
    'Or I can speak in ordinals. You are <say-as interpret-as="ordinal">10</say-as> in line. ' +
    'Or I can even speak in digits. Your position in line is <say-as interpret-as="digits">10</say-as>. ' +
    'I can also substitute phrases, like the <sub alias="World Wide Web Consortium">W3C</sub>. ' +
    'Finally, I can speak a paragraph with two sentences. ' +
    '<p><s>This is sentence one.</s><s>This is sentence two.</s></p>' +
    '</speak>';
  conv.ask(ssml);
}

{
  "expectUserResponse": true,
  "expectedInputs": [
    {
      "possibleIntents": [
        {
          "intent": "actions.intent.TEXT"
        }
      ],
      "inputPrompt": {
        "richInitialPrompt": {
          "items": [
            {
              "simpleResponse": {
                "textToSpeech": "<speak>Here are <say-as interpret-as=\"characters\">SSML</say-as> samples. I can pause <break time=\"3\" />. I can play a sound <audio src=\"https://www.example.com/MY_WAVE_FILE.wav\">your wave file</audio>. I can speak in cardinals. Your position is <say-as interpret-as=\"cardinal\">10</say-as> in line. Or I can speak in ordinals. You are <say-as interpret-as=\"ordinal\">10</say-as> in line. Or I can even speak in digits. Your position in line is <say-as interpret-as=\"digits\">10</say-as>. I can also substitute phrases, like the <sub alias=\"World Wide Web Consortium\">W3C</sub>. Finally, I can speak a paragraph with two sentences. <p><s>This is sentence one.</s><s>This is sentence two.</s></p></speak>"
              }
            }
          ]
        }
      }
    }
  ]
}

الصوت

تتوفّر لغة SSML في محاكي الإجراءات، ولكن لا تتوفر في Dialogflow المحاكي.

عناوين URL في SSML

عند تحديد استجابة SSML التي تتضمن عنوان URL فقط، تظهر علامات العطف في عنوان URL هذا يمكن أن تسبب مشكلات بسبب تنسيق XML. لضمان عرض عنوان URL بشكل صحيح المشار إليها، استبدِل مثيلات & بـ &.

حتى إذا كانت استجابة SSML تتضمّن عنوان URL فقط، تتطلب "المهام مع مساعد Google" النص المعروض للرد. لأنّ النص داخل العلامة <audio> لن يتم عرضه يتحدث بها "مساعد Google"، يمكنك إدراج نص الحشو أو وصف موجز في علامة <audio> لاستيفاء هذا الشرط. لن يتم عرض نص داخل العلامة <audio>. التي تقولها خدمة "مساعد Google" بعد تشغيل الصوت، وتستوفي ميزة "المهام مع مساعد Google" متطلبات إصدار النص المعروض من SSML.

فيما يلي مثال على استجابة SSML بإشكالية:

<speak>
  <audio src="https://firebasestorage.googleapis.com/v0/b/project-name.appspot.com/o/audio-file-name.ogg?alt=media&token=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX">
  </audio>
</speak>

لا يتخطّى المثال أعلاه & للحصول على تنسيق XML مناسب.

يبدو إصدار ثابت من استجابة SSML نفسها كما يلي:

<speak>
  <audio src="https://firebasestorage.googleapis.com/v0/b/project-name.appspot.com/o/audio-file-name.ogg?alt=media&amp;token=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX">
  text
  </audio>
</speak>

دعم عناصر SSML

تصف الأقسام التالية عناصر SSML والخيارات التي يمكن استخدامها في "الإجراءات" الخاصة بك.

<speak>

العنصر الجذر لاستجابة SSML.

للمزيد من المعلومات حول العنصر speak، يُرجى مراجعة مواصفات W3.

مثال

<speak>
  my SSML content
</speak>

<break>

عنصر فارغ يتحكم في الإيقاف المؤقت أو الحدود العرضية الأخرى بين الكلمات. ويُعدّ استخدام <break> بين أي زوج من الرموز المميّزة اختياريًا. في حال عدم توفّر هذا العنصر بين الكلمات، يتم تحديد الفاصل تلقائيًا استنادًا إلى السياق اللغوي.

للمزيد من المعلومات حول العنصر break، يُرجى مراجعة مواصفات W3.

السمات

مثال

يوضّح المثال التالي كيفية استخدام العنصر <break> للتوقف مؤقتًا بين الخطوات:

<speak>
  Step 1, take a deep breath. <break time="200ms"/>
  Step 2, exhale.
  Step 3, take a deep breath again. <break strength="weak"/>
  Step 4, exhale.
</speak>

<say‑as>

يتيح لك هذا العنصر الإشارة إلى معلومات حول نوع تركيبة النص المضمنة في العنصر. ويساعد أيضًا في تحديد مستوى التفاصيل لعرض النص المتضمّن.

يضم العنصر <say‑as> السمة المطلوبة interpret-as التي تحدّد طريقة قول القيمة. يمكن استخدام السمتَين الاختياريتَين format وdetail استنادًا إلى قيمة interpret-as المحدّدة.

أمثلة

تتيح السمة interpret-as استخدام القيم التالية:

• currency

  ويرمز المثال التالي إلى "اثنين وأربعين دولارًا وسنتًا واحدًا". إذا تم حذف سمة اللغة، سيتم استخدام اللغة الحالية.

  <speak>
    <say-as interpret-as='currency' language='en-US'>$42.01</say-as>
  </speak>
      

• telephone

  يمكنك الاطّلاع على وصف interpret-as='telephone' في ملاحظة WG في W3C SSML 1.0 say-as.

  يتم قول المثال التالي على النحو التالي "واحد ثمانية صفر اثنان صفر اثنين واحد اثنان واحد اثنان". إذا كان "google:style" حيث يتم إسقاطها، حيث تصبح صفرًا مثل الحرف O.

  "google:style='zero-as-zero'" لا تعمل إلا في اللغات الإنجليزية فقط.

        <speak>
          <say-as interpret-as='telephone' google:style='zero-as-zero'>1800-202-1212</say-as>
        </speak>
      

• verbatim أو spell-out

  يُكتب في المثال التالي حرفًا بحرف:

  <speak>
    <say-as interpret-as="verbatim">abcdefg</say-as>
  </speak>
      

• date

  السمة format هي سلسلة من رموز أحرف حقل التاريخ. رموز الأحرف المسموح بها للحقول في format هي {y وm وd} للسنة والشهر واليوم (من الشهر) على التوالي. وإذا ظهر رمز الحقل مرة واحدة للسنة أو الشهر أو اليوم، يكون عدد الأرقام المتوقع هو 4 و2 و2 على التوالي. إذا تكرر رمز الحقل، فإن عدد الأرقام المتوقعة هو عدد مرات تكرار الرمز. يمكن فصل الحقول في نص التاريخ بعلامات ترقيم و/أو مسافات.

  تتحكّم السمة detail في صيغة التاريخ المحكية. بالنسبة إلى detail='1'، تكون حقول "اليوم" وحقل "الشهر أو السنة" مطلوبَين فقط، ولكن قد يتم تقديمهما معًا. ويكون هذا هو الخيار التلقائي عندما يكون عدد الحقول الثلاثة أقل من جميع الحقول. الصيغة المحكية هي "{ordinal day} من {month}, {year}".

  يُقال المثال التالي على النحو التالي "العاشر من سبتمبر، 91 ستين":

  <speak>
    <say-as interpret-as="date" format="yyyymmdd" detail="1">
      1960-09-10
    </say-as>
  </speak>
      

  يتم قول المثال التالي باسم "العاشر من سبتمبر":

  <speak>
    <say-as interpret-as="date" format="dm">10-9</say-as>
  </speak>
      

  بالنسبة إلى detail='2'، تكون حقول اليوم والشهر والسنة مطلوبة، ويكون هذا هو الخيار التلقائي عند توفير الحقول الثلاثة جميعها. الصيغة المحكية هي "{month} {ordinal day}, {year}".

  يتم قول المثال التالي على النحو التالي "09 أيلول (سبتمبر)، 19 أيلول (سبتمبر)":

  <speak>
    <say-as interpret-as="date" format="dmy" detail="2">
      10-9-1960
    </say-as>
  </speak>
      

• characters

  يتم قول المثال التالي بالرمز "C A N":

  <speak>
    <say-as interpret-as="characters">can</say-as>
  </speak>
      

• cardinal

  يُنطق المثال التالي بالصيغة "اثنا عشر ألفًا وثلاثمئة وخمسة وأربعين" (للإنجليزية الأمريكية) أو "اثنا عشر ألفًا وثلاثمئة وخمسة وأربعون (للإنجليزية في المملكة المتحدة)":

  <speak>
    <say-as interpret-as="cardinal">12345</say-as>
  </speak>
      

• ordinal

  يتم قول المثال التالي باسم "الأول":

  <speak>
    <say-as interpret-as="ordinal">1</say-as>
  </speak>
      

• fraction

  يتم قول المثال التالي "خمسة ونصف":

  <speak>
    <say-as interpret-as="fraction">5+1/2</say-as>
  </speak>
      

• expletive أو bleep

  يظهر المثال التالي كإشارة صوتية كما لو كانت خاضعة للرقابة:

  <speak>
    <say-as interpret-as="expletive">censor this</say-as>
  </speak>
      

• unit

  لتحويل الوحدات إلى صيغة مفرد أو جمع بناءً على الرقم. يتم قول المثال التالي كـ "10 أقدام":

  <speak>
    <say-as interpret-as="unit">10 foot</say-as>
  </speak>
      

• time

  يتم قول المثال التالي بالعنوان "اثنين وثلاثين مساءً".

  <speak>
    <say-as interpret-as="time" format="hms12">2:30pm</say-as>
  </speak>
      

  السمة format هي سلسلة من رموز أحرف حقل الوقت. رموز الأحرف المسموح بها للحقول في format هي {h وm وs وZ و12 و24} للساعة والدقيقة (من الساعة) والثانية (من الدقيقة) والمنطقة الزمنية ووقت 12 ساعة ووقت 24 ساعة على التوالي. وإذا ظهر رمز الحقل مرة واحدة للساعة أو الدقيقة أو الثانية، يكون عدد الأرقام المتوقع هو 1 و2 و2 على التوالي. إذا تكرر رمز الحقل، فإن عدد الأرقام المتوقعة هو عدد مرات تكرار الرمز. يمكن فصل الحقول في نص الوقت بعلامات ترقيم و/أو مسافات. إذا لم يتم تحديد الساعة أو الدقيقة أو الثانية في التنسيق، أو لم تكن هناك أرقام مطابقة، يتم التعامل مع الحقل كقيمة صفرية. قيمة format التلقائية هي "hms12".

  تحدد السمة detail ما إذا كان التنسيق الصوتي للوقت هو 12 ساعة أو 24 ساعة. ويكون تنسيق الوقت الذي يتم قوله على مدار 24 ساعة إذا تم حذف detail='1' أو إذا تم حذف detail وكان تنسيق الوقت 24 ساعة. ويكون تنسيق الوقت الذي يتم قوله 12 ساعة إذا تم حذف detail='2' أو إذا تم حذف detail وكان تنسيق الوقت 12 ساعة.

للمزيد من المعلومات حول العنصر say-as، يُرجى مراجعة مواصفات W3.

<audio>

يتيح إدخال ملفات صوتية مسجلة وإدراج تنسيقات صوتية أخرى إلى جانب إخراج الكلام المركَّب.

السمات

في ما يلي إعدادات الصوت المتاحة حاليًا:

• التنسيق: MP3 (MPEG v2)
  • 24 ألف عينة في الثانية
  • 24 ألف إلى 96 ألف بت في الثانية، بمعدل ثابت
• التنسيق: Opus in Ogg
  • 24 ألف عينة في الثانية (النطاق الفائق العرض)
  • 24K - 96 كيلو بت في الثانية، بمعدل ثابت
• التنسيق (متوقّف نهائيًا): WAV (RIFF)
  • PCM بتوقيع 16 بت، نهاية صغيرة
  • 24 ألف عينة في الثانية
• بالنسبة إلى جميع التنسيقات:
  • ويفضل استخدام قناة واحدة، لكن يُسمح باستخدام الاستيريو.
  • 240 ثانية كحد أقصى للمدة. إذا أردت تشغيل صوت لمدة أطول، ننصحك باستخدام رد على الوسائط.
  • حد حجم الملف 5 ميغابايت.
  • يجب أن يستخدم عنوان URL المصدر بروتوكول HTTPS.
  • UserAgent (وكيل المستخدم) عند جلب الصوت هو "Google-Speech-Actions".

يكون محتوى العنصر <audio> اختياريًا ويتم استخدامه إذا تعذّر تشغيل الملف الصوتي أو إذا كان جهاز الإخراج لا يتيح تشغيل الصوت. قد يتضمّن المحتوى عنصر <desc>، وفي هذه الحالة يتم استخدام المحتوى النصي لهذا العنصر للعرض. لمزيد من المعلومات، يمكنك الاطّلاع على قسم "الصوت المسجّل" في قائمة التحقق من الردود.

يجب أن يكون عنوان URL للسمة src أيضًا عنوان URL يستخدم بروتوكول https (يمكن لخدمة Google Cloud Storage استضافة ملفاتك الصوتية على عنوان URL يستخدم بروتوكول https).

للمزيد من المعلومات حول الردود على الوسائط، يمكنك الاطّلاع على قسم الردّ على الوسائط في دليل "الردود".

للمزيد من المعلومات حول العنصر audio، يُرجى مراجعة مواصفات W3.

مثال

<speak>
  <audio src="cat_purr_close.ogg">
    <desc>a cat purring</desc>
    PURR (sound didn't load)
  </audio>
</speak>

<p>,<s>

عناصر الجملة والفقرة

لمزيد من المعلومات حول العنصرَين p وs، يمكنك الاطّلاع على مواصفات W3.

مثال

<p><s>This is sentence one.</s><s>This is sentence two.</s></p>

أفضل الممارسات

• استخدام <s>...</s> لإحاطة الجمل الكاملة بجمل كاملة، خاصةً إذا كانت تحتوي على عناصر SSML التي تغيّر العملية (أي <audio> و<break> و<emphasis> و<par> و<prosody> و<say-as> و<seq> و<sub>).
• إذا كان الهدف من الفاصل الإعلاني في الكلام أن يكون طويلًا بما يكفي لسماعه، استخدم <s>...</s> العلامات ووضع تلك الفاصلة بين الجمل.

<sub>

الإشارة إلى أنّ النص في قيمة السمة "الاسم المستعار" يحل محل النص المضمَّن في اللفظ.

يمكنك أيضًا استخدام العنصر sub لتوفير طريقة لفظ مبسّطة لكلمة يصعب قراءتها. يوضح المثال الأخير أدناه حالة الاستخدام هذه باللغة اليابانية.

للمزيد من المعلومات حول العنصر sub، يُرجى مراجعة مواصفات W3.

أمثلة

<sub alias="World Wide Web Consortium">W3C</sub>

<sub alias="にっぽんばし">日本橋</sub>

<mark>

عنصر فارغ يضع علامة في تسلسل النص أو العلامة. يمكن استخدامه للإشارة إلى موقع محدّد في التسلسل أو لإدراج علامة في مصدر بيانات للإشعارات غير المتزامنة.

للمزيد من المعلومات حول العنصر mark، يُرجى مراجعة مواصفات W3.

مثال

<speak>
Go from <mark name="here"/> here, to <mark name="there"/> there!
</speak>

<prosody>

يُستخدم لتخصيص درجة الصوت ومعدّل التحدث ومستوى الصوت في النص الذي يتضمّنه العنصر. يمكن حاليًا استخدام السمات rate وpitch وvolume.

يمكن ضبط السمتَين rate وvolume وفقًا لمواصفات W3. تتوفّر ثلاثة خيارات لضبط قيمة السمة pitch:

للمزيد من المعلومات حول العنصر prosody، يُرجى مراجعة مواصفات W3.

مثال

يستخدم المثال التالي العنصر <prosody> للتحدّث ببطء على نقطتَين أقل من المعتاد:

<prosody rate="slow" pitch="-2st">Can you hear me now?</prosody>

<emphasis>

يُستخدم لإضافة أو إزالة التوكيد من النص الذي يحتوي عليه العنصر. يُعدّ العنصر <emphasis> الكلام بطريقة مشابهة لـ <prosody>، ولكن بدون الحاجة إلى ضبط سمات الكلام بشكل فردي.

يدعم هذا العنصر "مستوى" اختياري بالقيم الصالحة التالية:

• strong
• moderate
• none
• reduced

للمزيد من المعلومات حول العنصر emphasis، يُرجى مراجعة مواصفات W3.

مثال

يستخدم المثال التالي العنصر <emphasis> لإنشاء إشعار:

<emphasis level="moderate">This is an important announcement</emphasis>

<par>

حاوية وسائط متوازية تسمح لك بتشغيل عناصر وسائط متعددة في وقت واحد. المحتوى الوحيد المسموح به هو مجموعة من عنصر واحد أو أكثر من العناصر <par> و<seq> و<media>. إنّ ترتيب عناصر <media> غير مهم.

يكون وقت البدء الضمني للعنصر هو نفسه وقت بدء حاوية <par> ما لم يحدّد العنصر الفرعي وقت بدء مختلفًا. إذا كان هناك عنصر فرعي يحتوي على قيمة إزاحة تم ضبطها لسمة البداية أو النهاية، سيتم ربط إزاحة العنصر بوقت بدء الحاوية <par>. بالنسبة إلى العنصر الجذر <par>، يتم تجاهل سمة البدء ويكون وقت البدء هو عندما تبدأ عملية تجميع الكلام في SSML في إنشاء إخراج للعنصر الجذر <par> (أي ضبط الوقت الفعلي على "صفر").

مثال

<speak>
  <par>
    <media xml:id="question" begin="0.5s">
      <speak>Who invented the Internet?</speak>
    </media>
    <media xml:id="answer" begin="question.end+2.0s">
      <speak>The Internet was invented by cats.</speak>
    </media>
    <media begin="answer.end-0.2s" soundLevel="-6dB">
      <audio
        src="https://actions.google.com/.../cartoon_boing.ogg"/>
    </media>
    <media repeatCount="3" soundLevel="+2.28dB"
      fadeInDur="2s" fadeOutDur="0.2s">
      <audio
        src="https://actions.google.com/.../cat_purr_close.ogg"/>
    </media>
  </par>
</speak>

<seq>

حاوية وسائط تسلسلية تتيح لك تشغيل عناصر الوسائط واحدًا تلو الآخر المحتوى الوحيد المسموح به هو مجموعة من عنصر واحد أو أكثر من العناصر <seq> و<par> و<media>. يكون ترتيب عناصر الوسائط هو الترتيب الذي يتم عرضها به.

يمكن ضبط سمتَي البداية والانتهاء للعناصر الفرعية على ضبط القيم وفقًا للقيم (راجِع المواصفات الزمنية أدناه). هذه العناصر الفرعية' ستكون قيم الإزاحة نسبية مع نهاية العنصر السابق في التسلسل، أو بالنسبة إلى بداية حاوية <seq> في حالة العنصر الأول في التسلسل.

مثال

<speak>
  <seq>
    <media begin="0.5s">
      <speak>Who invented the Internet?</speak>
    </media>
    <media begin="2.0s">
      <speak>The Internet was invented by cats.</speak>
    </media>
    <media soundLevel="-6dB">
      <audio
        src="https://actions.google.com/.../cartoon_boing.ogg"/>
    </media>
    <media repeatCount="3" soundLevel="+2.28dB"
      fadeInDur="2s" fadeOutDur="0.2s">
      <audio
        src="https://actions.google.com/.../cat_purr_close.ogg"/>
    </media>
  </seq>
</speak>

<media>

يمثل طبقة الوسائط داخل العنصر <par> أو <seq>. المحتوى المسموح به لعنصر <media> هو عنصر SSML <speak> أو <audio>. يوضّح الجدول التالي السمات الصالحة لعنصر <media>.

السمات

مواصفات الوقت

تُستخدم مواصفات الوقت لقيمة سمتَي "البداية" و"الانتهاء" لعناصر <media> وحاويات الوسائط (عناصر <par> و<seq>)، وتكون إما قيمة إزاحة (مثل +2.5s) أو قيمة Syncbase (مثل foo_id.end-250ms).

• قيمة الإزاحة - قيمة معادلة الوقت هي قيمة SMIL Timecount-value تسمح بالقيم التي تطابق التعبير العادي: "\s\*(+|-)?\s\*(\d+)(\.\d+)?(h|min|s|ms)?\s\*"

  سلسلة الرقم الأول هي الجزء الكامل من الرقم العشري وسلسلة الرقم الثاني هي الجزء العشري الكسري. العلامة التلقائية (أي "(+|-)؟" هي "+". وتتجاوب قيم الوحدة مع الساعات والدقائق والثواني والملي ثانية على التوالي. الإعداد التلقائي للوحدات هو "s". (ثوانٍ).

• قيمة Syncbase - قيمة Syncbase هي قيمة SMIL Syncbase تسمح بالقيم التي تتطابق مع التعبير العادي: "([-_#]|\p{L}|\p{D})+\.(begin|end)\s\*(+|-)\s\*(\d+)(\.\d+)?(h|min|s|ms)?\s\*"

  يتم تفسير الأرقام والوحدات بنفس طريقة تفسير قيمة الإزاحة.

محاكي تحويل النص إلى كلام

تتضمن وحدة تحكُّم الإجراءات مُحاكي تقنية "تحويل النص إلى كلام" (TTS) الذي يمكنك استخدامه لاختبار SSML مع أي من العناصر المذكورة أعلاه. يمكنك العثور على محاكي تحويل النص إلى كلام (TTS) في وحدة التحكّم ضمن المحاكي > الصوت: اكتب النص وSSML في المحاكي وانقر على التعديل والاستماع لسماع ناتج تحويل النص إلى كلام.

يمكنك أيضًا النقر على زر التنزيل لحفظ ملف .mp3 من تقنية "تحويل النص إلى كلام" الإخراج.