aabf284cbb
Expose in SDK the interfaces necessary to implement unbundled
subtitle support, which requires:
- exposing an interface to receive the encoded subtitle data
- exposing an interface while allows a renderer to synchronize
its rendering clock with the media time of the player.
Deprecate duplicated timed text constant, all timed text / sub
mime types are defined in MediaFormat.
Bug: 76121592
Test: make offline-sdk-docs
Change-Id: I42cc1d69069babb69a2feeba3f54da89889f4602
134 lines
4.5 KiB
Java
134 lines
4.5 KiB
Java
/*
|
|
* Copyright (C) 2011 The Android Open Source Project
|
|
*
|
|
* Licensed under the Apache License, Version 2.0 (the "License");
|
|
* you may not use this file except in compliance with the License.
|
|
* You may obtain a copy of the License at
|
|
*
|
|
* http://www.apache.org/licenses/LICENSE-2.0
|
|
*
|
|
* Unless required by applicable law or agreed to in writing, software
|
|
* distributed under the License is distributed on an "AS IS" BASIS,
|
|
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
* See the License for the specific language governing permissions and
|
|
* limitations under the License.
|
|
*/
|
|
|
|
package android.media;
|
|
|
|
import android.annotation.NonNull;
|
|
import android.os.Parcel;
|
|
|
|
/**
|
|
* Class encapsulating subtitle data, as received through the
|
|
* {@link MediaPlayer.OnSubtitleDataListener} interface.
|
|
* The subtitle data includes:
|
|
* <ul>
|
|
* <li> the track index</li>
|
|
* <li> the start time (in microseconds) of the data</li>
|
|
* <li> the duration (in microseconds) of the data</li>
|
|
* <li> the actual data.</li>
|
|
* </ul>
|
|
* The data is stored in a byte-array, and is encoded in one of the supported in-band
|
|
* subtitle formats. The subtitle encoding is determined by the MIME type of the
|
|
* {@link MediaPlayer.TrackInfo} of the subtitle track, one of
|
|
* {@link MediaFormat#MIMETYPE_TEXT_CEA_608}, {@link MediaFormat#MIMETYPE_TEXT_CEA_708},
|
|
* {@link MediaFormat#MIMETYPE_TEXT_VTT}.
|
|
* <p>
|
|
* Here is an example of iterating over the tracks of a {@link MediaPlayer}, and checking which
|
|
* encoding is used for the subtitle tracks:
|
|
* <p>
|
|
* <pre class="prettyprint">
|
|
* MediaPlayer mp = new MediaPlayer();
|
|
* mp.setDataSource(myContentLocation);
|
|
* mp.prepare(); // synchronous prepare, ready to use when method returns
|
|
* final TrackInfo[] trackInfos = mp.getTrackInfo();
|
|
* for (TrackInfo info : trackInfo) {
|
|
* if (info.getTrackType() == TrackInfo.MEDIA_TRACK_TYPE_SUBTITLE) {
|
|
* final String mime = info.getFormat().getString(MediaFormat.KEY_MIME);
|
|
* if (MediaFormat.MIMETYPE_TEXT_CEA_608.equals(mime) {
|
|
* // subtitle encoding is CEA 608
|
|
* } else if (MediaFormat.MIMETYPE_TEXT_CEA_708.equals(mime) {
|
|
* // subtitle encoding is CEA 708
|
|
* } else if (MediaFormat.MIMETYPE_TEXT_VTT.equals(mime) {
|
|
* // subtitle encoding is WebVTT
|
|
* }
|
|
* }
|
|
* }
|
|
* </pre>
|
|
* <p>
|
|
* See
|
|
* {@link MediaPlayer#setOnSubtitleDataListener(android.media.MediaPlayer.OnSubtitleDataListener, android.os.Handler)}
|
|
* to receive subtitle data from a MediaPlayer object.
|
|
*
|
|
* @see android.media.MediaPlayer
|
|
*/
|
|
public final class SubtitleData
|
|
{
|
|
private static final String TAG = "SubtitleData";
|
|
|
|
private int mTrackIndex;
|
|
private long mStartTimeUs;
|
|
private long mDurationUs;
|
|
private byte[] mData;
|
|
|
|
/** @hide */
|
|
public SubtitleData(Parcel parcel) {
|
|
if (!parseParcel(parcel)) {
|
|
throw new IllegalArgumentException("parseParcel() fails");
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Returns the index of the MediaPlayer track which contains this subtitle data.
|
|
* @return an index in the array returned by {@link MediaPlayer#getTrackInfo()}.
|
|
*/
|
|
public int getTrackIndex() {
|
|
return mTrackIndex;
|
|
}
|
|
|
|
/**
|
|
* Returns the media time at which the subtitle should be displayed, expressed in microseconds.
|
|
* @return the display start time for the subtitle
|
|
*/
|
|
public long getStartTimeUs() {
|
|
return mStartTimeUs;
|
|
}
|
|
|
|
/**
|
|
* Returns the duration in microsecond during which the subtitle should be displayed.
|
|
* @return the display duration for the subtitle
|
|
*/
|
|
public long getDurationUs() {
|
|
return mDurationUs;
|
|
}
|
|
|
|
/**
|
|
* Returns the encoded data for the subtitle content.
|
|
* Encoding format depends on the subtitle type, refer to
|
|
* <a href="https://en.wikipedia.org/wiki/CEA-708">CEA 708</a>,
|
|
* <a href="https://en.wikipedia.org/wiki/EIA-608">CEA/EIA 608</a> and
|
|
* <a href="https://www.w3.org/TR/webvtt1/">WebVTT</a>, defined by the MIME type
|
|
* of the subtitle track.
|
|
* @return the encoded subtitle data
|
|
*/
|
|
public @NonNull byte[] getData() {
|
|
return mData;
|
|
}
|
|
|
|
private boolean parseParcel(Parcel parcel) {
|
|
parcel.setDataPosition(0);
|
|
if (parcel.dataAvail() == 0) {
|
|
return false;
|
|
}
|
|
|
|
mTrackIndex = parcel.readInt();
|
|
mStartTimeUs = parcel.readLong();
|
|
mDurationUs = parcel.readLong();
|
|
mData = new byte[parcel.readInt()];
|
|
parcel.readByteArray(mData);
|
|
|
|
return true;
|
|
}
|
|
}
|