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