docs: Migrating TV Recording APIs preview docs into DAC
For Android N release, migrating and updating TV Recording API preview docs into regular DAC TV (TIF) docs. Updating training TOC and adding redirect. Removing preview/features doc. Bug: 30224466 Change-Id: Ia92f27467ccaa1d36dc69c5bd3c784509f267791
This commit is contained in:
Daniel Yu
@@ -1210,3 +1210,5 @@ redirects:
|
||||
to: /training/articles/security-config.html
|
||||
- from: /preview/features/picture-in-picture.html
|
||||
to: /training/tv/playback/picture-in-picture.html
|
||||
- from: /preview/features/tv-recording-api.html
|
||||
to: /training/tv/tif/content-recording.html
|
||||
|
||||
@@ -1,142 +0,0 @@
|
||||
page.title=TV Recording
|
||||
page.keywords=preview,sdk,tv,recording
|
||||
page.tags=androidn
|
||||
page.image=images/cards/card-nyc_2x.jpg
|
||||
|
||||
@jd:body
|
||||
|
||||
<div id="qv-wrapper">
|
||||
<div id="qv">
|
||||
<h2>In this document</h2>
|
||||
<ol>
|
||||
<li><a href="#supporting">Indicating Support for Recording</a></li>
|
||||
<li><a href="#recording">Recording a Session</a></li>
|
||||
<li><a href="#errors">Handling Recording Errors</a></li>
|
||||
<li><a href="#sessions">Managing Recorded Sessions</a></li>
|
||||
<li><a href="#best">Best Practices</a></li>
|
||||
</ol>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<p>TV input services let the user pause and resume channel playback via
|
||||
time-shifting APIs. Android N expands on time-shifting
|
||||
by letting the user save multiple recorded sessions.</p>
|
||||
|
||||
<p>Users can schedule recordings in advance, or start a recording as they watch
|
||||
a program. Once the system has saved a recording, the user can browse, manage,
|
||||
and play back the recording using the system TV app.</p>
|
||||
|
||||
<p>If you want to provide recording functionality for your TV input service,
|
||||
you must indicate to the system that your app supports recording, implement
|
||||
the ability to record programs, handle and communicate any errors that occur
|
||||
during recording, and manage your recorded sessions.</p>
|
||||
|
||||
<p class="note"><strong>Note:</strong> The Live Channels app does not yet
|
||||
provide a way for users to create or access recordings. Until changes are
|
||||
made to the Live Channels app, it may be difficult to fully test the recording
|
||||
experience for your TV input service.</p>
|
||||
|
||||
<h2 id="supporting">Indicating Support for Recording</h2>
|
||||
|
||||
<p>To tell the system that your TV input service supports recording, set
|
||||
the <code>android:canRecord</code> attribute in your service metadata XML file
|
||||
to <code>true</code>:
|
||||
</p>
|
||||
|
||||
<pre>
|
||||
<tv-input xmlns:android="http://schemas.android.com/apk/res/android"
|
||||
<b>android:canRecord="true"</b>
|
||||
android:setupActivity="com.example.sampletvinput.SampleTvInputSetupActivity" />
|
||||
</pre>
|
||||
|
||||
<p>For more information on the service metadata file, see
|
||||
<a href="{@docRoot}training/tv/tif/tvinput.html#manifest">Declare Your TV Input
|
||||
Service in the Manifest</a>.
|
||||
</p>
|
||||
|
||||
<p>Alternatively, you can indicate recording support in your code using
|
||||
these steps:</p>
|
||||
|
||||
<ol>
|
||||
<li>In your <code>TvInputService.onCreate()</code> method, create a new
|
||||
<code>TvInputInfo</code> object using the <code>TvInputInfo.Builder</code>
|
||||
class.</li>
|
||||
<li>When creating the new <code>TvInputInfo</code> object, call
|
||||
<code>setCanRecord(true)</code> before calling <code>build()</code> to
|
||||
indicate your service supports recording.</li>
|
||||
<li>Register your <code>TvInputInfo</code> object with the system by calling
|
||||
<code>TvInputManager.updateTvInputInfo()</code>.</li>
|
||||
</ol>
|
||||
|
||||
<h2 id="recording">Recording a Session</h2>
|
||||
|
||||
<p>After your TV input service registers that it supports recording
|
||||
functionality, the system calls your
|
||||
<code>TvInputService.onCreateRecordingSession()</code> when it needs to access
|
||||
your app's recording implementation. Implement your own
|
||||
<code>TvInputService.RecordingSession</code> subclass and return it
|
||||
when the <code>onCreateRecordingSession()</code> callback
|
||||
fires. This subclass is responsible for switching to the correct channel data,
|
||||
recording the requested data, and communicating recording status and errors to
|
||||
the system.</p>
|
||||
|
||||
<p>When the system calls <code>RecordingSession.onTune()</code>, passing in a
|
||||
channel URI, tune to the channel that the URI specifies. Notify the system that
|
||||
your app has tuned to the desired channel by calling <code>notifyTuned()</code>,
|
||||
or, if your app could not tune to the proper channel, call
|
||||
<code>notifyError()</code>.</p>
|
||||
|
||||
<p>The system next invokes the <code>RecordingSession.onStartRecording()</code>
|
||||
callback. Your app must start recording immediately. When the system invokes
|
||||
this callback, it may provide a URI that contains information about the program
|
||||
that is about to be recorded. When the recording is done, you need to copy this
|
||||
data to the <code>RecordedPrograms</code> data table.</p>
|
||||
|
||||
<p>Finally, the system calls <code>RecordingSession.onStopRecording()</code>.
|
||||
At this point, your app must stop recording immediately. You also need to
|
||||
create an entry in the <code>RecordedPrograms</code> table. This entry should
|
||||
include the recorded session data URI in the
|
||||
<code>RecordedPrograms.COLUMN_RECORDING_DATA_URI</code> column, and any program
|
||||
information that the system provided in the initial call to
|
||||
<code>onStartRecording()</code>.</p>
|
||||
|
||||
<p>For more details on how to access the <code>RecordedPrograms</code> table
|
||||
see <a href="#sessions">Managing Recorded Sessions</a>.</p>
|
||||
|
||||
<h2 id="errors">Handling Recording Errors</h2>
|
||||
|
||||
<p>If an error occurs during recording, rendering the recorded data unusable,
|
||||
notify the system by calling <code>RecordingSession.notifyError()</code>.
|
||||
Similarly, you can call <code>notifyError()</code> after a recording session is
|
||||
created to let the system know that your app can no longer record sessions.</p>
|
||||
|
||||
<p>If an error occurs during recording, but you'd like to provide a usable
|
||||
partial recording to users for playback, call
|
||||
<code>RecordingSession.notifyRecordingStopped()</code> to enable the system to
|
||||
use the partial session.</p>
|
||||
|
||||
<h2 id="sessions">Managing Recorded Sessions</h2>
|
||||
|
||||
<p>The system maintains information for all recorded sessions from all
|
||||
recording-capable channel apps in the <code>TvContract.RecordedPrograms</code>
|
||||
content provider table. This information is accessible via the
|
||||
<code>RecordedPrograms.Uri</code> content URI. Use content provider APIs to
|
||||
read, add, and delete entries from this table.</p>
|
||||
|
||||
<p>For more information on working with content provider data see
|
||||
<a href="{@docRoot}guide/topics/providers/content-provider-basics.html">
|
||||
Content Provider Basics</a> .</p>
|
||||
|
||||
<h2 id="best">Best Practices</h2>
|
||||
|
||||
<p>TV devices may have limited storage, so use your best judgment when
|
||||
allocating storage to save recorded sessions. Use
|
||||
<code>RecordingCallback.onError(RECORDING_ERROR_INSUFFICIENT_SPACE)</code> when
|
||||
there isn't enough space to save a recorded session.</p>
|
||||
|
||||
<p>When the user initiates recording, you should start recording data as soon
|
||||
as possible. To facilitate this, complete any up-front time-consuming tasks,
|
||||
like accessing and allocating storage space, when the system invokes the
|
||||
<code>onCreateRecordingSession()</code> callback. Doing so lets you start
|
||||
recording immediately when the <code>onStartRecording()</code> callback
|
||||
fires.</p>
|
||||
@@ -726,6 +726,8 @@ toc:
|
||||
path: /training/tv/tif/channel.html
|
||||
- title: Managing User Interaction
|
||||
path: /training/tv/tif/ui.html
|
||||
- title: Supporting Content Recording
|
||||
path: /training/tv/tif/content-recording.html
|
||||
- title: TV Apps Checklist
|
||||
path: /training/tv/publishing/checklist.html
|
||||
path_attributes:
|
||||
|
||||
171
docs/html/training/tv/tif/content-recording.jd
Normal file
171
docs/html/training/tv/tif/content-recording.jd
Normal file
@@ -0,0 +1,171 @@
|
||||
page.title=Supporting Content Recording
|
||||
page.keywords=tv,recording,channel,tif
|
||||
page.tags=tv, tif
|
||||
helpoutsWidget=true
|
||||
|
||||
trainingnavtop=true
|
||||
|
||||
@jd:body
|
||||
|
||||
<div id="tb-wrapper">
|
||||
<div id="tb">
|
||||
<h2>In this document</h2>
|
||||
<ol>
|
||||
<li><a href="#supporting">Indicating Support for Recording</a></li>
|
||||
<li><a href="#recording">Recording a Session</a></li>
|
||||
<li><a href="#errors">Handling Recording Errors</a></li>
|
||||
<li><a href="#sessions">Managing Recorded Sessions</a></li>
|
||||
<li><a href="#best">Best Practices</a></li>
|
||||
</ol>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<p>TV input services let the user pause and resume channel playback via
|
||||
time-shifting APIs. Android 7.0 expands on time-shifting
|
||||
by letting the user save multiple recorded sessions.</p>
|
||||
|
||||
<p>Users can schedule recordings in advance, or start a recording as they watch
|
||||
a program. Once the system has saved a recording, the user can browse, manage,
|
||||
and play back the recording using the system TV app.</p>
|
||||
|
||||
<p>If you want to provide recording functionality for your TV input service,
|
||||
you must indicate to the system that your app supports recording, implement
|
||||
the ability to record programs, handle and communicate any errors that occur
|
||||
during recording, and manage your recorded sessions.</p>
|
||||
|
||||
<p class="note"><strong>Note:</strong> The Live Channels app does not yet
|
||||
provide a way for users to create or access recordings. Until changes are
|
||||
made to the Live Channels app, it may be difficult to fully test the recording
|
||||
experience for your TV input service.</p>
|
||||
|
||||
<h2 id="supporting">Indicating Support for Recording</h2>
|
||||
|
||||
<p>To tell the system that your TV input service supports recording, set
|
||||
the <code>android:canRecord</code> attribute in your service metadata XML file
|
||||
to <code>true</code>:
|
||||
</p>
|
||||
|
||||
<pre>
|
||||
<tv-input xmlns:android="http://schemas.android.com/apk/res/android"
|
||||
<b>android:canRecord="true"</b>
|
||||
android:setupActivity="com.example.sampletvinput.SampleTvInputSetupActivity" />
|
||||
</pre>
|
||||
|
||||
<p>For more information on the service metadata file, see
|
||||
<a href="{@docRoot}training/tv/tif/tvinput.html#manifest">Declare Your TV Input
|
||||
Service in the Manifest</a>.
|
||||
</p>
|
||||
|
||||
<p>Alternatively, you can indicate recording support in your code using
|
||||
these steps:</p>
|
||||
|
||||
<ol>
|
||||
<li>In your TV input service {@link android.app.Service#onCreate onCreate()}
|
||||
method, create a new {@link android.media.tv.TvInputInfo} object using the
|
||||
{@link android.media.tv.TvInputInfo.Builder TvInputInfo.Builder} class.</li>
|
||||
<li>When creating the new {@link android.media.tv.TvInputInfo} object, call
|
||||
{@link android.media.tv.TvInputInfo.Builder#setCanRecord
|
||||
setCanRecord(true)} before calling
|
||||
{@link android.media.tv.TvInputInfo.Builder#build build()} to indicate your
|
||||
service supports recording.</li>
|
||||
<li>Register your {@link android.media.tv.TvInputInfo} object with the
|
||||
system by calling
|
||||
{@link android.media.tv.TvInputManager#updateTvInputInfo
|
||||
TvInputManager.updateTvInputInfo()}.</li>
|
||||
</ol>
|
||||
|
||||
<h2 id="recording">Recording a Session</h2>
|
||||
|
||||
<p>After your TV input service registers that it supports recording
|
||||
functionality, the system calls your
|
||||
{@link android.media.tv.TvInputService#onCreateRecordingSession
|
||||
TvInputService.onCreateRecordingSession()} method when it needs to access
|
||||
your app's recording implementation. Implement your own
|
||||
{@link android.media.tv.TvInputService.RecordingSession
|
||||
TvInputService.RecordingSession} subclass and return it
|
||||
when the {@link android.media.tv.TvInputService#onCreateRecordingSession
|
||||
onCreateRecordingSession()} callback fires. This subclass is responsible
|
||||
for switching to the correct channel data, recording the requested data,
|
||||
and communicating recording status and errors to the system.</p>
|
||||
|
||||
<p>When the system calls
|
||||
{@link android.media.tv.TvInputService.RecordingSession#onTune
|
||||
RecordingSession.onTune()}, passing in a channel URI, tune to the channel
|
||||
that the URI specifies. Notify the system that your app has tuned to the
|
||||
desired channel by calling
|
||||
{@link android.media.tv.TvInputService.RecordingSession#notifyTuned
|
||||
notifyTuned()} or, if your app could not tune to the proper channel, call
|
||||
{@link android.media.tv.TvInputService.RecordingSession#notifyError
|
||||
notifyError()}.</p>
|
||||
|
||||
<p>The system next invokes the
|
||||
{@link android.media.tv.TvInputService.RecordingSession#onStartRecording
|
||||
RecordingSession.onStartRecording()} callback. Your app must start recording
|
||||
immediately. When the system invokes this callback, it may provide a URI
|
||||
that contains information about the program that is about to be recorded.
|
||||
When the recording is done, you'll copy this data to the
|
||||
{@link android.media.tv.TvContract.RecordedPrograms RecordedPrograms}
|
||||
data table.</p>
|
||||
|
||||
<p>Finally, the system calls
|
||||
{@link android.media.tv.TvInputService.RecordingSession#onStopRecording
|
||||
RecordingSession.onStopRecording()}. At this point, your app must stop
|
||||
recording immediately. You also need to create an entry in the
|
||||
{@link android.media.tv.TvContract.RecordedPrograms RecordedPrograms}
|
||||
table. This entry should include the recorded session data URI in the
|
||||
{@link android.media.tv.TvContract.RecordedPrograms#COLUMN_RECORDING_DATA_URI
|
||||
RecordedPrograms.COLUMN_RECORDING_DATA_URI} column, and any program
|
||||
information that the system provided in the initial call to
|
||||
{@link android.media.tv.TvInputService.RecordingSession#onStartRecording
|
||||
onStartRecording()}.</p>
|
||||
|
||||
<p>For more details on how to access the
|
||||
{@link android.media.tv.TvContract.RecordedPrograms RecordedPrograms} table
|
||||
see <a href="#sessions">Managing Recorded Sessions</a>.</p>
|
||||
|
||||
<h2 id="errors">Handling Recording Errors</h2>
|
||||
|
||||
<p>If an error occurs during recording, resulting in unusable recorded data,
|
||||
notify the system by calling
|
||||
{@link android.media.tv.TvInputService.RecordingSession#notifyError
|
||||
notifyError()}. Similarly, you can call
|
||||
{@link android.media.tv.TvInputService.RecordingSession#notifyError
|
||||
notifyError()} after a recording session is created to let the system know
|
||||
that your app can no longer record sessions.</p>
|
||||
|
||||
<p>If an error occurs during recording, but you'd like to provide a
|
||||
partial recording to users for playback, call
|
||||
{@link android.media.tv.TvInputService.RecordingSession#notifyRecordingStopped
|
||||
notifyRecordingStopped()} to enable the system to
|
||||
use the partial session.</p>
|
||||
|
||||
<h2 id="sessions">Managing Recorded Sessions</h2>
|
||||
|
||||
<p>The system maintains information for all recorded sessions from all
|
||||
recording-capable channel apps in the
|
||||
{@link android.media.tv.TvContract.RecordedPrograms RecordedPrograms}
|
||||
content provider table. This information is accessible via the
|
||||
{@link android.media.tv.TvContract.RecordedPrograms RecordedPrograms}
|
||||
content recording URIs. Use content provider APIs to
|
||||
read, add, and delete entries from this table.</p>
|
||||
|
||||
<p>For more information on working with content provider data see
|
||||
<a href="{@docRoot}guide/topics/providers/content-provider-basics.html">
|
||||
Content Provider Basics</a>.</p>
|
||||
|
||||
<h2 id="best">Best Practices</h2>
|
||||
|
||||
<p>TV devices may have limited storage, so use your best judgment when
|
||||
allocating storage to save recorded sessions. Use
|
||||
{@link android.media.tv.TvRecordingClient.RecordingCallback#onError
|
||||
RecordingCallback.onError(RECORDING_ERROR_INSUFFICIENT_SPACE)} when
|
||||
there isn't enough space to save a recorded session.</p>
|
||||
|
||||
<p>When the user initiates recording, you should start recording data as soon
|
||||
as possible. To facilitate this, complete any up-front time-consuming tasks,
|
||||
like accessing and allocating storage space, when the system invokes the
|
||||
{@link android.media.tv.TvInputService#onCreateRecordingSession
|
||||
onCreateRecordingSession()} callback. Doing so lets you start
|
||||
recording immediately when the
|
||||
{@link android.media.tv.TvInputService.RecordingSession#onStartRecording
|
||||
onStartRecording()} callback fires.</p>
|
||||
Reference in New Issue
Block a user