Merge "Unhide APIs for timed text and multiple audio track switch APIs" into jb-dev

3 files changed, 319 insertions, 247 deletions

diff --git a/media/java/android/media/MediaPlayer.java b/media/java/android/media/MediaPlayer.java
index fae7d0b..33ed081 100644
--- a/media/java/android/media/MediaPlayer.java
+++ b/media/java/android/media/MediaPlayer.java
@@ -462,7 +462,7 @@ import java.lang.ref.WeakReference;
  *     <td>{Prepared, Started, Stopped, Paused, PlaybackCompleted}</p></td>
  *     <td>{Idle, Initialized, Error}</p></td>
  *     <td>Successful invoke of this method does not change the state.</p></td></tr>
- * <tr><td>addExternalSource </p></td>
+ * <tr><td>addTimedTextSource </p></td>
  *     <td>{Prepared, Started, Stopped, Paused, PlaybackCompleted}</p></td>
  *     <td>{Idle, Initialized, Error}</p></td>
  *     <td>Successful invoke of this method does not change the state.</p></td></tr>
@@ -470,7 +470,7 @@ import java.lang.ref.WeakReference;
  *     <td>{Prepared, Started, Stopped, Paused, PlaybackCompleted}</p></td>
  *     <td>{Idle, Initialized, Error}</p></td>
  *     <td>Successful invoke of this method does not change the state.</p></td></tr>
- * <tr><td>disableTrack </p></td>
+ * <tr><td>deselectTrack </p></td>
  *     <td>{Prepared, Started, Stopped, Paused, PlaybackCompleted}</p></td>
  *     <td>{Idle, Initialized, Error}</p></td>
  *     <td>Successful invoke of this method does not change the state.</p></td></tr>
@@ -598,7 +598,7 @@ public class MediaPlayer
     private static final int INVOKE_ID_ADD_EXTERNAL_SOURCE = 2;
     private static final int INVOKE_ID_ADD_EXTERNAL_SOURCE_FD = 3;
     private static final int INVOKE_ID_SELECT_TRACK = 4;
-    private static final int INVOKE_ID_UNSELECT_TRACK = 5;
+    private static final int INVOKE_ID_DESELECT_TRACK = 5;
 
     /**
      * Create a request parcel which can be routed to the native media
@@ -622,7 +622,7 @@ public class MediaPlayer
      * parcels for the request and reply. Both payloads' format is a
      * convention between the java caller and the native player.
      * Must be called after setDataSource to make sure a native player
-     * exists.
+     * exists. On failure, a RuntimeException is thrown.
      *
      * @param request Parcel with the data for the extension. The
      * caller must use {@link #newRequest()} to get one.
@@ -630,13 +630,14 @@ public class MediaPlayer
      * @param reply Output parcel with the data returned by the
      * native player.
      *
-     * @return The status code see utils/Errors.h
      * {@hide}
      */
-    public int invoke(Parcel request, Parcel reply) {
+    public void invoke(Parcel request, Parcel reply) {
         int retcode = native_invoke(request, reply);
         reply.setDataPosition(0);
-        return retcode;
+        if (retcode != 0) {
+            throw new RuntimeException("failure code: " + retcode);
+        }
     }
 
     /**
@@ -1504,8 +1505,7 @@ public class MediaPlayer
     /**
      * Class for MediaPlayer to return each audio/video/subtitle track's metadata.
      *
-     * {@see #getTrackInfo()}.
-     * {@hide}
+     * @see android.media.MediaPlayer#getTrackInfo
      */
     static public class TrackInfo implements Parcelable {
         /**
@@ -1539,17 +1539,16 @@ public class MediaPlayer
             mLanguage = in.readString();
         }
 
-        /*
-         * No special parcel contents. Keep it as hide.
-         * {@hide}
+        /**
+         * {@inheritDoc}
          */
         @Override
         public int describeContents() {
             return 0;
         }
 
-        /*
-         * {@hide}
+        /**
+         * {@inheritDoc}
          */
         @Override
         public void writeToParcel(Parcel dest, int flags) {
@@ -1577,22 +1576,18 @@ public class MediaPlayer
 
     /**
      * Returns an array of track information.
-     * If it is called in an invalid state, IllegalStateException will be thrown.
      *
      * @return Array of track info. The total number of tracks is the array length.
-     * Must be called again if an external source has been added after any of the
-     * addExternalSource methods are called.
-     * {@hide}
+     * Must be called again if an external timed text source has been added after any of the
+     * addTimedTextSource methods are called.
+     * @throws IllegalStateException if it is called in an invalid state.
      */
-    public TrackInfo[] getTrackInfo() {
+    public TrackInfo[] getTrackInfo() throws IllegalStateException {
         Parcel request = Parcel.obtain();
         Parcel reply = Parcel.obtain();
         request.writeInterfaceToken(IMEDIA_PLAYER);
         request.writeInt(INVOKE_ID_GET_TRACK_INFO);
-        int status = invoke(request, reply);
-        if (status != 0) {
-            throw new IllegalStateException();
-        }
+        invoke(request, reply);
         TrackInfo trackInfo[] = reply.createTypedArray(TrackInfo.CREATOR);
         return trackInfo;
     }
@@ -1601,8 +1596,7 @@ public class MediaPlayer
      * in include/media/stagefright/MediaDefs.h and media/libstagefright/MediaDefs.cpp!
      */
     /**
-     * MIME type for SubRip (SRT) container. Used in addExternalSource APIs.
-     * {@hide}
+     * MIME type for SubRip (SRT) container. Used in addTimedTextSource APIs.
      */
     public static final String MEDIA_MIMETYPE_TEXT_SUBRIP = "application/x-subrip";
 
@@ -1619,23 +1613,23 @@ public class MediaPlayer
     /* TODO: Limit the total number of external timed text source to a reasonable number.
      */
     /**
-     * Adds an external source file.
+     * Adds an external timed text source file.
      *
      * Currently supported format is SubRip with the file extension .srt, case insensitive.
-     * Note that a single external source may contain multiple tracks in it.
+     * Note that a single external timed text source may contain multiple tracks in it.
      * One can find the total number of available tracks using {@link #getTrackInfo()} to see what
      * additional tracks become available after this method call.
      *
-     * @param path The file path of external source file.
+     * @param path The file path of external timed text source file.
      * @param mimeType The mime type of the file. Must be one of the mime types listed above.
      * @throws IOException if the file cannot be accessed or is corrupted.
      * @throws IllegalArgumentException if the mimeType is not supported.
-     * {@hide}
+     * @throws IllegalStateException if called in an invalid state.
      */
-    public void addExternalSource(String path, String mimeType)
-            throws IOException, IllegalArgumentException {
+    public void addTimedTextSource(String path, String mimeType)
+            throws IOException, IllegalArgumentException, IllegalStateException {
         if (!availableMimeTypeForExternalSource(mimeType)) {
-            final String msg = "Illegal mimeType for external source: " + mimeType;
+            final String msg = "Illegal mimeType for timed text source: " + mimeType;
             throw new IllegalArgumentException(msg);
         }
 
@@ -1643,7 +1637,7 @@ public class MediaPlayer
         if (file.exists()) {
             FileInputStream is = new FileInputStream(file);
             FileDescriptor fd = is.getFD();
-            addExternalSource(fd, mimeType);
+            addTimedTextSource(fd, mimeType);
             is.close();
         } else {
             // We do not support the case where the path is not a file.
@@ -1652,10 +1646,10 @@ public class MediaPlayer
     }
 
     /**
-     * Adds an external source file (Uri).
+     * Adds an external timed text source file (Uri).
      *
      * Currently supported format is SubRip with the file extension .srt, case insensitive.
-     * Note that a single external source may contain multiple tracks in it.
+     * Note that a single external timed text source may contain multiple tracks in it.
      * One can find the total number of available tracks using {@link #getTrackInfo()} to see what
      * additional tracks become available after this method call.
      *
@@ -1664,13 +1658,13 @@ public class MediaPlayer
      * @param mimeType The mime type of the file. Must be one of the mime types listed above.
      * @throws IOException if the file cannot be accessed or is corrupted.
      * @throws IllegalArgumentException if the mimeType is not supported.
-     * {@hide}
+     * @throws IllegalStateException if called in an invalid state.
      */
-    public void addExternalSource(Context context, Uri uri, String mimeType)
-            throws IOException, IllegalArgumentException {
+    public void addTimedTextSource(Context context, Uri uri, String mimeType)
+            throws IOException, IllegalArgumentException, IllegalStateException {
         String scheme = uri.getScheme();
         if(scheme == null || scheme.equals("file")) {
-            addExternalSource(uri.getPath(), mimeType);
+            addTimedTextSource(uri.getPath(), mimeType);
             return;
         }
 
@@ -1681,7 +1675,7 @@ public class MediaPlayer
             if (fd == null) {
                 return;
             }
-            addExternalSource(fd.getFileDescriptor(), mimeType);
+            addTimedTextSource(fd.getFileDescriptor(), mimeType);
             return;
         } catch (SecurityException ex) {
         } catch (IOException ex) {
@@ -1693,47 +1687,49 @@ public class MediaPlayer
     }
 
     /**
-     * Adds an external source file (FileDescriptor).
+     * Adds an external timed text source file (FileDescriptor).
+     *
      * It is the caller's responsibility to close the file descriptor.
      * It is safe to do so as soon as this call returns.
      *
-     * Currently supported format is SubRip with the file extension .srt, case insensitive.
-     * Note that a single external source may contain multiple tracks in it.
-     * One can find the total number of available tracks using {@link #getTrackInfo()} to see what
-     * additional tracks become available after this method call.
+     * Currently supported format is SubRip. Note that a single external timed text source may
+     * contain multiple tracks in it. One can find the total number of available tracks
+     * using {@link #getTrackInfo()} to see what additional tracks become available
+     * after this method call.
      *
      * @param fd the FileDescriptor for the file you want to play
      * @param mimeType The mime type of the file. Must be one of the mime types listed above.
      * @throws IllegalArgumentException if the mimeType is not supported.
-     * {@hide}
+     * @throws IllegalStateException if called in an invalid state.
      */
-    public void addExternalSource(FileDescriptor fd, String mimeType)
-            throws IllegalArgumentException {
+    public void addTimedTextSource(FileDescriptor fd, String mimeType)
+            throws IllegalArgumentException, IllegalStateException {
         // intentionally less than LONG_MAX
-        addExternalSource(fd, 0, 0x7ffffffffffffffL, mimeType);
+        addTimedTextSource(fd, 0, 0x7ffffffffffffffL, mimeType);
     }
 
     /**
      * Adds an external timed text file (FileDescriptor).
+     *
      * It is the caller's responsibility to close the file descriptor.
      * It is safe to do so as soon as this call returns.
      *
-     * Currently supported format is SubRip with the file extension .srt, case insensitive.
-     * Note that a single external source may contain multiple tracks in it.
-     * One can find the total number of available tracks using {@link #getTrackInfo()} to see what
-     * additional tracks become available after this method call.
+     * Currently supported format is SubRip. Note that a single external timed text source may
+     * contain multiple tracks in it. One can find the total number of available tracks
+     * using {@link #getTrackInfo()} to see what additional tracks become available
+     * after this method call.
      *
      * @param fd the FileDescriptor for the file you want to play
      * @param offset the offset into the file where the data to be played starts, in bytes
      * @param length the length in bytes of the data to be played
      * @param mimeType The mime type of the file. Must be one of the mime types listed above.
      * @throws IllegalArgumentException if the mimeType is not supported.
-     * {@hide}
+     * @throws IllegalStateException if called in an invalid state.
      */
-    public void addExternalSource(FileDescriptor fd, long offset, long length, String mimeType)
-            throws IllegalArgumentException {
+    public void addTimedTextSource(FileDescriptor fd, long offset, long length, String mimeType)
+            throws IllegalArgumentException, IllegalStateException {
         if (!availableMimeTypeForExternalSource(mimeType)) {
-            throw new IllegalArgumentException("Illegal mimeType for external source: " + mimeType);
+            throw new IllegalArgumentException("Illegal mimeType for timed text source: " + mimeType);
         }
 
         Parcel request = Parcel.obtain();
@@ -1771,43 +1767,40 @@ public class MediaPlayer
      * @param index the index of the track to be selected. The valid range of the index
      * is 0..total number of track - 1. The total number of tracks as well as the type of
      * each individual track can be found by calling {@link #getTrackInfo()} method.
-     * @see android.media.MediaPlayer.getTrackInfo
-     * {@hide}
+     * @throws IllegalStateException if called in an invalid state.
+     *
+     * @see android.media.MediaPlayer#getTrackInfo
      */
-    public void selectTrack(int index) {
-        selectOrUnselectTrack(index, true /* select */);
+    public void selectTrack(int index) throws IllegalStateException {
+        selectOrDeselectTrack(index, true /* select */);
     }
 
     /**
-     * Unselect a track.
+     * Deselect a track.
      * <p>
      * Currently, the track must be a timed text track and no audio or video tracks can be
-     * unselected. If the timed text track identified by index has not been
+     * deselected. If the timed text track identified by index has not been
      * selected before, it throws an exception.
      * </p>
-     * @param index the index of the track to be unselected. The valid range of the index
+     * @param index the index of the track to be deselected. The valid range of the index
      * is 0..total number of tracks - 1. The total number of tracks as well as the type of
      * each individual track can be found by calling {@link #getTrackInfo()} method.
+     * @throws IllegalStateException if called in an invalid state.
      *
-     * @see android.media.MediaPlayer.getTrackInfo
-     * {@hide}
+     * @see android.media.MediaPlayer#getTrackInfo
      */
-    public void unselectTrack(int index) {
-        selectOrUnselectTrack(index, false /* select */);
+    public void deselectTrack(int index) throws IllegalStateException {
+        selectOrDeselectTrack(index, false /* select */);
     }
 
-    private void selectOrUnselectTrack(int index, boolean select) {
+    private void selectOrDeselectTrack(int index, boolean select)
+            throws IllegalStateException {
         Parcel request = Parcel.obtain();
         Parcel reply = Parcel.obtain();
         request.writeInterfaceToken(IMEDIA_PLAYER);
-        request.writeInt(select? INVOKE_ID_SELECT_TRACK: INVOKE_ID_UNSELECT_TRACK);
+        request.writeInt(select? INVOKE_ID_SELECT_TRACK: INVOKE_ID_DESELECT_TRACK);
         request.writeInt(index);
-        int status = invoke(request, reply);
-        if (status != 0) {
-            String msg = select? "selectTrack ": "unselectTrack ";
-            msg += "failed for track index: " + index;
-            throw new RuntimeException(msg);
-        }
+        invoke(request, reply);
     }
 
 
@@ -2142,7 +2135,6 @@ public class MediaPlayer
     /**
      * Interface definition of a callback to be invoked when a
      * timed text is available for display.
-     * {@hide}
      */
     public interface OnTimedTextListener
     {
@@ -2152,7 +2144,6 @@ public class MediaPlayer
          * @param mp             the MediaPlayer associated with this callback
          * @param text           the timed text sample which contains the text
          *                       needed to be displayed and the display format.
-         * {@hide}
          */
         public void onTimedText(MediaPlayer mp, TimedText text);
     }
@@ -2162,7 +2153,6 @@ public class MediaPlayer
      * for display.
      *
      * @param listener the callback that will be run
-     * {@hide}
      */
     public void setOnTimedTextListener(OnTimedTextListener listener)
     {
diff --git a/media/java/android/media/TimedText.java b/media/java/android/media/TimedText.java
index a055c8b..1d7c968 100644
--- a/media/java/android/media/TimedText.java
+++ b/media/java/android/media/TimedText.java
@@ -16,6 +16,7 @@
 
 package android.media;
 
+import android.graphics.Rect;
 import android.os.Parcel;
 import android.util.Log;
 import java.util.HashMap;
@@ -24,31 +25,48 @@ import java.util.List;
 import java.util.ArrayList;
 
 /**
- * Class to hold the timed text's metadata.
+ * Class to hold the timed text's metadata, including:
+ * <ul>
+ * <li> The characters for rendering</li>
+ * <li> The rendering postion for the timed text</li>
+ * </ul>
  *
- * {@hide}
+ * <p> To render the timed text, applications need to do the following:
+ *
+ * <ul>
+ * <li> Implement the {@link MediaPlayer.OnTimedTextListener} interface</li>
+ * <li> Register the {@link MediaPlayer.OnTimedTextListener} callback on a MediaPlayer object that is used for playback</li>
+ * <li> When a onTimedText callback is received, do the following:
+ * <ul>
+ * <li> call {@link #getText} to get the characters for rendering</li>
+ * <li> call {@link #getBounds} to get the text rendering area/region</li>
+ * </ul>
+ * </li>
+ * </ul>
+ *
+ * @see android.media.MediaPlayer
  */
-public class TimedText
+public final class TimedText
 {
     private static final int FIRST_PUBLIC_KEY                 = 1;
 
     // These keys must be in sync with the keys in TextDescription.h
-    public static final int KEY_DISPLAY_FLAGS                 = 1; // int
-    public static final int KEY_STYLE_FLAGS                   = 2; // int
-    public static final int KEY_BACKGROUND_COLOR_RGBA         = 3; // int
-    public static final int KEY_HIGHLIGHT_COLOR_RGBA          = 4; // int
-    public static final int KEY_SCROLL_DELAY                  = 5; // int
-    public static final int KEY_WRAP_TEXT                     = 6; // int
-    public static final int KEY_START_TIME                    = 7; // int
-    public static final int KEY_STRUCT_BLINKING_TEXT_LIST     = 8; // List<CharPos>
-    public static final int KEY_STRUCT_FONT_LIST              = 9; // List<Font>
-    public static final int KEY_STRUCT_HIGHLIGHT_LIST         = 10; // List<CharPos>
-    public static final int KEY_STRUCT_HYPER_TEXT_LIST        = 11; // List<HyperText>
-    public static final int KEY_STRUCT_KARAOKE_LIST           = 12; // List<Karaoke>
-    public static final int KEY_STRUCT_STYLE_LIST             = 13; // List<Style>
-    public static final int KEY_STRUCT_TEXT_POS               = 14; // TextPos
-    public static final int KEY_STRUCT_JUSTIFICATION          = 15; // Justification
-    public static final int KEY_STRUCT_TEXT                   = 16; // Text
+    private static final int KEY_DISPLAY_FLAGS                 = 1; // int
+    private static final int KEY_STYLE_FLAGS                   = 2; // int
+    private static final int KEY_BACKGROUND_COLOR_RGBA         = 3; // int
+    private static final int KEY_HIGHLIGHT_COLOR_RGBA          = 4; // int
+    private static final int KEY_SCROLL_DELAY                  = 5; // int
+    private static final int KEY_WRAP_TEXT                     = 6; // int
+    private static final int KEY_START_TIME                    = 7; // int
+    private static final int KEY_STRUCT_BLINKING_TEXT_LIST     = 8; // List<CharPos>
+    private static final int KEY_STRUCT_FONT_LIST              = 9; // List<Font>
+    private static final int KEY_STRUCT_HIGHLIGHT_LIST         = 10; // List<CharPos>
+    private static final int KEY_STRUCT_HYPER_TEXT_LIST        = 11; // List<HyperText>
+    private static final int KEY_STRUCT_KARAOKE_LIST           = 12; // List<Karaoke>
+    private static final int KEY_STRUCT_STYLE_LIST             = 13; // List<Style>
+    private static final int KEY_STRUCT_TEXT_POS               = 14; // TextPos
+    private static final int KEY_STRUCT_JUSTIFICATION          = 15; // Justification
+    private static final int KEY_STRUCT_TEXT                   = 16; // Text
 
     private static final int LAST_PUBLIC_KEY                  = 16;
 
@@ -85,219 +103,252 @@ public class TimedText
     private List<Style> mStyleList = null;
     private List<HyperText> mHyperTextList = null;
 
-    private TextPos mTextPos;
-    private Justification mJustification;
-    private Text mTextStruct;
-
-    /**
-     * Helper class to hold the text length and text content of
-     * one text sample. The member variables in this class are
-     * read-only.
-     */
-    public class Text {
-        /**
-         * The byte-count of this text sample
-         */
-        public int textLen;
-
-        /**
-         * The text sample
-         */
-        public byte[] text;
+    private Rect mTextBounds = null;
+    private String mTextChars = null;
 
-        public Text() { }
-    }
+    private Justification mJustification;
 
     /**
      * Helper class to hold the start char offset and end char offset
      * for Blinking Text or Highlight Text. endChar is the end offset
      * of the text (startChar + number of characters to be highlighted
      * or blinked). The member variables in this class are read-only.
+     * {@hide}
      */
-    public class CharPos {
+    public static final class CharPos {
         /**
          * The offset of the start character
          */
-        public int startChar = -1;
+        public final int startChar;
 
         /**
          * The offset of the end character
          */
-        public int endChar = -1;
-
-        public CharPos() { }
-    }
+        public final int endChar;
 
-    /**
-     * Helper class to hold the box position to display the text sample.
-     * The member variables in this class are read-only.
-     */
-    public class TextPos {
         /**
-         * The top position of the text
+         * Constuctor
+         * @param startChar the offset of the start character.
+         * @param endChar the offset of the end character.
          */
-        public int top = -1;
-
-        /**
-         * The left position of the text
-         */
-        public int left = -1;
-
-        /**
-         * The bottom position of the text
-         */
-        public int bottom = -1;
-
-        /**
-         * The right position of the text
-         */
-        public int right = -1;
-
-        public TextPos() { }
+        public CharPos(int startChar, int endChar) {
+            this.startChar = startChar;
+            this.endChar = endChar;
+        }
     }
 
     /**
      * Helper class to hold the justification for text display in the text box.
      * The member variables in this class are read-only.
+     * {@hide}
      */
-    public class Justification {
+    public static final class Justification {
         /**
-         * horizontalJustification  0: left, 1: centered, -1: right
+         * horizontal justification  0: left, 1: centered, -1: right
          */
-        public int horizontalJustification = -1;
+        public final int horizontalJustification;
 
         /**
-         * verticalJustification  0: top, 1: centered, -1: bottom
+         * vertical justification  0: top, 1: centered, -1: bottom
          */
-        public int verticalJustification = -1;
+        public final int verticalJustification;
 
-        public Justification() { }
+        /**
+         * Constructor
+         * @param horizontal the horizontal justification of the text.
+         * @param vertical the vertical justification of the text.
+         */
+        public Justification(int horizontal, int vertical) {
+            this.horizontalJustification = horizontal;
+            this.verticalJustification = vertical;
+        }
     }
 
     /**
      * Helper class to hold the style information to display the text.
      * The member variables in this class are read-only.
+     * {@hide}
      */
-    public class Style {
+    public static final class Style {
         /**
          * The offset of the start character which applys this style
          */
-        public int startChar = -1;
+        public final int startChar;
 
         /**
          * The offset of the end character which applys this style
          */
-        public int endChar = -1;
+        public final int endChar;
 
         /**
          * ID of the font. This ID will be used to choose the font
          * to be used from the font list.
          */
-        public int fontID = -1;
+        public final int fontID;
 
         /**
          * True if the characters should be bold
          */
-        public boolean isBold = false;
+        public final boolean isBold;
 
         /**
          * True if the characters should be italic
          */
-        public boolean isItalic = false;
+        public final boolean isItalic;
 
         /**
          * True if the characters should be underlined
          */
-        public boolean isUnderlined = false;
+        public final boolean isUnderlined;
 
         /**
          * The size of the font
          */
-        public int fontSize = -1;
+        public final int fontSize;
 
         /**
          * To specify the RGBA color: 8 bits each of red, green, blue,
          * and an alpha(transparency) value
          */
-        public int colorRGBA = -1;
+        public final int colorRGBA;
 
-        public Style() { }
+        /**
+         * Constructor
+         * @param startChar the offset of the start character which applys this style
+         * @param endChar the offset of the end character which applys this style
+         * @param fontId the ID of the font.
+         * @param isBold whether the characters should be bold.
+         * @param isItalic whether the characters should be italic.
+         * @param isUnderlined whether the characters should be underlined.
+         * @param fontSize the size of the font.
+         * @param colorRGBA red, green, blue, and alpha value for color.
+         */
+        public Style(int startChar, int endChar, int fontId,
+                     boolean isBold, boolean isItalic, boolean isUnderlined,
+                     int fontSize, int colorRGBA) {
+            this.startChar = startChar;
+            this.endChar = endChar;
+            this.fontID = fontId;
+            this.isBold = isBold;
+            this.isItalic = isItalic;
+            this.isUnderlined = isUnderlined;
+            this.fontSize = fontSize;
+            this.colorRGBA = colorRGBA;
+        }
     }
 
     /**
      * Helper class to hold the font ID and name.
      * The member variables in this class are read-only.
+     * {@hide}
      */
-    public class Font {
+    public static final class Font {
         /**
          * The font ID
          */
-        public int ID = -1;
+        public final int ID;
 
         /**
          * The font name
          */
-        public String name;
+        public final String name;
 
-        public Font() { }
+        /**
+         * Constructor
+         * @param id the font ID.
+         * @param name the font name.
+         */
+        public Font(int id, String name) {
+            this.ID = id;
+            this.name = name;
+        }
     }
 
     /**
      * Helper class to hold the karaoke information.
      * The member variables in this class are read-only.
+     * {@hide}
      */
-    public class Karaoke {
+    public static final class Karaoke {
         /**
          * The start time (in milliseconds) to highlight the characters
          * specified by startChar and endChar.
          */
-        public int startTimeMs = -1;
+        public final int startTimeMs;
 
         /**
          * The end time (in milliseconds) to highlight the characters
          * specified by startChar and endChar.
          */
-        public int endTimeMs = -1;
+        public final int endTimeMs;
 
         /**
          * The offset of the start character to be highlighted
          */
-        public int startChar = -1;
+        public final int startChar;
 
         /**
          * The offset of the end character to be highlighted
          */
-        public int endChar = -1;
+        public final int endChar;
 
-        public Karaoke() { }
+        /**
+         * Constructor
+         * @param startTimeMs the start time (in milliseconds) to highlight
+         * the characters between startChar and endChar.
+         * @param endTimeMs the end time (in milliseconds) to highlight
+         * the characters between startChar and endChar.
+         * @param startChar the offset of the start character to be highlighted.
+         * @param endChar the offset of the end character to be highlighted.
+         */
+        public Karaoke(int startTimeMs, int endTimeMs, int startChar, int endChar) {
+            this.startTimeMs = startTimeMs;
+            this.endTimeMs = endTimeMs;
+            this.startChar = startChar;
+            this.endChar = endChar;
+        }
     }
 
     /**
      * Helper class to hold the hyper text information.
      * The member variables in this class are read-only.
+     * {@hide}
      */
-    public class HyperText {
+    public static final class HyperText {
         /**
          * The offset of the start character
          */
-        public int startChar = -1;
+        public final int startChar;
 
         /**
          * The offset of the end character
          */
-        public int endChar = -1;
+        public final int endChar;
 
         /**
          * The linked-to URL
          */
-        public String URL;
+        public final String URL;
 
         /**
          * The "alt" string for user display
          */
-        public String altString;
+        public final String altString;
+
 
-        public HyperText() { }
+        /**
+         * Constructor
+         * @param startChar the offset of the start character.
+         * @param endChar the offset of the end character.
+         * @param url the linked-to URL.
+         * @param alt the "alt" string for display.
+         */
+        public HyperText(int startChar, int endChar, String url, String alt) {
+            this.startChar = startChar;
+            this.endChar = endChar;
+            this.URL = url;
+            this.altString = alt;
+        }
     }
 
     /**
@@ -315,6 +366,29 @@ public class TimedText
     }
 
     /**
+     * Get the characters in the timed text.
+     *
+     * @return the characters as a String object in the TimedText. Applications
+     * should stop rendering previous timed text at the current rendering region if
+     * a null is returned, until the next non-null timed text is received.
+     */
+    public String getText() {
+        return mTextChars;
+    }
+
+    /**
+     * Get the rectangle area or region for rendering the timed text as specified
+     * by a Rect object.
+     *
+     * @return the rectangle region to render the characters in the timed text.
+     * If no bounds information is available (a null is returned), render the
+     * timed text at the center bottom of the display.
+     */
+    public Rect getBounds() {
+        return mTextBounds;
+    }
+
+    /*
      * Go over all the records, collecting metadata keys and fields in the
      * Parcel. These are stored in mKeyObjectMap for application to retrieve.
      * @return false if an error occurred during parsing. Otherwise, true.
@@ -339,11 +413,13 @@ public class TimedText
                 return false;
             }
 
-            mTextStruct = new Text();
-            mTextStruct.textLen = mParcel.readInt();
-
-            mTextStruct.text = mParcel.createByteArray();
-            mKeyObjectMap.put(type, mTextStruct);
+            int textLen = mParcel.readInt();
+            byte[] text = mParcel.createByteArray();
+            if (text == null || text.length == 0) {
+                mTextChars = null;
+            } else {
+                mTextChars = new String(text);
+            }
 
         } else if (type != KEY_GLOBAL_SETTING) {
             Log.w(TAG, "Invalid timed text key found: " + type);
@@ -408,10 +484,10 @@ public class TimedText
                     break;
                 }
                 case KEY_STRUCT_JUSTIFICATION: {
-                    mJustification = new Justification();
 
-                    mJustification.horizontalJustification = mParcel.readInt();
-                    mJustification.verticalJustification = mParcel.readInt();
+                    int horizontal = mParcel.readInt();
+                    int vertical = mParcel.readInt();
+                    mJustification = new Justification(horizontal, vertical);
 
                     object = mJustification;
                     break;
@@ -422,14 +498,12 @@ public class TimedText
                     break;
                 }
                 case KEY_STRUCT_TEXT_POS: {
-                    mTextPos = new TextPos();
+                    int top = mParcel.readInt();
+                    int left = mParcel.readInt();
+                    int bottom = mParcel.readInt();
+                    int right = mParcel.readInt();
+                    mTextBounds = new Rect(left, top, right, bottom);
 
-                    mTextPos.top = mParcel.readInt();
-                    mTextPos.left = mParcel.readInt();
-                    mTextPos.bottom = mParcel.readInt();
-                    mTextPos.right = mParcel.readInt();
-
-                    object = mTextPos;
                     break;
                 }
                 case KEY_SCROLL_DELAY: {
@@ -454,43 +528,49 @@ public class TimedText
         return true;
     }
 
-    /**
+    /*
      * To parse and store the Style list.
      */
     private void readStyle() {
-        Style style = new Style();
         boolean endOfStyle = false;
-
+        int startChar = -1;
+        int endChar = -1;
+        int fontId = -1;
+        boolean isBold = false;
+        boolean isItalic = false;
+        boolean isUnderlined = false;
+        int fontSize = -1;
+        int colorRGBA = -1;
         while (!endOfStyle && (mParcel.dataAvail() > 0)) {
             int key = mParcel.readInt();
             switch (key) {
                 case KEY_START_CHAR: {
-                    style.startChar = mParcel.readInt();
+                    startChar = mParcel.readInt();
                     break;
                 }
                 case KEY_END_CHAR: {
-                    style.endChar = mParcel.readInt();
+                    endChar = mParcel.readInt();
                     break;
                 }
                 case KEY_FONT_ID: {
-                    style.fontID = mParcel.readInt();
+                    fontId = mParcel.readInt();
                     break;
                 }
                 case KEY_STYLE_FLAGS: {
                     int flags = mParcel.readInt();
                     // In the absence of any bits set in flags, the text
                     // is plain. Otherwise, 1: bold, 2: italic, 4: underline
-                    style.isBold = ((flags % 2) == 1);
-                    style.isItalic = ((flags % 4) >= 2);
-                    style.isUnderlined = ((flags / 4) == 1);
+                    isBold = ((flags % 2) == 1);
+                    isItalic = ((flags % 4) >= 2);
+                    isUnderlined = ((flags / 4) == 1);
                     break;
                 }
                 case KEY_FONT_SIZE: {
-                    style.fontSize = mParcel.readInt();
+                    fontSize = mParcel.readInt();
                     break;
                 }
                 case KEY_TEXT_COLOR_RGBA: {
-                    style.colorRGBA = mParcel.readInt();
+                    colorRGBA = mParcel.readInt();
                     break;
                 }
                 default: {
@@ -503,26 +583,28 @@ public class TimedText
             }
         }
 
+        Style style = new Style(startChar, endChar, fontId, isBold,
+                                isItalic, isUnderlined, fontSize, colorRGBA);
         if (mStyleList == null) {
             mStyleList = new ArrayList<Style>();
         }
         mStyleList.add(style);
     }
 
-    /**
+    /*
      * To parse and store the Font list
      */
     private void readFont() {
         int entryCount = mParcel.readInt();
 
         for (int i = 0; i < entryCount; i++) {
-            Font font = new Font();
-
-            font.ID = mParcel.readInt();
+            int id = mParcel.readInt();
             int nameLen = mParcel.readInt();
 
             byte[] text = mParcel.createByteArray();
-            font.name = new String(text, 0, nameLen);
+            final String name = new String(text, 0, nameLen);
+
+            Font font = new Font(id, name);
 
             if (mFontList == null) {
                 mFontList = new ArrayList<Font>();
@@ -531,14 +613,13 @@ public class TimedText
         }
     }
 
-    /**
+    /*
      * To parse and store the Highlight list
      */
     private void readHighlight() {
-        CharPos pos = new CharPos();
-
-        pos.startChar = mParcel.readInt();
-        pos.endChar = mParcel.readInt();
+        int startChar = mParcel.readInt();
+        int endChar = mParcel.readInt();
+        CharPos pos = new CharPos(startChar, endChar);
 
         if (mHighlightPosList == null) {
             mHighlightPosList = new ArrayList<CharPos>();
@@ -546,19 +627,19 @@ public class TimedText
         mHighlightPosList.add(pos);
     }
 
-    /**
+    /*
      * To parse and store the Karaoke list
      */
     private void readKaraoke() {
         int entryCount = mParcel.readInt();
 
         for (int i = 0; i < entryCount; i++) {
-            Karaoke kara = new Karaoke();
-
-            kara.startTimeMs = mParcel.readInt();
-            kara.endTimeMs = mParcel.readInt();
-            kara.startChar = mParcel.readInt();
-            kara.endChar = mParcel.readInt();
+            int startTimeMs = mParcel.readInt();
+            int endTimeMs = mParcel.readInt();
+            int startChar = mParcel.readInt();
+            int endChar = mParcel.readInt();
+            Karaoke kara = new Karaoke(startTimeMs, endTimeMs,
+                                       startChar, endChar);
 
             if (mKaraokeList == null) {
                 mKaraokeList = new ArrayList<Karaoke>();
@@ -567,22 +648,22 @@ public class TimedText
         }
     }
 
-    /**
+    /*
      * To parse and store HyperText list
      */
     private void readHyperText() {
-        HyperText hyperText = new HyperText();
-
-        hyperText.startChar = mParcel.readInt();
-        hyperText.endChar = mParcel.readInt();
+        int startChar = mParcel.readInt();
+        int endChar = mParcel.readInt();
 
         int len = mParcel.readInt();
         byte[] url = mParcel.createByteArray();
-        hyperText.URL = new String(url, 0, len);
+        final String urlString = new String(url, 0, len);
 
         len = mParcel.readInt();
         byte[] alt = mParcel.createByteArray();
-        hyperText.altString = new String(alt, 0, len);
+        final String altString = new String(alt, 0, len);
+        HyperText hyperText = new HyperText(startChar, endChar, urlString, altString);
+
 
         if (mHyperTextList == null) {
             mHyperTextList = new ArrayList<HyperText>();
@@ -590,14 +671,13 @@ public class TimedText
         mHyperTextList.add(hyperText);
     }
 
-    /**
+    /*
      * To parse and store blinking text list
      */
     private void readBlinkingText() {
-        CharPos blinkingPos = new CharPos();
-
-        blinkingPos.startChar = mParcel.readInt();
-        blinkingPos.endChar = mParcel.readInt();
+        int startChar = mParcel.readInt();
+        int endChar = mParcel.readInt();
+        CharPos blinkingPos = new CharPos(startChar, endChar);
 
         if (mBlinkingPosList == null) {
             mBlinkingPosList = new ArrayList<CharPos>();
@@ -605,12 +685,12 @@ public class TimedText
         mBlinkingPosList.add(blinkingPos);
     }
 
-    /**
+    /*
      * To check whether the given key is valid.
      * @param key the key to be checked.
      * @return true if the key is a valid one. Otherwise, false.
      */
-    public boolean isValidKey(final int key) {
+    private boolean isValidKey(final int key) {
         if (!((key >= FIRST_PUBLIC_KEY) && (key <= LAST_PUBLIC_KEY))
                 && !((key >= FIRST_PRIVATE_KEY) && (key <= LAST_PRIVATE_KEY))) {
             return false;
@@ -618,34 +698,36 @@ public class TimedText
         return true;
     }
 
-    /**
+    /*
      * To check whether the given key is contained in this TimedText object.
      * @param key the key to be checked.
      * @return true if the key is contained in this TimedText object.
      *         Otherwise, false.
      */
-    public boolean containsKey(final int key) {
+    private boolean containsKey(final int key) {
         if (isValidKey(key) && mKeyObjectMap.containsKey(key)) {
             return true;
         }
         return false;
     }
-    /**
+
+    /*
      * @return a set of the keys contained in this TimedText object.
      */
-    public Set keySet() {
+    private Set keySet() {
         return mKeyObjectMap.keySet();
     }
 
-    /**
+    /*
      * To retrieve the object associated with the key. Caller must make sure
      * the key is present using the containsKey method otherwise a
      * RuntimeException will occur.
      * @param key the key used to retrieve the object.
-     * @return an object. The object could be an instanceof Integer, List, or
-     * any of the helper classes such as TextPos, Justification, and Text.
+     * @return an object. The object could be 1) an instance of Integer; 2) a
+     * List of CharPos, Karaoke, Font, Style, and HyperText, or 3) an instance of
+     * Justification.
      */
-    public Object getObject(final int key) {
+    private Object getObject(final int key) {
         if (containsKey(key)) {
             return mKeyObjectMap.get(key);
         } else {
diff --git a/media/tests/MediaFrameworkTest/src/com/android/mediaframeworktest/functional/MediaPlayerInvokeTest.java b/media/tests/MediaFrameworkTest/src/com/android/mediaframeworktest/functional/MediaPlayerInvokeTest.java
index 0b96bae..55a1545 100644
--- a/media/tests/MediaFrameworkTest/src/com/android/mediaframeworktest/functional/MediaPlayerInvokeTest.java
+++ b/media/tests/MediaFrameworkTest/src/com/android/mediaframeworktest/functional/MediaPlayerInvokeTest.java
@@ -65,7 +65,7 @@ public class MediaPlayerInvokeTest extends ActivityInstrumentationTestCase2<Medi
 
         int val = rnd.nextInt();
         request.writeInt(val);
-        assertEquals(0, mPlayer.invoke(request, reply));
+        mPlayer.invoke(request, reply);
         assertEquals(val, reply.readInt());
    }
 }