From 3d04b7693428dd887c93e2ac7f4e90fd0cc87859 Mon Sep 17 00:00:00 2001
From: Jae Seo <jaeseo@google.com>
Date: Tue, 12 May 2015 20:05:00 -0700
Subject: [PATCH] TIF: API Review: android.media.tv

Addressed the feedback from the API Review:

android.media.tv.TvView.TimeShiftPositionCallback
Please add more documentation to explain why we are using the wall-clock
time here.

android.media.tv.TvInputService
onTimeShiftSetPlaybackRate should be renamed to
onTimeShiftSetPlaybackParams and pass in the PlaybackParams object
(formerly known as PlaybackSettings) instead of the rate and mode
separately.

android.media.tv.TvTrackInfo
getDescription() should return a CharSequence not a String.

android.media.tv.TvTrackInfo.Builder
setDescription() should take a CharSequence as input.

android.media.tv.TvView
Change timeShiftSetPlaybackRate() to setTimeShiftPlaybackParams() and
use the PlaybackParams object (formerly known as PlaybackSettings)
instead of the rate and mode separately.

Bug: 21045120
Change-Id: I768665ae9c385fcb034bfb346c21b4c9f0891172
---
 api/current.txt                               |  8 ++--
 api/system-current.txt                        |  8 ++--
 .../media/tv/ITvInputSessionWrapper.java      |  6 ++-
 .../java/android/media/tv/TvInputService.java | 37 +++++++++----------
 media/java/android/media/tv/TvTrackInfo.java  | 12 +++---
 media/java/android/media/tv/TvView.java       | 22 ++++++-----
 6 files changed, 48 insertions(+), 45 deletions(-)

diff --git a/api/current.txt b/api/current.txt
index 3ea8b67ba9dfe..a7df2a1c9079d 100644
--- a/api/current.txt
+++ b/api/current.txt
@@ -17852,7 +17852,7 @@ package android.media.tv {
     method public void onTimeShiftPause();
     method public void onTimeShiftResume();
     method public void onTimeShiftSeekTo(long);
-    method public void onTimeShiftSetPlaybackRate(float, int);
+    method public void onTimeShiftSetPlaybackParams(android.media.PlaybackParams);
     method public boolean onTouchEvent(android.view.MotionEvent);
     method public boolean onTrackballEvent(android.view.MotionEvent);
     method public abstract boolean onTune(android.net.Uri);
@@ -17864,7 +17864,7 @@ package android.media.tv {
     method public int describeContents();
     method public final int getAudioChannelCount();
     method public final int getAudioSampleRate();
-    method public final java.lang.String getDescription();
+    method public final java.lang.CharSequence getDescription();
     method public final android.os.Bundle getExtra();
     method public final java.lang.String getId();
     method public final java.lang.String getLanguage();
@@ -17885,7 +17885,7 @@ package android.media.tv {
     method public android.media.tv.TvTrackInfo build();
     method public final android.media.tv.TvTrackInfo.Builder setAudioChannelCount(int);
     method public final android.media.tv.TvTrackInfo.Builder setAudioSampleRate(int);
-    method public final android.media.tv.TvTrackInfo.Builder setDescription(java.lang.String);
+    method public final android.media.tv.TvTrackInfo.Builder setDescription(java.lang.CharSequence);
     method public final android.media.tv.TvTrackInfo.Builder setExtra(android.os.Bundle);
     method public final android.media.tv.TvTrackInfo.Builder setLanguage(java.lang.String);
     method public final android.media.tv.TvTrackInfo.Builder setVideoFrameRate(float);
@@ -17913,7 +17913,7 @@ package android.media.tv {
     method public void timeShiftPause();
     method public void timeShiftResume();
     method public void timeShiftSeekTo(long);
-    method public void timeShiftSetPlaybackRate(float, int);
+    method public void timeShiftSetPlaybackParams(android.media.PlaybackParams);
     method public void tune(java.lang.String, android.net.Uri);
   }
 
diff --git a/api/system-current.txt b/api/system-current.txt
index 6c51cbaf8188b..328d6948fd203 100644
--- a/api/system-current.txt
+++ b/api/system-current.txt
@@ -19298,7 +19298,7 @@ package android.media.tv {
     method public void onTimeShiftPause();
     method public void onTimeShiftResume();
     method public void onTimeShiftSeekTo(long);
-    method public void onTimeShiftSetPlaybackRate(float, int);
+    method public void onTimeShiftSetPlaybackParams(android.media.PlaybackParams);
     method public boolean onTouchEvent(android.view.MotionEvent);
     method public boolean onTrackballEvent(android.view.MotionEvent);
     method public abstract boolean onTune(android.net.Uri);
@@ -19334,7 +19334,7 @@ package android.media.tv {
     method public int describeContents();
     method public final int getAudioChannelCount();
     method public final int getAudioSampleRate();
-    method public final java.lang.String getDescription();
+    method public final java.lang.CharSequence getDescription();
     method public final android.os.Bundle getExtra();
     method public final java.lang.String getId();
     method public final java.lang.String getLanguage();
@@ -19355,7 +19355,7 @@ package android.media.tv {
     method public android.media.tv.TvTrackInfo build();
     method public final android.media.tv.TvTrackInfo.Builder setAudioChannelCount(int);
     method public final android.media.tv.TvTrackInfo.Builder setAudioSampleRate(int);
-    method public final android.media.tv.TvTrackInfo.Builder setDescription(java.lang.String);
+    method public final android.media.tv.TvTrackInfo.Builder setDescription(java.lang.CharSequence);
     method public final android.media.tv.TvTrackInfo.Builder setExtra(android.os.Bundle);
     method public final android.media.tv.TvTrackInfo.Builder setLanguage(java.lang.String);
     method public final android.media.tv.TvTrackInfo.Builder setVideoFrameRate(float);
@@ -19388,7 +19388,7 @@ package android.media.tv {
     method public void timeShiftPause();
     method public void timeShiftResume();
     method public void timeShiftSeekTo(long);
-    method public void timeShiftSetPlaybackRate(float, int);
+    method public void timeShiftSetPlaybackParams(android.media.PlaybackParams);
     method public void tune(java.lang.String, android.net.Uri);
     method public void tune(java.lang.String, android.net.Uri, android.os.Bundle);
     method public void unblockContent(android.media.tv.TvContentRating);
diff --git a/media/java/android/media/tv/ITvInputSessionWrapper.java b/media/java/android/media/tv/ITvInputSessionWrapper.java
index 019165243d854..58954bd3a9e33 100644
--- a/media/java/android/media/tv/ITvInputSessionWrapper.java
+++ b/media/java/android/media/tv/ITvInputSessionWrapper.java
@@ -18,6 +18,7 @@ package android.media.tv;
 
 import android.content.Context;
 import android.graphics.Rect;
+import android.media.PlaybackParams;
 import android.net.Uri;
 import android.os.Bundle;
 import android.os.IBinder;
@@ -172,7 +173,10 @@ public class ITvInputSessionWrapper extends ITvInputSession.Stub implements Hand
                 break;
             }
             case DO_TIME_SHIFT_SET_PLAYBACK_RATE: {
-                mTvInputSessionImpl.timeShiftSetPlaybackRate((Float) msg.obj, msg.arg1);
+                PlaybackParams params = new PlaybackParams()
+                        .setSpeed((Float) msg.obj)
+                        .setAudioFallbackMode(msg.arg1);
+                mTvInputSessionImpl.timeShiftSetPlaybackParams(params);
                 break;
             }
             case DO_TIME_SHIFT_ENABLE_POSITION_TRACKING: {
diff --git a/media/java/android/media/tv/TvInputService.java b/media/java/android/media/tv/TvInputService.java
index 8b0472a95a2c1..4b84090861cdf 100644
--- a/media/java/android/media/tv/TvInputService.java
+++ b/media/java/android/media/tv/TvInputService.java
@@ -26,6 +26,8 @@ import android.content.Intent;
 import android.graphics.PixelFormat;
 import android.graphics.Rect;
 import android.hardware.hdmi.HdmiDeviceInfo;
+import android.media.PlaybackParams;
+import android.media.tv.TvInputService.HardwareSession;
 import android.net.Uri;
 import android.os.AsyncTask;
 import android.os.Bundle;
@@ -586,7 +588,7 @@ public abstract class TvInputService extends Service {
          * set playback rate and audio mode. The implementation should override
          * {@link #onTimeShiftPause}, {@link #onTimeShiftResume}, {@link #onTimeShiftSeekTo},
          * {@link #onTimeShiftGetStartPosition}, {@link #onTimeShiftGetCurrentPosition} and
-         * {@link #onTimeShiftSetPlaybackRate}.
+         * {@link #onTimeShiftSetPlaybackParams}.
          *
          * @param status The current time shift status. Should be one of the followings.
          * <ul>
@@ -853,7 +855,7 @@ public abstract class TvInputService extends Service {
          *
          * @see #onTimeShiftResume
          * @see #onTimeShiftSeekTo
-         * @see #onTimeShiftSetPlaybackRate
+         * @see #onTimeShiftSetPlaybackParams
          * @see #onTimeShiftGetStartPosition
          * @see #onTimeShiftGetCurrentPosition
          */
@@ -865,7 +867,7 @@ public abstract class TvInputService extends Service {
          *
          * @see #onTimeShiftPause
          * @see #onTimeShiftSeekTo
-         * @see #onTimeShiftSetPlaybackRate
+         * @see #onTimeShiftSetPlaybackParams
          * @see #onTimeShiftGetStartPosition
          * @see #onTimeShiftGetCurrentPosition
          */
@@ -881,7 +883,7 @@ public abstract class TvInputService extends Service {
          * @param timeMs The time position to seek to, in milliseconds since the epoch.
          * @see #onTimeShiftResume
          * @see #onTimeShiftPause
-         * @see #onTimeShiftSetPlaybackRate
+         * @see #onTimeShiftSetPlaybackParams
          * @see #onTimeShiftGetStartPosition
          * @see #onTimeShiftGetCurrentPosition
          */
@@ -889,25 +891,20 @@ public abstract class TvInputService extends Service {
         }
 
         /**
-         * Called when the application sets playback rate and audio mode.
+         * Called when the application sets playback parameters containing the speed and audio mode.
          *
-         * <p>Once a playback rate is set, the implementation should honor the value until a new
-         * tune request. Pause/resume/seek request does not reset the playback rate previously set.
+         * <p>Once the playback parameters are set, the implementation should honor the current
+         * settings until the next tune request. Pause/resume/seek request does not reset the
+         * parameters previously set.
          *
-         * @param rate The ratio between desired playback rate and normal one.
-         * @param audioMode Audio playback mode. Must be one of the supported audio modes:
-         * <ul>
-         * <li> {@link android.media.MediaPlayer#PLAYBACK_RATE_AUDIO_MODE_DEFAULT}
-         * <li> {@link android.media.MediaPlayer#PLAYBACK_RATE_AUDIO_MODE_STRETCH}
-         * <li> {@link android.media.MediaPlayer#PLAYBACK_RATE_AUDIO_MODE_RESAMPLE}
-         * </ul>
+         * @param params The playback params.
          * @see #onTimeShiftResume
          * @see #onTimeShiftPause
          * @see #onTimeShiftSeekTo
          * @see #onTimeShiftGetStartPosition
          * @see #onTimeShiftGetCurrentPosition
          */
-        public void onTimeShiftSetPlaybackRate(float rate, int audioMode) {
+        public void onTimeShiftSetPlaybackParams(PlaybackParams params) {
         }
 
         /**
@@ -924,7 +921,7 @@ public abstract class TvInputService extends Service {
          * @see #onTimeShiftResume
          * @see #onTimeShiftPause
          * @see #onTimeShiftSeekTo
-         * @see #onTimeShiftSetPlaybackRate
+         * @see #onTimeShiftSetPlaybackParams
          * @see #onTimeShiftGetCurrentPosition
          */
         public long onTimeShiftGetStartPosition() {
@@ -939,7 +936,7 @@ public abstract class TvInputService extends Service {
          * @see #onTimeShiftResume
          * @see #onTimeShiftPause
          * @see #onTimeShiftSeekTo
-         * @see #onTimeShiftSetPlaybackRate
+         * @see #onTimeShiftSetPlaybackParams
          * @see #onTimeShiftGetStartPosition
          */
         public long onTimeShiftGetCurrentPosition() {
@@ -1273,10 +1270,10 @@ public abstract class TvInputService extends Service {
         }
 
         /**
-         * Calls {@link #onTimeShiftSetPlaybackRate}.
+         * Calls {@link #onTimeShiftSetPlaybackParams}.
          */
-        void timeShiftSetPlaybackRate(float rate, int audioMode) {
-            onTimeShiftSetPlaybackRate(rate, audioMode);
+        void timeShiftSetPlaybackParams(PlaybackParams params) {
+            onTimeShiftSetPlaybackParams(params);
         }
 
         /**
diff --git a/media/java/android/media/tv/TvTrackInfo.java b/media/java/android/media/tv/TvTrackInfo.java
index 2c956e9d3e8e3..ed432c463b8ab 100644
--- a/media/java/android/media/tv/TvTrackInfo.java
+++ b/media/java/android/media/tv/TvTrackInfo.java
@@ -45,7 +45,7 @@ public final class TvTrackInfo implements Parcelable {
     private final int mType;
     private final String mId;
     private final String mLanguage;
-    private final String mDescription;
+    private final CharSequence mDescription;
     private final int mAudioChannelCount;
     private final int mAudioSampleRate;
     private final int mVideoWidth;
@@ -54,7 +54,7 @@ public final class TvTrackInfo implements Parcelable {
     private final float mVideoPixelAspectRatio;
     private final Bundle mExtra;
 
-    private TvTrackInfo(int type, String id, String language, String description,
+    private TvTrackInfo(int type, String id, String language, CharSequence description,
             int audioChannelCount, int audioSampleRate, int videoWidth, int videoHeight,
             float videoFrameRate, float videoPixelAspectRatio, Bundle extra) {
         mType = type;
@@ -110,7 +110,7 @@ public final class TvTrackInfo implements Parcelable {
     /**
      * Returns a user readable description for the current track.
      */
-    public final String getDescription() {
+    public final CharSequence getDescription() {
         return mDescription;
     }
 
@@ -201,7 +201,7 @@ public final class TvTrackInfo implements Parcelable {
         dest.writeInt(mType);
         dest.writeString(mId);
         dest.writeString(mLanguage);
-        dest.writeString(mDescription);
+        dest.writeString(mDescription != null ? mDescription.toString() : null);
         dest.writeInt(mAudioChannelCount);
         dest.writeInt(mAudioSampleRate);
         dest.writeInt(mVideoWidth);
@@ -231,7 +231,7 @@ public final class TvTrackInfo implements Parcelable {
         private final String mId;
         private final int mType;
         private String mLanguage;
-        private String mDescription;
+        private CharSequence mDescription;
         private int mAudioChannelCount;
         private int mAudioSampleRate;
         private int mVideoWidth;
@@ -274,7 +274,7 @@ public final class TvTrackInfo implements Parcelable {
          *
          * @param description The user readable description.
          */
-        public final Builder setDescription(String description) {
+        public final Builder setDescription(CharSequence description) {
             mDescription = description;
             return this;
         }
diff --git a/media/java/android/media/tv/TvView.java b/media/java/android/media/tv/TvView.java
index ebe281ff8fe84..6169eeac52d7c 100644
--- a/media/java/android/media/tv/TvView.java
+++ b/media/java/android/media/tv/TvView.java
@@ -24,9 +24,11 @@ import android.graphics.Canvas;
 import android.graphics.PorterDuff;
 import android.graphics.Rect;
 import android.graphics.Region;
+import android.media.PlaybackParams;
 import android.media.tv.TvInputManager.Session;
 import android.media.tv.TvInputManager.Session.FinishedInputEventCallback;
 import android.media.tv.TvInputManager.SessionCallback;
+import android.media.tv.TvView.TimeShiftPositionCallback;
 import android.net.Uri;
 import android.os.Bundle;
 import android.os.Handler;
@@ -468,19 +470,13 @@ public class TvView extends ViewGroup {
     }
 
     /**
-     * Sets playback rate and audio mode.
+     * Sets playback rate using {@link android.media#PlaybackParams}.
      *
-     * @param rate The ratio between desired playback rate and normal one.
-     * @param audioMode Audio playback mode. Must be one of the supported audio modes:
-     * <ul>
-     * <li> {@link android.media.MediaPlayer#PLAYBACK_RATE_AUDIO_MODE_DEFAULT}
-     * <li> {@link android.media.MediaPlayer#PLAYBACK_RATE_AUDIO_MODE_STRETCH}
-     * <li> {@link android.media.MediaPlayer#PLAYBACK_RATE_AUDIO_MODE_RESAMPLE}
-     * </ul>
+     * @param params The playback params.
      */
-    public void timeShiftSetPlaybackRate(float rate, int audioMode) {
+    public void timeShiftSetPlaybackParams(@NonNull PlaybackParams params) {
         if (mSession != null) {
-            mSession.timeShiftSetPlaybackRate(rate, audioMode);
+            mSession.timeShiftSetPlaybackRate(params.getSpeed(), params.getAudioFallbackMode());
         }
     }
 
@@ -820,6 +816,9 @@ public class TvView extends ViewGroup {
          * limitation on storage space). The application should not allow the user to seek to a
          * position earlier than the start position.
          *
+         * <p>Note that {@code timeMs} is not relative time in the program but wall-clock time,
+         * which is intended to avoid calling this method unnecessarily around program boundaries.
+         *
          * @param inputId The ID of the TV input bound to this view.
          * @param timeMs The start playback position of the time shifted program, in milliseconds
          *            since the epoch.
@@ -830,6 +829,9 @@ public class TvView extends ViewGroup {
         /**
          * This is called when the current playback position is changed.
          *
+         * <p>Note that {@code timeMs} is not relative time in the program but wall-clock time,
+         * which is intended to avoid calling this method unnecessarily around program boundaries.
+         *
          * @param inputId The ID of the TV input bound to this view.
          * @param timeMs The current playback position of the time shifted program, in milliseconds
          *            since the epoch.