Medya yanıtları

Medya yanıtları, İşlemlerinizin 240 saniyelik SSML sınırından uzun oynatma süresi olan ses içeriklerini oynatmasına olanak tanır. Medya yanıtları, hem yalnızca ses özellikli cihazlarda hem de görsel içerik gösterebilen cihazlarda çalışır. Ekranda, medya yanıtlarına medya kontrolleri içeren bir görsel bileşen ve (isteğe bağlı olarak) hareketsiz bir resim eşlik eder.

Medya yanıtı tanımlarken hem RICH_RESPONSE hem de LONG_FORM_AUDIO yüzey özelliklerine sahip bir aday kullanın. Böylece Google Asistan yalnızca desteklenen cihazlarda zengin yanıtı döndürür. Bir istemde content nesnesi başına yalnızca bir zengin yanıt kullanabilirsiniz.

Çalınacak ses, doğru biçimlendirilmiş bir MP3 dosyasında olmalıdır. MP3 dosyaları bir web sunucusunda barındırılmalı ve HTTPS URL'si üzerinden herkese açık olmalıdır. Canlı yayın yalnızca MP3 biçimi için desteklenir.

Akıllı ekranda medya yanıtı örneği
Şekil 1. Akıllı ekranda medya yanıtı örneği

Davranış

Akıllı telefondaki bir medya yanıtı örneği
Şekil 2. Akıllı telefonda medya yanıtı örneği

Medya yanıtının birincil bileşeni tek parça kartıdır. Kart, kullanıcının aşağıdakileri yapmasına olanak tanır:

  • Son 10 saniyeyi tekrar oynat
  • İleriye doğru 30 saniye atla
  • Medya içeriğinin toplam uzunluğunu görüntüleme
  • Medya oynatma için ilerleme durumu göstergesini görüntüleme
  • Geçen oynatma süresini görüntüleme

Medya yanıtları, sesli etkileşimler için aşağıdaki ses kontrollerini destekler. Bu denetimlerin tümü Google Asistan tarafından yönetilir:

  • "Ok Google, oynat."
  • "Ok Google, duraklat."
  • "Ok Google, durdur."
  • "Ok Google, baştan başla."

Kullanıcılar "Ok Google, sesi aç." veya "Ok Google, sesi yüzde 50'ye ayarla" gibi ifadeler kullanarak da ses seviyesini kontrol edebilirler. İşleminizdeki amaçlar benzer eğitim ifadeleri kullanıyorsa önceliklidir. İşleminizin özel bir nedeni yoksa Asistan'ın bu kullanıcı isteklerini yerine getirmesine izin verin.

Android telefonlardaki davranış

Medya kontrolleri, Android telefonlarda telefon kilitliyken de kullanılabilir. Medya denetimleri de bildirim alanında görünür ve aşağıdaki koşullardan herhangi biri karşılandığında kullanıcılar medya yanıtlarını görebilir:

  • Google Asistan ön planda ve telefon ekranı açık.
  • Kullanıcı, ses çalarken Google Asistan'dan ayrılır ve çalma işlemi tamamlandıktan sonra 10 dakika içinde Google Asistan'a geri döner. Kullanıcı, Google Asistan'a döndüğünde medya kartını ve öneri çiplerini görür.

Özellikler

Medya yanıtları aşağıdaki özelliklere sahiptir:

Özellik Tür Koşul Açıklama
media_type MediaType Gerekli Sağlanan yanıtın medya türü. Medya durumunu onaylarken MEDIA_STATUS_ACK döndürün.
start_offset dize İsteğe bağlı İlk medya parçasını başlatmak için konum arayın. Değeri, en fazla dokuz ondalık basamakla ifade edilen kesirli saniyelerle saniye cinsinden sağlayın ve "s" sonekiyle bitirin. Örneğin, 3 saniye ve 1 nanosaniye, "3.000000001s" olarak ifade edilir.
optional_media_controls OptionalMediaControls dizisi İsteğe bağlı Bir kullanıcı medya oynatma durumunu değiştirdiğinde (ör. medya oynatmayı duraklatarak veya durdurarak) geri çağırma almak için özelliği etkinleştirin.
media_objects MediaObject dizisi Gerekli İsteme dahil edilecek medya nesnelerini temsil eder. MEDIA_STATUS_ACK ile bir medya durumunu onaylarken medya nesneleri sağlamayın.
first_media_object_index tam sayı İsteğe bağlı Oynayacak media_objects içindeki ilk MediaObject için 0 tabanlı dizin. Belirtilmemişse, sıfır veya sınırların dışındaysa oynatma ilk MediaObject konumundan başlar.
repeat_mode RepeatMode İsteğe bağlı Medya nesneleri listesi için tekrar modu.

Örnek kod

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"
    }
  }
}

Medya durumu alınıyor

Google Asistan, bir kullanıcı için medya oynatma sırasında veya sonrasında, oynatma İşleminizin ilerleme durumunu bildirmek için medya durumu etkinlikleri oluşturabilir. Kullanıcıları medya oynatmayı duraklattıklarında, durdurduklarında veya tamamladıklarında uygun şekilde yönlendirmek için webhook kodunuzda bu durum etkinliklerini işleyin.

Google Asistan, medya oynatma ilerlemesine ve kullanıcı sorgularına göre aşağıdaki listeden bir durum etkinliği döndürür:

  • FINISHED: Kullanıcı medya oynatmayı tamamlamıştır (veya sonraki medya parçasına atlar) ve geçiş, bir görüşme çıkışı değildir. Bu durum, MEDIA_STATUS_FINISHED sistem amacı ile de eşlenir.
  • PAUSED: Kullanıcı medya oynatmayı duraklattı. optional_media_controls mülkü ile bu durum etkinliğini almayı etkinleştirin. Bu durum, MEDIA_STATUS_PAUSED sistem amacı ile de eşlenir.
  • STOPPED: Kullanıcı medya oynatmayı durdurdu veya oynattı. optional_media_controls mülkü ile bu durum etkinliğini almayı etkinleştirin. Bu durum, MEDIA_STATUS_STOPPED sistem amacı ile de eşleşir.
  • FAILED: Medya oynatılamadı. Bu durum, MEDIA_STATUS_FAILED sistem amacı ile de eşlenir.

Medya oynatma sırasında, kullanıcı hem medyayı duraklatma hem de durdurma etkinliği olarak yorumlanabilen bir sorgu ("durdur", "iptal et" veya "çıkış" gibi) sağlayabilir. Bu durumda Asistan, İşleminize actions.intent.CANCEL sistem niyeti sağlar, "DURDURULDU" durum değerine sahip bir medya durumu etkinliği oluşturur ve İşleminizden tamamen çıkar.

Asistan, PAUSED veya STOPPED durum değeriyle bir medya durumu etkinliği oluşturduğunda, yalnızca onay (MEDIA_STATUS_ACK türünde) içeren bir medya yanıtıyla yanıt verin.

Medya ilerleme durumu

Webhook istekleri için mevcut medya oynatma durumu context.media.progress alanında bulunabilir. Medya ilerleme durumunu, medya oynatmanın sona erdiği noktada oynatmaya devam etmek için başlangıç zamanı ofseti olarak kullanabilirsiniz. Bir medya yanıtına başlangıç zamanı ofsetini uygulamak için start_offset özelliğini kullanın.

Örnek kod

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.');
  }
});

Oynatma listesini döndürme

Oynatma listesi oluşturmak için yanıtınıza birden fazla ses dosyası ekleyebilirsiniz. İlk parçanın çalınması bittiğinde, sonraki parça otomatik olarak çalınır ve bu, her parça çalınana kadar devam eder. Ayrıca kullanıcılar ekrandaki Sonraki düğmesine basabilir veya "Next" (Sonraki) diyebilir ya da sonraki parçaya atlamak için benzer bir şey söyleyebilirler.

Oynatma listesinin son parçasında Sonraki düğmesi devre dışıdır. Ancak döngü modunu etkinleştirirseniz oynatma listesi ilk parçadan tekrar başlar. Döngü modu hakkında daha fazla bilgi edinmek için Döngü modunu uygulama bölümüne bakın.

Oynatma listesi oluşturmak için media_objects dizisine birden fazla MediaObject ekleyin. Aşağıdaki kod snippet'inde, üç parçadan oluşan bir oynatma listesi döndüren bir istem gösterilmektedir:

{
  "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
                }
              }
            }
          ],
        }
      }
    }
  ]
}

Döngü modunu uygulayın

Döngü modu, otomatik olarak tekrarlanan bir sesli yanıt sağlamanıza olanak tanır. Bu modu tek bir parçayı tekrarlamak veya bir şarkı listesinde döngü yapmak için kullanabilirsiniz. Kullanıcı, döngülü tek bir parça için "Sonraki" veya benzer bir şey dediğinde şarkı tekrar başlar. Döngü içindeki şarkı listelerinde, "Sonraki" ifadesini söyleyen bir kullanıcı oynatma listesindeki sonraki parçayı başlatır.

Döngü modunu uygulamak için isteminize repeat_mode alanını ekleyip değerini ALL olarak ayarlayın. Bu ekleme, son medya nesnesinin sonuna ulaşıldığında medya yanıtınızın ilk medya nesnesinin başlangıcında döngüye alınmasını sağlar.

Aşağıdaki kod snippet'inde, döngülü bir parça döndüren bir istem gösterilmektedir:

{
  "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"
        }
      }
    }
  ]
}