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
17package android.media;
18
19import android.annotation.NonNull;
20import 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 */
66public 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 */
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     */
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     */
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     */
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     */
115    public @NonNull byte[] getData() {
116        return mData;
117    }
118
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