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.
Davranış
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" } } } ] }