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 * Constructor. 84 * 85 * @param trackIndex the index of the media player track which contains this subtitle data. 86 * @param startTimeUs the start time in microsecond for the subtitle data 87 * @param durationUs the duration in microsecond for the subtitle data 88 * @param data the data array for the subtitle data. It should not be null. 89 * No data copying is made. 90 */ SubtitleData(int trackIndex, long startTimeUs, long durationUs, @NonNull byte[] data)91 public SubtitleData(int trackIndex, long startTimeUs, long durationUs, @NonNull byte[] data) { 92 if (data == null) { 93 throw new IllegalArgumentException("null data is not allowed"); 94 } 95 mTrackIndex = trackIndex; 96 mStartTimeUs = startTimeUs; 97 mDurationUs = durationUs; 98 mData = data; 99 } 100 101 /** 102 * Returns the index of the media player track which contains this subtitle data. 103 * @return an index in the array returned by {@link MediaPlayer#getTrackInfo()}. 104 */ getTrackIndex()105 public int getTrackIndex() { 106 return mTrackIndex; 107 } 108 109 /** 110 * Returns the media time at which the subtitle should be displayed, expressed in microseconds. 111 * @return the display start time for the subtitle 112 */ getStartTimeUs()113 public long getStartTimeUs() { 114 return mStartTimeUs; 115 } 116 117 /** 118 * Returns the duration in microsecond during which the subtitle should be displayed. 119 * @return the display duration for the subtitle 120 */ getDurationUs()121 public long getDurationUs() { 122 return mDurationUs; 123 } 124 125 /** 126 * Returns the encoded data for the subtitle content. 127 * Encoding format depends on the subtitle type, refer to 128 * <a href="https://en.wikipedia.org/wiki/CEA-708">CEA 708</a>, 129 * <a href="https://en.wikipedia.org/wiki/EIA-608">CEA/EIA 608</a> and 130 * <a href="https://www.w3.org/TR/webvtt1/">WebVTT</a>, defined by the MIME type 131 * of the subtitle track. 132 * @return the encoded subtitle data 133 */ getData()134 public @NonNull byte[] getData() { 135 return mData; 136 } 137 parseParcel(Parcel parcel)138 private boolean parseParcel(Parcel parcel) { 139 parcel.setDataPosition(0); 140 if (parcel.dataAvail() == 0) { 141 return false; 142 } 143 144 mTrackIndex = parcel.readInt(); 145 mStartTimeUs = parcel.readLong(); 146 mDurationUs = parcel.readLong(); 147 mData = new byte[parcel.readInt()]; 148 parcel.readByteArray(mData); 149 150 return true; 151 } 152 } 153