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

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>