การตอบกลับจากสื่อ

การตอบสนองของสื่อช่วยให้การดำเนินการของคุณเล่นเนื้อหาเสียงที่มีระยะเวลาการเล่นนานกว่า SSML ที่จำกัดไว้ที่ 240 วินาทีได้ การตอบสนองของสื่อทำงานได้ทั้งในอุปกรณ์แบบเสียงเท่านั้นและอุปกรณ์ที่แสดงเนื้อหาที่เป็นภาพได้ ในจอแสดงผล การตอบสนองของสื่อจะมีคอมโพเนนต์ภาพที่มีตัวควบคุมสื่อ และ (ไม่บังคับ) ภาพนิ่ง

เมื่อกำหนดการตอบกลับสื่อ ให้ใช้ตัวเลือกที่มีความสามารถของทั้ง RICH_RESPONSE และ LONG_FORM_AUDIO เพื่อให้ Google Assistant แสดงผลการตอบสนองริชมีเดียเฉพาะในอุปกรณ์ที่รองรับ คุณสามารถใช้การตอบกลับด้วยริชมีเดีย 1 รายการต่อออบเจ็กต์ content ในพรอมต์เท่านั้น

เสียงสำหรับการเล่นต้องอยู่ในรูปแบบไฟล์ MP3 ที่ถูกต้อง ไฟล์ MP3 ต้องโฮสต์บนเว็บเซิร์ฟเวอร์และเข้าถึงได้แบบสาธารณะผ่าน HTTPS URL สตรีมมิงแบบสดรองรับเฉพาะรูปแบบ MP3 เท่านั้น

ตัวอย่างการตอบสนองของสื่อในจออัจฉริยะ
รูปที่ 1 ตัวอย่างการตอบสนองของสื่อใน Smart Display

ลักษณะการทำงาน

ตัวอย่างการตอบสนองของสื่อบนสมาร์ทโฟน
รูปที่ 2 ตัวอย่างการตอบสนองของสื่อบนสมาร์ทโฟน

องค์ประกอบหลักของการตอบกลับสื่อคือการ์ดแทร็กเดียว การ์ดช่วยให้ผู้ใช้ทำสิ่งต่อไปนี้ได้

  • เล่น 10 วินาทีล่าสุดอีกครั้ง
  • ข้ามไปข้างหน้า 30 วินาที
  • ดูความยาวรวมของเนื้อหาสื่อ
  • ดูสัญญาณบอกสถานะความคืบหน้าสำหรับการเล่นสื่อ
  • ดูเวลาการเล่นที่ผ่านไป

การตอบสนองของสื่อรองรับการควบคุมเสียงต่อไปนี้สำหรับการโต้ตอบด้วยเสียง ซึ่ง Google Assistant จะจัดการทั้งหมดนี้ ได้แก่

  • "Ok Google เล่น"
  • "Ok Google หยุดชั่วคราว"
  • "Ok Google หยุด"
  • "Ok Google เริ่มต้นใหม่"

ผู้ใช้ยังควบคุมระดับเสียงได้โดยพูดวลีอย่างเช่น "Ok Google เพิ่มระดับเสียง" หรือ "Ok Google ปรับระดับเสียงไปที่ 50 เปอร์เซ็นต์" Intent ในการกระทำ จะมีผลเหนือกว่าหากจัดการวลีการฝึกที่คล้ายกัน โดยให้ Assistant จัดการคำขอของผู้ใช้เหล่านี้ เว้นแต่การดำเนินการของคุณจะมีเหตุผลเฉพาะ

ลักษณะการทำงานในโทรศัพท์ Android

ในโทรศัพท์ Android คุณจะใช้ตัวควบคุมสื่อขณะที่โทรศัพท์ล็อกอยู่ได้เช่นกัน ตัวควบคุมสื่อจะปรากฏในพื้นที่การแจ้งเตือนด้วย และผู้ใช้สามารถดูการตอบสนองของสื่อเมื่อตรงกับเงื่อนไขต่อไปนี้

  • Google Assistant เป็นพื้นหน้าและหน้าจอโทรศัพท์เปิดอยู่
  • ผู้ใช้จะออกจาก Google Assistant ขณะที่เสียงเล่นอยู่และกลับไปที่ Google Assistant ภายใน 10 นาทีหลังเล่นเสร็จ เมื่อกลับไปที่ Google Assistant ผู้ใช้จะเห็นการ์ดสื่อและชิปคำแนะนำ

พร็อพเพอร์ตี้

การตอบกลับสื่อมีพร็อพเพอร์ตี้ต่อไปนี้

พร็อพเพอร์ตี้ Type ข้อกำหนด คำอธิบาย
media_type MediaType จำเป็น ประเภทสื่อของคําตอบที่ระบุ แสดงผล MEDIA_STATUS_ACK เมื่อรับทราบสถานะสื่อ
start_offset สตริง ไม่บังคับ กรอตำแหน่งเพื่อเริ่มแทร็กสื่อแรก ระบุค่าเป็นวินาที โดยที่เศษส่วนวินาทีมีทศนิยมไม่เกิน 9 ตำแหน่ง และลงท้ายด้วย "s" เช่น 3 วินาทีและ 1 นาโนวินาทีจะแสดงเป็น "3.000000001s"
optional_media_controls อาร์เรย์ของ OptionalMediaControls ไม่บังคับ พร็อพเพอร์ตี้การเลือกใช้เพื่อรับโค้ดเรียกกลับเมื่อผู้ใช้เปลี่ยนสถานะการเล่นสื่อ (เช่น โดยการหยุดชั่วคราวหรือหยุดการเล่นสื่อ)
media_objects อาร์เรย์ของ MediaObject จำเป็น แสดงออบเจ็กต์สื่อที่จะรวมไว้ในพรอมต์ เมื่อคุณรับทราบสถานะสื่อด้วย MEDIA_STATUS_ACK ห้ามระบุออบเจ็กต์สื่อ
first_media_object_index จำนวนเต็ม ไม่บังคับ ดัชนีฐาน 0 ของ MediaObject แรกใน media_objects ที่จะเล่น หากไม่ระบุ มีค่าเป็น 0 หรืออยู่นอกขอบเขต การเล่นจะเริ่มเล่นที่ MediaObject แรก
repeat_mode RepeatMode ไม่บังคับ โหมดเล่นซ้ำสำหรับรายการออบเจ็กต์สื่อ

รหัสตัวอย่าง

YAML

candidates:
  - first_simple:
      variants:
        - speech: This is a media response.
    content:
      media:
        start_offset: 2.12345s
        optional_media_controls:
          - PAUSED
          - STOPPED
        media_objects:
          - name: Media name
            description: Media description
            url: 'https://storage.googleapis.com/automotive-media/Jazz_In_Paris.mp3'
            image:
              large:
                url: 'https://storage.googleapis.com/automotive-media/album_art.jpg'
                alt: Jazz in Paris album art
        media_type: AUDIO

JSON

{
  "candidates": [
    {
      "first_simple": {
        "variants": [
          {
            "speech": "This is a media response."
          }
        ]
      },
      "content": {
        "media": {
          "start_offset": "2.12345s",
          "optional_media_controls": [
            "PAUSED",
            "STOPPED"
          ],
          "media_objects": [
            {
              "name": "Media name",
              "description": "Media description",
              "url": "https://storage.googleapis.com/automotive-media/Jazz_In_Paris.mp3",
              "image": {
                "large": {
                  "url": "https://storage.googleapis.com/automotive-media/album_art.jpg",
                  "alt": "Jazz in Paris album art"
                }
              }
            }
          ],
          "media_type": "AUDIO"
        }
      }
    }
  ]
}

Node.js

// Media response
app.handle('media', (conv) => {
  conv.add('This is a media response');
  conv.add(new Media({
    mediaObjects: [
      {
        name: 'Media name',
        description: 'Media description',
        url: 'https://storage.googleapis.com/automotive-media/Jazz_In_Paris.mp3',
        image: {
          large: JAZZ_IN_PARIS_IMAGE,
        }
      }
    ],
    mediaType: 'AUDIO',
    optionalMediaControls: ['PAUSED', 'STOPPED'],
    startOffset: '2.12345s'
  }));
});

JSON

{
  "session": {
    "id": "session_id",
    "params": {},
    "languageCode": ""
  },
  "prompt": {
    "override": false,
    "content": {
      "media": {
        "mediaObjects": [
        {
          "name": "Media name",
          "description": "Media description",
          "url": "https://storage.googleapis.com/automotive-media/Jazz_In_Paris.mp3",
          "image": {
            "large": {
              "alt": "Jazz in Paris album art",
              "height": 0,
              "url": "https://storage.googleapis.com/automotive-media/album_art.jpg",
              "width": 0
            }
          }
        }
        ],
        "mediaType": "AUDIO",
        "optionalMediaControls": [
          "PAUSED",
          "STOPPED"
        ]
      }
    },
    "firstSimple": {
      "speech": "This is a media response",
      "text": "This is a media response"
    }
  }
}

กำลังรับสถานะสื่อ

ระหว่างหรือหลังการเล่นสื่อให้ผู้ใช้ Google Assistant สามารถสร้างเหตุการณ์สถานะสื่อเพื่อแจ้งความคืบหน้าในการเล่นของคุณได้ จัดการเหตุการณ์สถานะเหล่านี้ในโค้ดเว็บฮุคเพื่อกำหนดเส้นทางผู้ใช้อย่างเหมาะสมเมื่อผู้ใช้หยุดชั่วคราว หยุด หรือเล่นสื่อให้เสร็จ

Google Assistant จะแสดงผลเหตุการณ์สถานะจากรายการต่อไปนี้โดยอิงตามความคืบหน้าในการเล่นสื่อและคำค้นหาของผู้ใช้

  • FINISHED: ผู้ใช้เล่นสื่อเสร็จแล้ว (หรือข้ามไปยังสื่อชิ้นถัดไป) และการเปลี่ยนไม่ใช่การออกจากการสนทนา สถานะนี้จะแมปกับ Intent ของระบบ MEDIA_STATUS_FINISHED ด้วย
  • PAUSED: ผู้ใช้หยุดเล่นสื่อชั่วคราว เลือกรับเหตุการณ์สถานะนี้ ด้วยพร็อพเพอร์ตี้ optional_media_controls สถานะนี้จะแมปกับ Intent ของระบบ MEDIA_STATUS_PAUSED ด้วย
  • STOPPED: ผู้ใช้หยุดหรือออกจากการเล่นสื่อ เลือกรับเหตุการณ์สถานะนี้ด้วยพร็อพเพอร์ตี้ optional_media_controls สถานะนี้จะแมปกับ Intent ของระบบ MEDIA_STATUS_STOPPED ด้วย
  • FAILED: เล่นสื่อไม่สำเร็จ สถานะนี้จะแมปกับ Intent ของระบบ MEDIA_STATUS_FAILED ด้วย

ระหว่างการเล่นสื่อ ผู้ใช้อาจระบุคำค้นหาที่ทำให้เข้าใจว่าเป็นทั้งเหตุการณ์หยุดชั่วคราวและหยุดสื่อ (เช่น "หยุด" "ยกเลิก" หรือ "ออก") ในกรณีดังกล่าว Assistant จะระบุ Intent ของระบบ actions.intent.CANCEL ให้กับการดำเนินการของคุณ สร้างเหตุการณ์สถานะสื่อที่มีค่าสถานะ "หยุดแล้ว" และออกจากการดำเนินการโดยสมบูรณ์

เมื่อ Assistant สร้างเหตุการณ์สถานะสื่อด้วยค่าสถานะ PAUSED หรือ STOPPED ให้ตอบกลับด้วยสื่อตอบกลับที่มีเพียงการรับทราบเท่านั้น (ประเภท MEDIA_STATUS_ACK)

ความคืบหน้าของสื่อ

ความคืบหน้าในการเล่นสื่อปัจจุบันจะอยู่ในช่อง context.media.progress สำหรับคำขอเว็บฮุค คุณใช้ความคืบหน้าของสื่อเป็นออฟเซ็ตเวลาเริ่มต้นเพื่อกลับมาเล่นอีกครั้ง ณ จุดที่การเล่นสื่อสิ้นสุดลงได้ หากต้องการใช้ออฟเซ็ตเวลาเริ่มต้นกับการตอบสนองของสื่อ ให้ใช้พร็อพเพอร์ตี้ start_offset

รหัสตัวอย่าง

Node.js

// Media status
app.handle('media_status', (conv) => {
  const mediaStatus = conv.intent.params.MEDIA_STATUS.resolved;
  switch(mediaStatus) {
    case 'FINISHED':
      conv.add('Media has finished playing.');
      break;
    case 'FAILED':
      conv.add('Media has failed.');
      break;
    case 'PAUSED' || 'STOPPED':
      if (conv.request.context) {
        // Persist the media progress value
        const progress = conv.request.context.media.progress;
      }
      // Acknowledge pause/stop
      conv.add(new Media({
        mediaType: 'MEDIA_STATUS_ACK'
        }));
      break;
    default:
      conv.add('Unknown media status received.');
  }
});

แสดงเพลย์ลิสต์

คุณเพิ่มไฟล์เสียงได้มากกว่า 1 ไฟล์ในการตอบกลับเพื่อสร้างเพลย์ลิสต์ เมื่อแทร็กแรกเล่นจบ แทร็กถัดไปจะเล่นโดยอัตโนมัติ และจะเล่นต่อไปจนกระทั่งแต่ละแทร็กเล่น ผู้ใช้ยังกดปุ่มถัดไปบนหน้าจอ หรือพูดว่า "ถัดไป" หรือคำที่คล้ายกันเพื่อข้ามไปยังแทร็กถัดไปได้ด้วย

ปุ่มถัดไปปิดใช้อยู่บนแทร็กสุดท้ายของเพลย์ลิสต์ อย่างไรก็ตาม หากคุณเปิดใช้โหมดวนซ้ำ เพลย์ลิสต์จะเริ่มเล่นอีกครั้งจากแทร็กแรก ดูข้อมูลเพิ่มเติมเกี่ยวกับโหมดวนซ้ำได้ที่ใช้โหมดวนซ้ำ

หากต้องการสร้างเพลย์ลิสต์ ให้ใส่ MediaObject มากกว่า 1 รายการในอาร์เรย์ media_objects ข้อมูลโค้ดต่อไปนี้แสดงข้อความแจ้งที่แสดงเพลย์ลิสต์ที่มี 3 แทร็ก

{
  "candidates": [
    {
      "content": {
        "media": {
          "media_objects": [
            {
              "name": "1. Jazz in Paris",
              "description": "Song 1 of 3",
              "url": "https://storage.googleapis.com/automotive-media/Jazz_In_Paris.mp3",
              "image": {
                "large": {
                  "url": "https://storage.googleapis.com/automotive-media/album_art.jpg",
                  "alt": "Album cover of an ocean view",
                  "height": 1600,
                  "width": 1056
                }
              }
            },
            {
              "name": "2. Jazz in Paris",
              "description": "Song 2 of 3",
              "url": "https://storage.googleapis.com/automotive-media/Jazz_In_Paris.mp3",
              "image": {
                "large": {
                  "url": "https://storage.googleapis.com/automotive-media/album_art.jpg",
                  "alt": "Album cover of an ocean view",
                  "height": 1600,
                  "width": 1056
                }
              }
            },
            {
              "name": "3. Jazz in Paris",
              "description": "Song 3 of 3",
              "url": "https://storage.googleapis.com/automotive-media/Jazz_In_Paris.mp3",
              "image": {
                "large": {
                  "url": "https://storage.googleapis.com/automotive-media/album_art.jpg",
                  "alt": "Album cover of an ocean view",
                  "height": 1600,
                  "width": 1056
                }
              }
            }
          ],
        }
      }
    }
  ]
}

ใช้โหมดการวนซ้ำ

โหมดวนซ้ำช่วยให้คุณมอบเสียงตอบกลับที่เกิดซ้ำโดยอัตโนมัติได้ คุณสามารถใช้โหมดนี้เพื่อเล่น แทร็กเดียวซ้ำ หรือเล่นวนซ้ำในเพลย์ลิสต์ หากผู้ใช้พูดว่า "ถัดไป" หรือคำที่คล้ายๆ กันสำหรับแทร็กที่วนซ้ำ 1 แทร็ก เพลงจะเริ่มเล่นอีกครั้ง สำหรับเพลย์ลิสต์แบบวนซ้ำ เมื่อผู้ใช้พูดว่า "ถัดไป" จะเป็นการเริ่มเล่นแทร็กถัดไปในเพลย์ลิสต์

หากต้องการใช้โหมดการวนซ้ำ ให้เพิ่มช่อง repeat_mode ลงในพรอมต์แล้วตั้งค่าเป็น ALL การเพิ่มนี้จะช่วยให้การตอบสนองของสื่อเล่นวนซ้ำไปยังจุดเริ่มต้นของออบเจ็กต์สื่อแรกได้เมื่อถึงจุดสิ้นสุดของออบเจ็กต์สื่อสุดท้าย

ข้อมูลโค้ดต่อไปนี้จะแสดงข้อความแจ้งที่แสดงผลแทร็กการวนซ้ำ

{
  "candidates": [
    {
      "content": {
        "media": {
          "media_objects": [
            {
              "name": "Jazz in Paris",
              "description": "Single song (repeated)",
              "url": "https://storage.googleapis.com/automotive-media/Jazz_In_Paris.mp3",
              "image": {
                "large": {
                  "url": "https://storage.googleapis.com/automotive-media/album_art.jpg",
                  "alt": "Album cover of an ocean view",
                  "height": 1600,
                  "width": 1056
                }
              }
            }
          ],
          "repeat_mode": "ALL"
        }
      }
    }
  ]
}