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