تنسيق SSML

عند عرض ردّ على "مساعد 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.add(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>"
              }
            }
          ]
        }
      }
    }
  ]
}

الصوت

عناوين URL في SSML

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

حتى إذا كانت استجابة SSML تتضمّن عنوان URL فقط، تتطلّب أداة "المهام مع مساعد Google" عرض النص للردّ. بما أنّ النص داخل العلامة <audio> لن يتمكّن من قوله في "مساعد Google"، يمكنك إدراج نص الحشو أو وصف موجز في العلامة <audio> لاستيفاء هذا الشرط. لن يقول "مساعد Google" النص المضمّن في علامة <audio> بعد تشغيل الصوت، شرط أن يكون ذلك متوافقًا مع متطلبات 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' في ملاحظة WGC SML SSML 1.0 لقيم المقالات التالية.

  على سبيل المثال، يتم قول المثال التالي: "one Zero صفر صفرًا اثنان مفردان اثنان واحدًا اثنان". إذا تم حذف السمة "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'، يجب استخدام حقلَي اليوم فقط وحقل واحد في الشهر أو السنة، على الرغم من أنّه يمكن تقديم الحقلين. هذا هو الإعداد التلقائي عندما يتم تقديم أقل من الحقول الثلاثة جميعها. النموذج المنطوق هو "The {ordical day} من {month}، {year}.

  يتم قول المثال التالي على أنه "العاشر من أيلول (سبتمبر)":

  <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} {ordical day}، {year}.

  يتم قول المثال التالي باسم "10 أيلول (سبتمبر) وتسعين ستين":

  <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 هي "mss12".

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

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

<audio>

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

السمات

في ما يلي إعدادات الصوت المسموح بها حاليًا:

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

ويكون محتوى العنصر <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>، ولكن بدون الحاجة إلى ضبط سمات الكلام الفردية.

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

• strong
• moderate
• none
• reduced

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

مثال

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

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

<par>

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

ما لم يحدد عنصر فرعي وقت بدء مختلفًا، يكون وقت البدء الضمني للعنصر هو نفسه وقت حاوية <par>. إذا تم ضبط قيمة إزاحة للعنصر الفرعي للسمة البدء أو الانتهاء، ستكون إزاحة العنصر نسبيًا إلى وقت بدء حاوية <par>. بالنسبة إلى العنصر <par> الجذر، يتم تجاهل السمة start ويكون وقت البدء هو عند بدء عملية تركيب كلام 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>.

السمات

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

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

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

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

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

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

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

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

يمكنك أيضًا النقر على زر التنزيل لحفظ ملف .mp3 من مخرجات TTS.