Home | History | Annotate | Download | only in media 
      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 */
     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