From ad3e0f2299493bc3e6df1b4adf58cd45447f202d Mon Sep 17 00:00:00 2001 From: Daniel Yu Date: Wed, 24 Feb 2016 15:10:12 -0800 Subject: [PATCH] docs: Adding N preview docs on TV recording APIs Adding docs on TV recording APIs, formerly known as DVR APIs. Only focuses on APIs for channel apps. For playback apps, these APIs should get documented by AOSP team for OEMs and partners. Adding updates from CL reviews. Bug: 27048027 Change-Id: I18ce62a3d0049a59a57f3daae71e26261688089d --- .../html/preview/features/tv-recording-api.jd | 120 ++++++++++++++++++ 1 file changed, 120 insertions(+) create mode 100644 docs/html/preview/features/tv-recording-api.jd diff --git a/docs/html/preview/features/tv-recording-api.jd b/docs/html/preview/features/tv-recording-api.jd new file mode 100644 index 0000000000000..64d0c297de76e --- /dev/null +++ b/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 + +
+ +
+ +

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.

+ +

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.

+ +

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.

+ +

Indicating Support for Recording

+ +

To tell the system that your TV input service supports recording, follow +these steps:

+ +
    +
  1. In your TvInputService.onCreate() method, create a new +TvInputInfo object using the TvInputInfo.Builder +class.
    2. +
  2. When creating the new TvInputInfo object, call +setCanRecord(true) before calling build() to +indicate your service supports recording.
    3. +
  3. Register your TvInputInfo object with the system by calling +TvInputService.updateTvInputInfo().
    4. +
+ +

Recording a Session

+ +

After your TV input service registers that it supports recording +functionality, the system calls your +TvInputService.onCreateRecordingSession() when it needs to access +your app's recording implementation. Implement your own +TvInputService.RecordingSession subclass and return it +when the 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.

+ +

When the system calls 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 notifyTuned(), +or, if your app could not tune to the proper channel, call +notifyError().

+ +

The system next invokes the 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 need to copy this +data to the RecordedPrograms data table.

+ +

Finally, the system calls RecordingSession.onStopRecording(). +At this point, your app must stop recording immediately. You also need to +create an entry in the RecordedPrograms table. This entry should +include the recorded session data URI in the +RecordedPrograms.COLUMN_RECORDING_DATA_URI column, and any program +information that the system provided in the initial call to +onStartRecording().

+ +

For more details on how to access the RecordedPrograms table +see Managing Recorded Sessions.

+ +

Handling Recording Errors

+ +

If an error occurs during recording, rendering the recorded data unusable, +notify the system by calling RecordingSession.notifyError(). +Similarly, you can call notifyError() after a recording session is +created to let the system know that your app can no longer record sessions.

+ +

If an error occurs during recording, but you'd like to provide a usable +partial recording to users for playback, call +RecordingSession.notifyRecordingStopped() to enable the system to +use the partial session.

+ +

Managing Recorded Sessions

+ +

The system maintains information for all recorded sessions from all +recording-capable channel apps in the TvContract.RecordedPrograms +content provider table. This information is accessible via the +RecordedPrograms.Uri content URI. Use content provider APIs to +read, add, and delete entries from this table.

+ +

For more information on working with content provider data see + +Content Provider Basics .

+ +

Best Practices

+ +

TV devices may have limited storage, so use your best judgment when +allocating storage to save recorded sessions. Use +RecordingCallback.onError(RECORDING_ERROR_INSUFFICIENT_SPACE) when +there isn't enough space to save a recorded session.

+ +

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 +onCreateRecordingSession() callback. Doing so lets you start +recording immediately when the onStartRecording() callback +fires.