Ihrer Web Sender App erweiterte Funktionen hinzufügen

Werbeunterbrechungen

Das Web Sender SDK unterstützt Werbeunterbrechungen und Companion-Anzeigen in einem bestimmten Medienstream.

Weitere Informationen zur Funktionsweise von Werbeunterbrechungen findest du in der Übersicht zu Werbeunterbrechungen im Webempfänger.

Pausen können zwar sowohl auf dem Sender als auch auf dem Empfänger festgelegt werden, es wird jedoch empfohlen, sie auf dem Webempfänger und dem Android TV-Empfänger festzulegen, um ein einheitliches Verhalten auf allen Plattformen zu gewährleisten.

Im Web können Sie Werbeunterbrechungen in einem Ladebefehl mit BreakClip und Break angeben:

let breakClip1 = new BreakClip('bc0');
breakClip1.title = 'Clip title'
breakClip1.posterUrl = 'https://www.some.url';
breakClip1.duration = 60;
breakClip.whenSKippable = 5;

let breakClip2 = ...
let breakClip3 = ...

let break1 = new Break('b0', ['bc0', 'bc1', 'bc2'], 10);

let mediaInfo = new chrome.cast.media.MediaInfo(<contentId>, '<contentType');
...
mediaInfo.breakClips = [breakClip1, breakClip2, breakClip3];
mediaInfo.breaks = [break1];

let request = new chrome.cast.media.LoadRequest(mediaInfo);

cast.framework.CastContext.getInstance().getCurrentSession().loadMedia(request)

Tracks-APIs verwenden

Ein Track kann ein Textobjekt (Untertitel) oder ein Audio- oder Videostreamobjekt sein. Die Tracks APIs ermöglichen Ihnen die Arbeit mit diesen Objekten in Ihrer Anwendung.

Ein Track-Objekt stellt einen Track im SDK dar. So können Sie einen Track konfigurieren und ihm eine eindeutige ID zuweisen:

var englishSubtitle = new chrome.cast.media.Track(1, // track ID
  chrome.cast.media.TrackType.TEXT);
englishSubtitle.trackContentId = 'https://some-url/caption_en.vtt';
englishSubtitle.trackContentType = 'text/vtt';
englishSubtitle.subtype = chrome.cast.media.TextTrackType.SUBTITLES;
englishSubtitle.name = 'English Subtitles';
englishSubtitle.language = 'en-US';
englishSubtitle.customData = null;

var frenchSubtitle = new chrome.cast.media.Track(2, // track ID
  chrome.cast.media.TrackType.TEXT);
frenchSubtitle.trackContentId = 'https://some-url/caption_fr.vtt';
frenchSubtitle.trackContentType = 'text/vtt';
frenchSubtitle.subtype = chrome.cast.media.TextTrackType.SUBTITLES;
frenchSubtitle.name = 'French Subtitles';
frenchSubtitle.language = 'fr';
frenchSubtitle.customData = null;

var frenchAudio = new chrome.cast.media.Track(3, // track ID
  chrome.cast.media.TrackType.AUDIO);
frenchAudio.trackContentId = 'trk0001';
frenchAudio.trackContentType = 'audio/mp3';
frenchAudio.subtype = null;
frenchAudio.name = 'French Audio';
frenchAudio.language = 'fr';
frenchAudio.customData = null;

Ein Medienelement kann mehrere Tracks haben. So kann es beispielsweise mehrere Untertitel (jeweils für eine andere Sprache) oder mehrere alternative Audiostreams (für verschiedene Sprachen) haben.

MediaInfo ist die Klasse, die ein Medienelement modelliert. Wenn Sie eine Sammlung von Track-Objekten mit einem Medienelement verknüpfen möchten, aktualisieren Sie dessen Attribut tracks. Diese Verknüpfung muss hergestellt werden, bevor die Medien in den Empfänger geladen werden:

var tracks = [englishSubtitle, frenchSubtitle, frenchAudio];
var mediaInfo = new chrome.cast.media.MediaInfo(mediaURL);
mediaInfo.contentType = 'video/mp4';
mediaInfo.metadata = new chrome.cast.media.GenericMediaMetadata();
mediaInfo.customData = null;
mediaInfo.streamType = chrome.cast.media.StreamType.BUFFERED;
mediaInfo.textTrackStyle = new chrome.cast.media.TextTrackStyle();
mediaInfo.duration = null;
mediaInfo.tracks = tracks;

Sie können die aktiven Tracks in der Medien-activeTrackIds-Anfrage festlegen.

Sie können auch einen oder mehrere Tracks aktivieren, die mit dem Mediaelement verknüpft wurden, nachdem das Medium geladen wurde, indem Sie EditTracksInfoRequest(opt_activeTrackIds, opt_textTrackStyle) aufrufen und die IDs der zu aktivierenden Tracks in opt_activeTrackIds übergeben. Beide Parameter sind optional. Sie können selbst bestimmen, welche, aktive Tracks oder Stile Sie festlegen möchten. So aktivierst du beispielsweise die französischen Untertitel (2) und die französischen Audioinhalte (3):

var activeTrackIds = [2, 3];
var tracksInfoRequest = new chrome.cast.media.EditTracksInfoRequest(activeTrackIds);
media.editTracksInfo(tracksInfoRequest, successCallback, errorCallback);

Wenn Sie alle Audio- oder Videotracks vom aktuellen Medium entfernen möchten, legen Sie einfach mediaInfo.tracks=null (ein leeres Array) fest und laden Sie die Medien neu.

Führe einen der folgenden Schritte aus, um alle Texttracks aus den aktuellen Medien zu entfernen und z. B. Untertitel zu deaktivieren:

  • Aktualisiere var activeTrackIds = [2, 3]; (wie zuvor gezeigt), sodass nur der Audiotrack [3] enthalten ist.
  • Legen Sie dazu mediaInfo.tracks=null fest. Es ist nicht notwendig, die Medien neu zu laden, um Textuntertitel (track.hidden) zu deaktivieren. Wenn ein activeTracksId-Array gesendet wird, das keine zuvor aktivierte trackId enthält, wird der Text-Track deaktiviert.

Stile für Textspuren festlegen

TextTrackStyle ist das Objekt, in dem die Stilinformationen eines Text-Tracks zusammengefasst werden. Nachdem Sie ein TextTrackStyle-Objekt erstellt oder aktualisiert haben, können Sie es auf das aktuell wiedergegebene Medienelement anwenden. Rufen Sie dazu die zugehörige Methode editTrackInfo auf:

var textTrackStyle = new chrome.cast.media.TextTrackStyle();
var tracksInfoRequest = new chrome.cast.media.EditTracksInfoRequest(textTrackStyle);
media.editTracksInfo(tracksInfoRequest, successCallback, errorCallback);

Sie können den Status der Anfrage anhand des Ergebnisses der Callbacks (Erfolg oder Fehler) verfolgen und den ursprünglichen Absender entsprechend aktualisieren.

Anwendungen sollten es Nutzern ermöglichen, den Stil von Textspuren über die vom System oder von der Anwendung selbst bereitgestellten Einstellungen zu aktualisieren.

Sie können die folgenden Stilelemente für Text-Tracks gestalten:

  • Farbe und Deckkraft des Vordergrunds (Text)
  • Farbe und Transparenz des Hintergrunds
  • Rahmentyp
  • Rahmenfarbe
  • Schriftgrad
  • Schriftfamilie
  • Schriftstil

Legen Sie beispielsweise als Textfarbe Rot mit einer Deckkraft von 75% fest:

var textTrackStyle = new chrome.cast.media.TextTrackStyle();
textTrackStyle.foregroundColor = '#80FF0000';

Lautstärkeregelung

Mit RemotePlayer und RemotePlayerController können Sie die Empfängerlautstärke einstellen.

function changeVolume(newVolume) {
  player.volumeLevel = newVolume;
  playerController.setVolumeLevel();
  // Update sender UI to reflect change
}

Die Sender-App muss zur Lautstärkeregelung die folgenden Richtlinien einhalten:

  • Die Senderanwendung muss mit dem Empfänger synchronisiert werden, damit die Absender-UI immer das Volumen pro Empfänger meldet. Verwenden Sie die Callbacks RemotePlayerEventType.VOLUME_LEVEL_CHANGED und RemotePlayerEventType.IS_MUTED_CHANGED, um die Lautstärke beim Absender aufrechtzuerhalten. Weitere Informationen finden Sie unter Statusaktualisierungen.
  • Absender-Apps dürfen die Lautstärke nicht auf eine bestimmte, vordefinierte Stufe setzen oder die Lautstärke auf die Klingelton-/Medienlautstärke des Absendergeräts einstellen, wenn die App auf dem Empfänger geladen wird.

Weitere Informationen finden Sie in der Design-Checkliste unter Lautstärkeregler für Absender.

Mediennachrichten an den Empfänger senden

Media Messages kann vom Sender an den Empfänger gesendet werden. So senden Sie beispielsweise eine SKIP_AD-Nachricht an den Empfänger:

// Get a handle to the skip button element
const skipButton = document.getElementById('skip');
skipButton.addEventListener("click", function() {
  if (castSession) {
    const media = castSession.getMediaSession();
    castSession.sendMessage('urn:x-cast:com.google.cast.media', {
      type: 'SKIP_AD',
      requestId: 1,
      mediaSessionId: media.mediaSessionId
    });
  }
});

Statusaktualisierungen

Wenn mehrere Sender mit demselben Empfänger verbunden sind, ist es wichtig, dass jeder Sender über die Änderungen auf dem Empfänger informiert ist, auch wenn diese Änderungen von anderen Absendern initiiert wurden.

Zu diesem Zweck sollte die Anwendung alle erforderlichen Listener im RemotePlayerController registrieren. Wenn sich der TextTrackStyle der aktuellen Medien ändert, werden alle verbundenen Absender benachrichtigt und die entsprechenden Attribute der aktuellen Mediensitzung, z. B. activeTrackIds und textTrackStyle des Felds MediaInfo, werden in Callbacks an Absender gesendet. In diesem Fall prüft das Receiver-SDK nicht, ob sich der neue Stil vom vorherigen unterscheidet, und benachrichtigt trotzdem alle verbundenen Absender.

Fortschrittsanzeige

Bei den meisten Apps ist es erforderlich, den Wiedergabeort mit einer Fortschrittsanzeige auf dem Absender zu sehen. Die Cast APIs verwenden das Cast-Medienprotokoll, mit dem die Bandbreitennutzung für dieses und andere Szenarien optimiert wird, sodass Sie keine eigene Statussynchronisierung implementieren müssen. Informationen zur korrekten Implementierung einer Fortschrittsanzeige für die Medienwiedergabe mithilfe der APIs findest du in der Beispiel-App CastVideos-chrome.

CORS-Anforderungen

Für adaptives Mediastreaming sind für Google Cast CORS-Header erforderlich, aber selbst einfache MP4-Medienstreams benötigen CORS, wenn sie Titel enthalten. Wenn Sie Tracks für alle Medien aktivieren möchten, müssen Sie CORS sowohl für Ihre Track- als auch für Ihre Medienstreams aktivieren. Wenn auf Ihrem Server keine CORS-Header für Ihre einfachen MP4-Medien zur Verfügung stehen und Sie dann eine einfache Untertitelspur hinzufügen, können Sie Ihre Medien erst streamen, wenn Sie die entsprechenden CORS-Header auf dem Server aktualisieren.

Sie benötigen die folgenden Header: Content-Type, Accept-Encoding und Range. Die letzten beiden Header Accept-Encoding und Range sind zusätzliche Header, die Sie möglicherweise zuvor nicht benötigt haben.

Platzhalter „*“ können nicht für den Access-Control-Allow-Origin-Header verwendet werden. Wenn die Seite geschützte Medieninhalte enthält, muss eine Domain anstelle eines Platzhalters verwendet werden.

Sitzung fortsetzen, ohne die Webseite zu aktualisieren

Wenn Sie eine vorhandene CastSession fortsetzen möchten, verwenden Sie requestSessionById(sessionId) mit der sessionId der Sitzung, an der Sie teilnehmen möchten.

Das sessionId kann mit getSessionId() nach dem Aufrufen von loadMedia() in der aktiven CastSession gefunden werden.

Wir empfehlen folgende Vorgehensweise:

  1. loadMedia() aufrufen, um die Sitzung zu starten
  2. sessionId lokal speichern
  3. Nehmen Sie bei Bedarf mit requestSessionById(sessionId) wieder an der Sitzung teil.
let sessionId;

function rejoinCastSession() {
  chrome.cast.requestSessionById(sessionId);

  // Add any business logic to load new content or only resume the session
}

document.getElementById('play-button').addEventListener(("click"), function() {
  if (sessionId == null) {
    let castSession = cast.framework.CastContext.getInstance().getCurrentSession();
    if (castSession) {
      let mediaInfo = createMediaInfo();
      let request = new chrome.cast.media.LoadRequest(mediaInfo);
      castSession.loadMedia(request)

      sessionId = CastSession.getSessionId();
    } else {
      console.log("Error: Attempting to play media without a Cast Session");
    }
  } else {
    rejoinCastSession();
  }
});

Nächste Schritte

Damit sind die Funktionen abgeschlossen, die Sie Ihrer Web Sender-App hinzufügen können. Sie können jetzt eine Sender-App für eine andere Plattform (Android oder iOS) oder eine Empfänger-App erstellen.