MediaTrack
代表媒體音軌,可以是音訊串流、影片串流或文字 (例如字幕)。您的應用程式可以分類、設定媒體曲目及設定媒體曲目。
設定測試群組
您可以設定測試群組,並為測試群組指派專屬 ID。以下程式碼會建立英文文字音軌、法文版文字音軌和法文音軌,每個項目都有自己的 ID:
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()
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();
群組音軌
您可以將多個曲目組成一個媒體項目,以 MediaInfo
表示。MediaInfo
的例項會取用一系列軌跡,並匯總媒體項目的其他資訊。以這個範例為基礎,您的應用程式可以將這三個媒體曲目的清單傳遞至 MediaInfo.Builder.setMediaTracks(List)
,藉此將這三個媒體曲目加入媒體項目中。應用程式需要以這種方式在 MediaInfo
中建立關聯軌跡,才能將媒體載入至接收器。
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()
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();
移除測試群組
如要從目前媒體中移除所有曲目 (例如關閉範例中的三個字幕),請呼叫 MediaInfo.Builder.setMediaTracks(List)
,並傳遞空白的 ID 清單。
更新曲目
您的應用程式可以啟用一或多個與媒體項目相關聯的曲目 (載入媒體後),方法是呼叫 RemoteMediaClient.setActiveMediaTracks(long[])
,並傳遞要啟用的曲目 ID。以下範例會啟用法文字幕和法文音訊:
// 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 ) } })
// 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()); } });
設定文字軌樣式
TextTrackStyle
會封裝文字軌的樣式資訊。建立或更新現有的 TextTrackStyle 後,您可以呼叫 RemoteMediaClient.setTextTrackStyle
,將該樣式套用至目前播放的媒體項目,如下所示:
// 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 ) } })
remoteMediaClient.setTextTrackStyle(style) .setResultCallback(mediaChannelResult -> { if (!mediaChannelResult.getStatus().isSuccess()) { Log.e(TAG, "Failed to set the style, status code: " + mediaChannelResult.getStatus().getStatusCode()); } });
應用程式應允許使用者透過系統或應用程式本身的設定更新文字軌的樣式。在 Android KitKat 和以上版本中,您可以使用架構提供的整個系統隱藏式輔助字幕設定:
val textTrackStyle = TextTrackStyle.fromSystemSettings(context)
TextTrackStyle textTrackStyle = TextTrackStyle.fromSystemSettings(context);
如果是 KitKat 之前的版本,上述呼叫會傳回具有未定義欄位的物件,因此您必須根據使用者選取項目和部分預設值在應用程式中填入這些欄位。您可以設定下列文字軌樣式元素的樣式:
- 前景 (文字) 顏色和不透明度
- 背景色彩和透明度
- 邊緣類型
- 邊緣顏色
- 字型比例
- 字型系列
- 字型樣式
例如,將文字顏色設為紅色 (FF),以及透明度 50% (80),如下所示:
textTrackStyle.foregroundColor = Color.parseColor("#80FF0000")
textTrackStyle.setForegroundColor(Color.parseColor("#80FF0000"));
在 KitKat 和較新版本中,您應該註冊應用程式,以便在系統更新全系統隱藏式輔助字幕設定時收到通知。為此,您需要在應用程式中實作 CaptioningManager.CaptioningChangeListener
,並呼叫下列項目以註冊這個事件監聽器:
CaptioningManager.addCaptioningChangeListener(yourChangeListener)
CaptioningManager.addCaptioningChangeListener(yourChangeListener);
應用程式收到字幕設定變更的呼叫時,您需要擷取新設定,並呼叫 RemoteMediaClient.setTextTrackStyle
並傳入新樣式,為目前播放的媒體更新文字字幕樣式。
接收狀態更新資訊
當多位寄件者連線到同一個接收端時,每個寄件者都必須瞭解接收端的變更,即使這些變更是由其他寄件者發起也一樣。
為此,您的應用程式應註冊 RemoteMediaClient.Listener
和 RemoteMediaClient.ProgressListener
。
如果目前媒體的 TextTrackStyle
有所變更,所有已連結的傳送者都會透過上述兩個已註冊的事件監聽器收到通知。在這種情況下,接收器 SDK 不會驗證新樣式是否與前一個樣式不同,並會通知所有已連結的寄件者。不過,如果使用中的測試群組狀態有所變更,系統只會通知連線寄件者中的 RemoteMediaClient.ProgressListener
。
符合 CORS 需求條件
如要進行自動調整式媒體串流,Google Cast 需要使用 CORS 標頭,但即使是簡單的 mp4 媒體串流,則需有追蹤記錄 (如有) 才能使用 CORS。如果想為任何媒體啟用曲目,您必須同時為音軌串流和媒體串流啟用 CORS。因此,如果您在伺服器上沒有適用於簡易 mp4 媒體的 CORS 標頭,然後新增簡單的字幕軌,那麼除非您更新伺服器,加入適當的 CORS 標頭,否則無法串流媒體。此外,您至少須允許下列標頭:Content-Type、Accept-Encoding 和 Range。請注意,最後兩個標頭是之前您可能不需要的其他標頭。