1 /* 2 * Copyright (C) 2011 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package android.media; 18 19 import android.annotation.NonNull; 20 import android.os.Parcel; 21 22 /** 23 * Class encapsulating subtitle data, as received through the 24 * {@link MediaPlayer.OnSubtitleDataListener} interface. 25 * The subtitle data includes: 26 * <ul> 27 * <li> the track index</li> 28 * <li> the start time (in microseconds) of the data</li> 29 * <li> the duration (in microseconds) of the data</li> 30 * <li> the actual data.</li> 31 * </ul> 32 * The data is stored in a byte-array, and is encoded in one of the supported in-band 33 * subtitle formats. The subtitle encoding is determined by the MIME type of the 34 * {@link MediaPlayer.TrackInfo} of the subtitle track, one of 35 * {@link MediaFormat#MIMETYPE_TEXT_CEA_608}, {@link MediaFormat#MIMETYPE_TEXT_CEA_708}, 36 * {@link MediaFormat#MIMETYPE_TEXT_VTT}. 37 * <p> 38 * Here is an example of iterating over the tracks of a {@link MediaPlayer}, and checking which 39 * encoding is used for the subtitle tracks: 40 * <p> 41 * <pre class="prettyprint"> 42 * MediaPlayer mp = new MediaPlayer(); 43 * mp.setDataSource(myContentLocation); 44 * mp.prepare(); // synchronous prepare, ready to use when method returns 45 * final TrackInfo[] trackInfos = mp.getTrackInfo(); 46 * for (TrackInfo info : trackInfo) { 47 * if (info.getTrackType() == TrackInfo.MEDIA_TRACK_TYPE_SUBTITLE) { 48 * final String mime = info.getFormat().getString(MediaFormat.KEY_MIME); 49 * if (MediaFormat.MIMETYPE_TEXT_CEA_608.equals(mime) { 50 * // subtitle encoding is CEA 608 51 * } else if (MediaFormat.MIMETYPE_TEXT_CEA_708.equals(mime) { 52 * // subtitle encoding is CEA 708 53 * } else if (MediaFormat.MIMETYPE_TEXT_VTT.equals(mime) { 54 * // subtitle encoding is WebVTT 55 * } 56 * } 57 * } 58 * </pre> 59 * <p> 60 * See 61 * {@link MediaPlayer#setOnSubtitleDataListener(android.media.MediaPlayer.OnSubtitleDataListener, android.os.Handler)} 62 * to receive subtitle data from a MediaPlayer object. 63 * 64 * @see android.media.MediaPlayer 65 */ 66 public final class SubtitleData 67 { 68 private static final String TAG = "SubtitleData"; 69 70 private int mTrackIndex; 71 private long mStartTimeUs; 72 private long mDurationUs; 73 private byte[] mData; 74 75 /** @hide */ SubtitleData(Parcel parcel)76 public SubtitleData(Parcel parcel) { 77 if (!parseParcel(parcel)) { 78 throw new IllegalArgumentException("parseParcel() fails"); 79 } 80 } 81 82 /** 83 * Returns the index of the MediaPlayer track which contains this subtitle data. 84 * @return an index in the array returned by {@link MediaPlayer#getTrackInfo()}. 85 */ getTrackIndex()86 public int getTrackIndex() { 87 return mTrackIndex; 88 } 89 90 /** 91 * Returns the media time at which the subtitle should be displayed, expressed in microseconds. 92 * @return the display start time for the subtitle 93 */ getStartTimeUs()94 public long getStartTimeUs() { 95 return mStartTimeUs; 96 } 97 98 /** 99 * Returns the duration in microsecond during which the subtitle should be displayed. 100 * @return the display duration for the subtitle 101 */ getDurationUs()102 public long getDurationUs() { 103 return mDurationUs; 104 } 105 106 /** 107 * Returns the encoded data for the subtitle content. 108 * Encoding format depends on the subtitle type, refer to 109 * <a href="https://en.wikipedia.org/wiki/CEA-708">CEA 708</a>, 110 * <a href="https://en.wikipedia.org/wiki/EIA-608">CEA/EIA 608</a> and 111 * <a href="https://www.w3.org/TR/webvtt1/">WebVTT</a>, defined by the MIME type 112 * of the subtitle track. 113 * @return the encoded subtitle data 114 */ getData()115 public @NonNull byte[] getData() { 116 return mData; 117 } 118 parseParcel(Parcel parcel)119 private boolean parseParcel(Parcel parcel) { 120 parcel.setDataPosition(0); 121 if (parcel.dataAvail() == 0) { 122 return false; 123 } 124 125 mTrackIndex = parcel.readInt(); 126 mStartTimeUs = parcel.readLong(); 127 mDurationUs = parcel.readLong(); 128 mData = new byte[parcel.readInt()]; 129 parcel.readByteArray(mData); 130 131 return true; 132 } 133 } 134