docs: Migrating TV Recording APIs preview docs into DAC

  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

      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:

page.title=TV Recording

page.keywords=preview,sdk,tv,recording

page.tags=androidn

page.image=images/cards/card-nyc_2x.jpg

page.title=Supporting Content Recording

page.keywords=tv,recording,channel,tif

page.tags=tv, tif

helpoutsWidget=true

trainingnavtop=true

@jd:body

<div id="qv-wrapper">

<div id="qv">

<div id="tb-wrapper">

<div id="tb">

  <h2>In this document</h2>

  <ol>

    <li><a href="#supporting">Indicating Support for Recording</a></li>

</div>

<p>TV input services let the user pause and resume channel playback via

time-shifting APIs. Android N expands on time-shifting

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

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>

<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

<code>TvInputService.onCreateRecordingSession()</code> when it needs to access

{@link android.media.tv.TvInputService#onCreateRecordingSession

TvInputService.onCreateRecordingSession()} method 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

{@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

<code>onStartRecording()</code>.</p>

{@link android.media.tv.TvInputService.RecordingSession#onStartRecording

onStartRecording()}.</p>

<p>For more details on how to access the <code>RecordedPrograms</code> table

<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, 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, 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 usable

<p>If an error occurs during recording, but you'd like to provide a

partial recording to users for playback, call

<code>RecordingSession.notifyRecordingStopped()</code> to enable the system to

{@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 <code>TvContract.RecordedPrograms</code>

recording-capable channel apps in the

{@link android.media.tv.TvContract.RecordedPrograms RecordedPrograms}

content provider table. This information is accessible via the

<code>RecordedPrograms.Uri</code> content URI. Use content provider APIs to

{@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

<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

{@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

<code>onCreateRecordingSession()</code> callback. Doing so lets you start

recording immediately when the <code>onStartRecording()</code> callback

fires.</p>

{@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>