Merge "docs: Adding N preview docs on TV recording APIs" into mnc-mr-docs

docs/html/preview/features/tv-recording-api.jd

@@ -0,0 +1,120 @@
+page.title=Android TV Recording APIs
+page.keywords=preview,sdk,tv,recording
+page.tags=androidn
+
+@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. The Android N Developer Preview 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>
+
+<h2 id="supporting">Indicating Support for Recording</h2>
+
+<p>To tell the system that your TV input service supports recording, follow
+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>TvInputService.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>