Utiliser des pistes multimédias

MediaTrack représente une piste multimédia, qui peut être un flux audio, un flux vidéo ou du texte (comme des sous-titres). Votre application peut regrouper, styliser et activer des canaux multimédias.

Configurer un canal

Vous pouvez configurer un titre et lui attribuer un identifiant unique. Le code suivant crée une piste de texte en anglais, une piste de texte en français et une piste audio en français, chacune avec son propre ID:

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();

Regrouper des titres

Vous pouvez regrouper plusieurs pistes dans un élément multimédia, représenté par MediaInfo. Une instance de MediaInfo utilise un tableau de pistes et agrège d'autres informations sur l'élément multimédia. En nous appuyant sur l'exemple, votre application peut ajouter ces trois pistes multimédias à un élément multimédia en transmettant une liste de ces trois pistes dans MediaInfo.Builder.setMediaTracks(List). Votre application doit ainsi associer les pistes dans un MediaInfo pour pouvoir charger le contenu multimédia sur le récepteur.

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();

Supprimer les canaux

Pour supprimer toutes les pistes du support actuel (par exemple en désactivant les trois sous-titres dans l'exemple), appelez MediaInfo.Builder.setMediaTracks(List) et transmettez une liste d'ID vide.

Mettre à jour les titres

Votre application peut activer un ou plusieurs canaux associés à l'élément multimédia (après le chargement du média) en appelant RemoteMediaClient.setActiveMediaTracks(long[]) et en transmettant les ID des canaux à activer. Cet exemple active le sous-titre et l'audio en français:

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());
        }
    });

Appliquer un style aux pistes de texte

TextTrackStyle encapsule les informations de style d'une piste de texte. Après avoir créé ou mis à jour un TextTrackStyle existant, vous pouvez appliquer ce style à l'élément multimédia en cours de lecture en appelant RemoteMediaClient.setTextTrackStyle, comme suit:

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());
        }
    });

Votre application doit permettre aux utilisateurs de modifier le style des pistes de texte en utilisant les paramètres fournis par le système ou par l'application elle-même. Sous Android KitKat et versions ultérieures, vous pouvez utiliser les paramètres de sous-titres pour l'ensemble du système fournis par le framework:

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

Pour les versions antérieures à KitKat, l'appel ci-dessus renvoie un objet dont les champs ne sont pas définis. Vous devez donc renseigner ces champs dans votre application, en fonction des sélections des utilisateurs et de certaines valeurs par défaut. Vous pouvez styliser les éléments de style de la piste de texte suivants:

  • Couleur et opacité au premier plan (texte)
  • Couleur et opacité de l'arrière-plan
  • Type de contour
  • Couleur du contour
  • Échelle de police
  • Famille de polices
  • Style de police

Par exemple, définissez la couleur du texte sur rouge (FF) avec 50% d'opacité (80) comme suit:

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

Dans KitKat et versions ultérieures, vous devez enregistrer votre application pour être informé lorsque les paramètres des sous-titres pour l'ensemble du système sont mis à jour. Pour cela, vous devez implémenter CaptioningManager.CaptioningChangeListener dans votre application et enregistrer cet écouteur en appelant la méthode suivante:

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

Lorsque votre application reçoit un appel indiquant que les paramètres de sous-titres ont été modifiés, vous devez extraire les nouveaux paramètres et mettre à jour le style du sous-titre du texte en cours de lecture en appelant RemoteMediaClient.setTextTrackStyle et en transmettant le nouveau style.

Recevoir des informations sur l'état

Lorsque plusieurs expéditeurs sont connectés au même destinataire, il est important que chaque expéditeur soit informé des modifications apportées au récepteur, même si ces modifications proviennent d'autres expéditeurs.

À cette fin, votre application doit enregistrer un RemoteMediaClient.Listener et un RemoteMediaClient.ProgressListener.

Si la valeur TextTrackStyle du média actuel change, tous les expéditeurs connectés seront avertis par les deux écouteurs enregistrés ci-dessus. Dans ce cas, le SDK du récepteur ne vérifie pas si le nouveau style est différent du précédent et notifie tous les expéditeurs connectés. Toutefois, si l'état des canaux actifs change, seuls les RemoteMediaClient.ProgressListener des expéditeurs connectés seront avertis.

Répondre aux exigences CORS

Pour le streaming multimédia adaptatif, Google Cast nécessite la présence d'en-têtes CORS. Cependant, même les flux multimédias mp4 simples nécessitent CORS s'ils incluent des titres. Si vous souhaitez activer le suivi pour n'importe quel média, vous devez activer le CORS pour vos flux de piste et vos flux multimédias. Ainsi, si aucun en-tête CORS n'est disponible pour votre média mp4 simple sur votre serveur, et que vous ajoutez ensuite une piste de sous-titres simple, vous ne pourrez pas diffuser votre contenu multimédia en streaming, sauf si vous mettez à jour votre serveur afin d'inclure l'en-tête CORS approprié. De plus, vous devez autoriser au moins les en-têtes suivants : Content-Type, Accept-Encoding et Range. Notez que les deux derniers en-têtes sont des en-têtes supplémentaires dont vous n'avez peut-être pas besoin auparavant.