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
diff --git a/docs/html/_redirects.yaml b/docs/html/_redirects.yaml
index 837b222..b6d28dc 100644
--- a/docs/html/_redirects.yaml
+++ b/docs/html/_redirects.yaml
@@ -1210,3 +1210,5 @@
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
diff --git a/docs/html/preview/features/tv-recording-api.jd b/docs/html/preview/features/tv-recording-api.jd
deleted file mode 100644
index 6619821..0000000
--- a/docs/html/preview/features/tv-recording-api.jd
+++ /dev/null
@@ -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>
diff --git a/docs/html/training/_book.yaml b/docs/html/training/_book.yaml
index 6142dba..0054c5c 100644
--- a/docs/html/training/_book.yaml
+++ b/docs/html/training/_book.yaml
@@ -726,6 +726,8 @@
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:
diff --git a/docs/html/training/tv/tif/content-recording.jd b/docs/html/training/tv/tif/content-recording.jd
new file mode 100644
index 0000000..ffdd14c
--- /dev/null
+++ b/docs/html/training/tv/tif/content-recording.jd
@@ -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>
