Support time-shifting

Use time-shifting APIs in your TV input service to let users pause, rewind, and
fast-forward live programs in your service channels. If your app supports
time-shifting, users gain additional flexibility in how they watch your content,
such as:

Users can pause programs while handling a short-term interruption, ensuring
they never miss key moments.

Time-shifting uses short, temporary, recorded segments of program data to
implement the ability to playback live programs. Users can't play these time-shifting
recordings outside of the current playback session, so they can't use
time-shifting to pause a program to watch the next day, or pause a program to
watch later while they switch to a different channel. Use the TV recording APIs if you want
to let your users record program content to watch outside of the current playback
session.

Add time-shifting support

To add time-shifting support to your TV input service, you need to implement the
time-shifting APIs in your TvInputService.Session class,
handle recording and playback of time-shifting recordings in your app, and notify
the system that your input service provides time-shifting support.

If you’re using the TIF Companion Library to implement your
TvInputService.Session class, you automatically get an
implementation of time-shifting that uses ExoPlayer. You can use this
implementation, or override the time-shifting API methods in
BaseTvInputService.Session and provide your own
implementation. For more information on using the TIF Companion Library, see Create a TV input service using
the TIF Companion Library.

Record content when a session starts

A user can pause, rewind, and fast-forward program content by accessing the
playback controls for the channel (pressing Select while
watching content and then navigating to the playback controls), or by using
dedicated playback controls on a device remote, if available. Because the user can
use time-shifting at any time while watching program content, your TV
input service must begin recording time-shifting content as soon as the user
tunes to a channel in your
onTune()
implementation. At this point you also need to
inform the system that you're capable of recording by calling
notifyTimeShiftStatusChanged(int)
as described in
Notify the system about time-shifting status.

Manage recorded content storage

Your TV input service is responsible for storing time-shifting recordings in
your app’s private app storage, and playing back content when the system calls
your time-shifting methods such as
onTimeShiftResume().
If your content is already stored in the cloud and your app can manage
time-shifting recordings in the cloud, you can use cloud storage instead
of app storage.

If your content uses protected content, your TV input service is responsible for
proper encryption of recorded content and decryption of content during
playback.

Since recorded video content can require a large amount of storage, you need to
carefully manage recorded content during session playback. If the playback
session time exceeds the amount of time you can record and store for
time-shifting, you should adjust your time-shifting recording to maintain the
current buffer but ensure the current time is captured. For example, if the user
has been playing content for 31 minutes and your maximum time-shifting recording
size is 30 minutes, you could adjust your recording and start time to contain
content from minute 1 to minute 31.

If your TV input service is unable to support time-shifting due to lack of
storage, you must inform the system. For more details on how to notify the
system of time-shifting support restrictions, see
Notify the system about time-shifting status.

When a user switches to a different channel or otherwise ends their playback
session, you should delete your recorded time-shifting data.

Track playback times

The start position of a time-shifting recording is the earliest absolute time
position (in milliseconds since the epoch) that the user can seek to. This is
usually the time when the video playback starts after
onTune() is called.
However, in cases where the user watches an amount of content that exceeds what
your app can record, you might have to start recording a new segment for
time-shifting, and you should update your start time accordingly.

The current position of a time-shifting recording is the current playback
position, in milliseconds since the epoch. This position changes continuously
during playback. Typically, you can use your playback engine to determine this
value; for example:

Support playback parameters

To change playback speed during time-shifting, the system uses playback parameters. For
example, if the user decides to rewind the current playback, new playback
parameters are passed to your app with a negative playback speed.
Time-shifting also supports several different levels (2x, 3x) of playback speed
for rewinding or fast-forwarding.

If your playback engine does not support a parameter, you should attempt to
emulate the expected behavior as best you can. For example, if your playback
engine doesn’t support 2x speed, use repeated seek operations on your playback
engine to achieve an approximately double playback speed.

After the parameters are set, don't change the settings unless the user either
issues a playback command that would require a different parameter or switches
to a new channel.