Media-Tracks verwenden

Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

MediaTrack steht für einen Medien-Track, der einen Audiostream, einen Videostream oder Text (z. B. Untertitel) umfassen kann. Deine App kann Medien-Tracks gruppieren, gestalten und aktivieren.

Track konfigurieren

Du kannst einen Track konfigurieren und ihm eine eindeutige ID zuweisen. Mit dem folgenden Code werden ein englischer, ein französischer und ein Audiotrack mit jeweils einer eigenen ID erstellt:

Kotlin
val englishSubtitle = MediaTrack.Builder(1 /* ID */, MediaTrack.TYPE_TEXT)
    .setName("English Subtitle")
    .setSubtype(MediaTrack.SUBTYPE_SUBTITLES)
    .setContentId("https://some-url/caption_en.vtt")
    /* language is required for subtitle type but optional otherwise */
    .setLanguage("en-US")
    .build()

val frenchSubtitle = MediaTrack.Builder(2, MediaTrack.TYPE_TEXT)
    .setName("French Subtitle")
    .setSubtype(MediaTrack.SUBTYPE_SUBTITLES)
    .setContentId("https://some-url/caption_fr.vtt")
    .setLanguage("fr")
    .build()

val frenchAudio = MediaTrack.Builder(3, MediaTrack.TYPE_AUDIO)
    .setName("French Audio")
    .setContentId("trk0001")
    .setLanguage("fr")
    .build()
Java
MediaTrack englishSubtitle = new MediaTrack.Builder(1 /* ID */,
MediaTrack.TYPE_TEXT)
  .setName("English Subtitle")
  .setSubtype(MediaTrack.SUBTYPE_SUBTITLES)
  .setContentId("https://some-url/caption_en.vtt")
  /* language is required for subtitle type but optional otherwise */
  .setLanguage("en-US")
  .build();

MediaTrack frenchSubtitle = new MediaTrack.Builder(2, MediaTrack.TYPE_TEXT)
  .setName("French Subtitle")
  .setSubtype(MediaTrack.SUBTYPE_SUBTITLES)
  .setContentId("https://some-url/caption_fr.vtt")
  .setLanguage("fr")
  .build();

MediaTrack frenchAudio = new MediaTrack.Builder(3, MediaTrack.TYPE_AUDIO)
  .setName("French Audio")
  .setContentId("trk0001")
  .setLanguage("fr")
  .build();

Tracks gruppieren

Du kannst mehrere Titel in einem Medienelement gruppieren, das durch MediaInfo dargestellt wird. Eine Instanz von MediaInfo nimmt ein Array von Tracks an und fasst weitere Informationen zum Medienelement zusammen. Basierend auf dem Beispiel kann Ihre App diese drei Medien-Tracks einem Medienelement hinzufügen, indem sie eine Liste dieser drei Tracks an MediaInfo.Builder.setMediaTracks(List) übergibt. Deine App muss Tracks auf diese Weise mit einem MediaInfo verknüpfen, bevor die Medien an den Empfänger geladen werden.

Kotlin
val tracks: MutableList<MediaTrack> = ArrayList<MediaTrack>()
tracks.add(englishSubtitle)
tracks.add(frenchSubtitle)
tracks.add(frenchAudio)
val mediaInfo = MediaInfo.Builder(url)
    .setStreamType(MediaInfo.STREAM_TYPE_BUFFERED)
    .setContentType(getContentType())
    .setMetadata(getMetadata())
    .setMediaTracks(tracks)
    .build()
Java
List tracks = new ArrayList();
tracks.add(englishSubtitle);
tracks.add(frenchSubtitle);
tracks.add(frenchAudio);
MediaInfo mediaInfo = MediaInfo.Builder(url)
  .setStreamType(MediaInfo.STREAM_TYPE_BUFFERED)
  .setContentType(getContentType())
  .setMetadata(getMetadata())
  .setMediaTracks(tracks)
  .build();

Tracks entfernen

Wenn Sie alle Tracks aus dem aktuellen Medium entfernen und beispielsweise die drei Untertitel deaktivieren möchten, rufen Sie MediaInfo.Builder.setMediaTracks(List) auf und übergeben Sie eine leere Liste von IDs.

Titel aktualisieren

Ihre App kann einen oder mehrere Tracks aktivieren, die mit dem Medienelement verknüpft wurden (nachdem das Medium geladen wurde), indem RemoteMediaClient.setActiveMediaTracks(long[]) aufgerufen und die IDs der zu aktivierenden Tracks übergeben werden. In diesem Beispiel werden der französische Untertitel und die französische Version aktiviert:

Kotlin
// the ID for the French subtitle is '2' and for the French audio '3'
remoteMediaClient.setActiveMediaTracks(longArrayOf(2, 3))
    .setResultCallback(ResultCallback {
            mediaChannelResult: RemoteMediaClient.MediaChannelResult ->
                if (!mediaChannelResult.status.isSuccess) {
                    Log.e(TAG, "Failed with status code:" +
                            mediaChannelResult.status.statusCode
                    )
                }
    })
Java
// the ID for the French subtitle is '2' and for the French audio '3'
remoteMediaClient.setActiveMediaTracks(new long[]{2, 3})
    .setResultCallback(mediaChannelResult -> {
        if (!mediaChannelResult.getStatus().isSuccess()) {
            Log.e(TAG, "Failed with status code:" +
                    mediaChannelResult.getStatus().getStatusCode());
        }
    });

Texttracks gestalten

Mit TextTrackStyle werden die Stilinformationen eines Texttracks zusammengefasst. Nachdem Sie einen vorhandenen TextTrackStyle erstellt oder aktualisiert haben, können Sie diesen Stil auf das aktuell wiedergegebene Medienelement anwenden. Dazu rufen Sie RemoteMediaClient.setTextTrackStyle auf:

Kotlin
// the ID for the French subtitle is '2' and for the French audio '3'
remoteMediaClient.setTextTrackStyle(style)
    .setResultCallback(ResultCallback {
            mediaChannelResult: RemoteMediaClient.MediaChannelResult ->
                if (!mediaChannelResult.status.isSuccess) {
                    Log.e(TAG, "Failed to set the style, status code: " +
                            mediaChannelResult.status.statusCode
                    )
                }
    })
Java
remoteMediaClient.setTextTrackStyle(style)
    .setResultCallback(mediaChannelResult -> {
        if (!mediaChannelResult.getStatus().isSuccess()) {
            Log.e(TAG, "Failed to set the style, status code: " +
                    mediaChannelResult.getStatus().getStatusCode());
        }
    });

Deine App sollte es Nutzern ermöglichen, den Stil für Texttracks entweder mithilfe der vom System bereitgestellten Einstellungen oder der App selbst zu aktualisieren. Ab Android KitKat kannst du die vom Framework bereitgestellten systemweiten Untertiteleinstellungen verwenden:

Kotlin
val textTrackStyle = TextTrackStyle.fromSystemSettings(context)
Java
TextTrackStyle textTrackStyle = TextTrackStyle.fromSystemSettings(context);

Für Versionen vor KitKat wird durch den obigen Aufruf ein Objekt zurückgegeben, dessen Felder nicht definiert sind. Sie müssen diese Felder dann in der App basierend auf der Nutzerauswahl und einigen Standardwerten füllen. Sie können die folgenden Stile für Texttracks gestalten:

  • Vordergrundfarbe (Text) und Deckkraft
  • Farbe und Transparenz des Hintergrunds
  • Rahmentyp
  • Rahmenfarbe
  • Schriftgröße
  • Schriftfamilie
  • Schriftstil

Legen Sie beispielsweise für die Textfarbe Rot (FF) mit einer Opazität von 50 % (80) fest:

Kotlin
textTrackStyle.foregroundColor = Color.parseColor("#80FF0000")
Java
textTrackStyle.setForegroundColor(Color.parseColor("#80FF0000"));

In KitKat und höher solltest du deine App registrieren, um benachrichtigt zu werden, wenn die systemweiten Untertiteleinstellungen aktualisiert werden. Zu diesem Zweck müssen Sie CaptioningManager.CaptioningChangeListener in Ihrer Anwendung implementieren und diesen Listener durch folgenden Aufruf registrieren:

Kotlin
CaptioningManager.addCaptioningChangeListener(yourChangeListener)
Java
CaptioningManager.addCaptioningChangeListener(yourChangeListener);

Wenn Ihre App einen Callback erhält, dass die Untertiteleinstellungen geändert wurden, müssen Sie die neuen Einstellungen extrahieren und den Stil der Textuntertitel für das aktuell abgespielte Medium aktualisieren. Dazu rufen Sie RemoteMediaClient.setTextTrackStyle auf und übergeben den neuen Stil.

Statusupdates erhalten

Wenn mehrere Absender mit demselben Empfänger verbunden sind, ist es wichtig, dass jeder Absender die Änderungen im Empfänger erkennt, auch wenn diese Änderungen von anderen Absendern stammen.

Zu diesem Zweck sollte Ihre Anwendung eine RemoteMediaClient.Listener und eine RemoteMediaClient.ProgressListener registrieren.

Wenn sich TextTrackStyle der aktuellen Medien ändert, werden alle verbundenen Absender über die beiden oben genannten Listener benachrichtigt. In diesem Fall prüft das Receiver SDK nicht, ob der neue Stil sich vom vorherigen unterscheidet, und benachrichtigt alle verbundenen Absender unabhängig davon. Wenn sich der Status von aktiven Tracks jedoch ändert, wird nur die RemoteMediaClient.ProgressListener bei verbundenen Absendern benachrichtigt.

CORS-Anforderungen erfüllen

Für adaptives Media-Streaming sind für Google Cast CORS-Header erforderlich. Aber auch einfache MP4-Medienstreams erfordern CORS, wenn sie Tracks enthalten. Wenn Sie Tracks für beliebige Medien aktivieren möchten, müssen Sie CORS sowohl für Ihre Track- als auch für Ihre Media-Streams aktivieren. Wenn auf deinem Server also keine CORS-Header für deine einfachen MP4-Medien verfügbar sind und du dann einen einfachen Untertitel-Track hinzufügst, kannst du deine Medien nur streamen, wenn du deinen Server mit dem entsprechenden CORS-Header aktualisierst. Außerdem müssen Sie mindestens die folgenden Header zulassen: Content-Type, Accept-Encoding und Range. Die letzten beiden Header sind zusätzliche Header, die Sie möglicherweise zuvor nicht benötigt haben.