diff options
Diffstat (limited to 'en/devices/tv/index.html')
| -rw-r--r-- | en/devices/tv/index.html | 143 |
1 files changed, 94 insertions, 49 deletions
diff --git a/en/devices/tv/index.html b/en/devices/tv/index.html index 1b2fa230..2d330c20 100644 --- a/en/devices/tv/index.html +++ b/en/devices/tv/index.html @@ -25,8 +25,13 @@ <img style="float: right; margin: 0px 15px 15px 15px;" src="images/ape_fwk_hal_tv.png" alt="Android TV HAL icon"/> -<p>The Android TV Input Framework (TIF) simplifies delivery of live content to Android TV. The Android TIF provides a standard API for manufacturers to create input modules for controlling Android TV, and enables live TV search and recommendations via metadata published by the TV Input.</p> -<p>The framework does not seek to implement TV standards or regional requirements, but does make it easier for device manufacturers to meet regional digital TV broadcast standards without re-implementation. Documentation in this section might also be useful to third-party app developers who want to create custom TV Inputs.</p> +<p>The Android TV Input Framework (TIF) simplifies delivery of live content to Android TV. The +Android TIF provides a standard API for manufacturers to create input modules for controlling +Android TV, and enables live TV search and recommendations via metadata published by the TV Input.</p> +<p>The framework does not seek to implement TV standards or regional requirements, but does make it +easier for device manufacturers to meet regional digital TV broadcast standards without +re-implementation. Documentation in this section might also be useful to third-party app +developers who want to create custom TV Inputs.</p> <h2 id="components">Components</h2> @@ -39,11 +44,14 @@ parties through the TV Input Manager.</p> <p>The TV Input Framework consists of:</p> <ul> - <li>TV Provider (<code>com.android.providers.tv.TvProvider</code>): a database of channels, programs, and associated permissions + <li>TV Provider (<code>com.android.providers.tv.TvProvider</code>): a database of channels, + programs, and associated permissions <li>TV App (<code>com.android.tv.TvActivity</code>): the app that handles user interaction - <li>TV Input Manager (<code>android.media.tv.TvInputManager</code>): allows the TV Inputs to communicate with the TV App + <li>TV Input Manager (<code>android.media.tv.TvInputManager</code>): allows the TV Inputs to + communicate with the TV App <li>TV Input: an app representing physical or virtual tuners and input ports - <li>TV Input HAL (<code>tv_input</code> module): a hardware definition that allows system TV Inputs to access + <li>TV Input HAL (<code>tv_input</code> module): a hardware definition that allows system TV + Inputs to access TV-specific hardware when implemented <li>Parental Control: the technology to allow blocking of channels and programs <li>HDMI-CEC: the technology to allow remote control of various devices over HDMI @@ -64,7 +72,8 @@ detailed view of the Android TV Input Framework architecture.</p> replaced by a third-party app. <li>The TV App displays the AV content from the TV Input. <li>The TV App cannot talk directly with the TV Inputs. The TV Input Manager -identifies the state of TV Inputs for the TV App. See <em>TV Input Manager</em> below for more details about these limitations. +identifies the state of TV Inputs for the TV App. See <em>TV Input Manager</em> below for more +details about these limitations. </ol> <h2 id="permissions">Permissions</h2> @@ -81,7 +90,8 @@ and can READ/WRITE only to matching package rows. <li>Third-party TV inputs can either display their own content or content from a device manufacturer’s passthrough TV inputs, like HDMI1. They can’t display content from non-passthrough TV inputs, like a built-in or IPTV tuner. - <li><code>TV_INPUT_HARDWARE</code> permission for a hardware TV Input app, signals the TV Input Manager Service + <li><code>TV_INPUT_HARDWARE</code> permission for a hardware TV Input app, signals the TV Input + Manager Service to notify the TV Input service on boot to call the TV Input Manager Service and add its TV Inputs. This permission allows a hardware TV Input app to support multiple TV Inputs per TV Input service, as well as being able to dynamically @@ -99,7 +109,9 @@ accessing any other TV Inputs’ channels and programs. </p> <p>The TV Provider maps "broadcast genre" to "canonical genre" internally. TV Inputs are responsible for populating "broadcast genre" with the value in the underlying broadcast standard, and the "canonical genre" field will -automatically be populated with the correct associated genre from <code>android.provider.TvContract.Genres</code>. For example, with broadcast standard ATSC A/65 and program with genre 0x25 +automatically be populated with the correct associated genre from +<code>android.provider.TvContract.Genres</code>. For example, with broadcast +standard ATSC A/65 and program with genre 0x25 (meaning “Sports”), the TV Input will populate the “broadcast genre” with the String “Sports” and TV Provider will populate the “canonical genre” field with the mapped value <code>android.provider.TvContract.Genres.SPORTS</code>.</p> @@ -115,7 +127,8 @@ database. </em></p> <p>Passthrough TV inputs do not store channels and programs. </p> <p>In addition to the standard fields for channels and programs, the TV Provider -database also offers a BLOB type field, <code>COLUMN_INTERNAL_PROVIDER_DATA</code>, in each table that TV Inputs may use to store arbitrary data. That BLOB data +database also offers a BLOB type field, <code>COLUMN_INTERNAL_PROVIDER_DATA</code>, +in each table that TV Inputs may use to store arbitrary data. That BLOB data can include custom information, such as frequency of the associated tuner, and may be provided in a protocol buffer or another form. A Searchable field is available to make certain channels unavailable in search (such as to meet @@ -123,31 +136,41 @@ country-specific requirements for content protection).</p> <h3 id="tv_provider_database_field_examples">Database field examples</h3> -<p>The TV Provider supports structured data in channel (<code>android.provider.TvContract.Channels</code>) and program (<code>android.provider.TvContract.Programs</code>) tables. These tables are populated and accessed by TV Inputs and system apps +<p>The TV Provider supports structured data in channel +(<code>android.provider.TvContract.Channels</code>) and program +(<code>android.provider.TvContract.Programs</code>) tables. These tables are +populated and accessed by TV Inputs and system apps like the TV App. These tables have four types of fields:</p> <ul> - <li><strong>Display: </strong>Display fields contain information that apps may want to make visible to the -user, like a channel’s name (<code>COLUMN_DISPLAY_NAME</code>) or number (<code>COLUMN_DISPLAY_NUMBER</code>), or the title of the program being viewed. - <li><strong>Metadata:</strong> There are three fields for identifying content, according to relevant -standards, like a channel’s transport stream ID (<code>COLUMN_TRANSPORT_STREAM_ID</code>), original network ID (<code>COLUMN_ORIGINAL_NETWORK_ID</code>) and service id (<code>COLUMN_SERVICE_ID</code>). + <li><strong>Display: </strong>Display fields contain information that apps may + want to make visible to the user, like a channel’s name (<code>COLUMN_DISPLAY_NAME</code>) + or number (<code>COLUMN_DISPLAY_NUMBER</code>), or the title of the program being viewed. + <li><strong>Metadata:</strong> There are three fields for identifying content, according + to relevant standards, like a channel’s transport stream ID + (<code>COLUMN_TRANSPORT_STREAM_ID</code>), original network ID + (<code>COLUMN_ORIGINAL_NETWORK_ID</code>) and service id (<code>COLUMN_SERVICE_ID</code>). <li><strong>Internal data</strong>: Fields that are for the custom use of TV Inputs.<br> - Some fields, like <code>COLUMN_INTERNAL_PROVIDER_DATA</code>, are customizable BLOB fields where a TV Input can store arbitrary metadata -about their channel or program. - <li><strong>Flag: </strong>Flag fields represent whether a channel should be restricted from search, -browse, or viewing. This can be set only at the channel level. All programs + Some fields, like <code>COLUMN_INTERNAL_PROVIDER_DATA</code>, are customizable BLOB + fields where a TV Input can store arbitrary metadata about their channel or program. + <li><strong>Flag: </strong>Flag fields represent whether a channel should be restricted + from search, browse, or viewing. This can be set only at the channel level. All programs defer to the setting on the channel. <ul> - <li><code>COLUMN_SEARCHABLE</code>: Restricting search from some channels may be a requirement in certain -regions. <code>COLUMN_SEARCHABLE = 0</code> means the channel should not be exposed in search results. - <li><code>COLUMN_BROWSABLE</code>: Visible to system applications only. Restricting channel from being browsed -by applications. <code>COLUMN_BROWSABLE = 0</code> means the channel should not be included in the channel list. - <li><code>COLUMN_LOCKED</code>: Visible to system applications only. Restricting channel from being viewed by -invalid accounts without entering PIN code. <code>COLUMN_LOCKED = 1</code> means the channel should be protected by parental control. + <li><code>COLUMN_SEARCHABLE</code>: Restricting search from some channels may be a requirement + in certain regions. <code>COLUMN_SEARCHABLE = 0</code> means the channel should not be exposed + in search results. + <li><code>COLUMN_BROWSABLE</code>: Visible to system applications only. Restricting channel from + being browsed by applications. <code>COLUMN_BROWSABLE = 0</code> means the channel should not be + included in the channel list. + <li><code>COLUMN_LOCKED</code>: Visible to system applications only. Restricting channel from + being viewed by invalid accounts without entering PIN code. <code>COLUMN_LOCKED = 1</code> means + the channel should be protected by parental control. </ul> </ul> -<p>For a more exhaustive list of the fields, see <code>android/frameworks/base/media/java/android/media/tv/TvContract.java</code></p> +<p>For a more exhaustive list of the fields, see +<code>android/frameworks/base/media/java/android/media/tv/TvContract.java</code></p> <h3 id="permissions_and_access_control">Permissions and access control</h3> @@ -156,13 +179,14 @@ fields are directly accessible to users; they see only what the TV App, System apps, or TV Inputs surface.</p> <ul> - <li>Each row has <code>PACKAGE_NAME</code>, the package (app) that owns that row, checked on Query, Insert, Update via -TvProvider.java. + <li>Each row has <code>PACKAGE_NAME</code>, the package (app) that owns that row, checked on + Query, Insert, Update via TvProvider.java. A TV Input may access only the information it wrote and is cordoned off from the information provided by other TV Inputs. <li>READ, WRITE permissions via AndroidManifest.xml (requires user consent) to determine available channels. - <li>Only <code>signatureOrSystem</code> apps can acquire <code>ACCESS_ALL_EPG_DATA</code> permission to access the entire database. + <li>Only <code>signatureOrSystem</code> apps can acquire <code>ACCESS_ALL_EPG_DATA</code> + permission to access the entire database. </ul> <h2 id="tv_input_manager">TV Input Manager</h2> @@ -180,13 +204,16 @@ installed TV Inputs so apps may:</p> <p>For sessions, a TV Input may be tuned by the TV App only to URIs it has added to the TV Provider database, except for passthrough TV Inputs which can be -tuned to using <code>TvContract.buildChannelUriForPassthroughInput()</code>. A TV Input may also have its volume set. TV Inputs provided and signed by the +tuned to using <code>TvContract.buildChannelUriForPassthroughInput()</code>. +A TV Input may also have its volume set. TV Inputs provided and signed by the device manufacturer (signature apps) or other apps installed in the system partition will have access to the entire TV Provider database. This access can be used to construct apps to browse and search across all available TV channels and programs.</p> -<p>An app may create and register a <code>TvInputCallback</code> with the <code>android.media.tv.TvInputManager</code> to be called back on a TV Input’s state change or on the addition or removal +<p>An app may create and register a <code>TvInputCallback</code> with the +<code>android.media.tv.TvInputManager</code> to be called back on a TV Input’s +state change or on the addition or removal of a TV Input. For example, a TV App can react when a TV Input is disconnected by displaying it as disconnected and preventing its selection.</p> @@ -216,8 +243,9 @@ new input can be selected within the TV App.</p> <p>In this example, the TV Input provided by the device manufacturer is trusted and has full access to the TV Provider. As a passthrough TV Input, it does not register any channels or programs with the TV Provider. To obtain the URI used -to reference the passthrough input, use the <code>android.media.tv.TvContract</code> utility method <code>buildChannelUriForPassthroughInput(String inputId)</code>. The TV App communicates with the TV Input Manager to reach the HDMI TV -Input. </p> +to reference the passthrough input, use the <code>android.media.tv.TvContract</code> +utility method <code>buildChannelUriForPassthroughInput(String inputId)</code>. +The TV App communicates with the TV Input Manager to reach the HDMI TV Input.</p> <h3 id=built-in_tuner_example>Built-in tuner example</h3> @@ -250,18 +278,25 @@ the TV while the manufacturer-provided HDMI TV Input renders the video.</p> specific TV Input for picture in picture (PIP) display. Those button presses are interpreted by the hardware driver supplied by the device manufacturer, converting hardware scancodes to Android keycodes and passing them to the -standard Android <a href="/devices/input/overview.html">input pipeline</a> <code>InputReader</code> and <code>InputDispatcher</code> functions as <a href="http://developer.android.com/reference/android/view/KeyEvent.html">KeyEvents</a>. These in turn trigger events on the TV App if it is in focus. </p> +standard Android <a href="/devices/input/overview.html">input pipeline</a> +<code>InputReader</code> and <code>InputDispatcher</code> functions as +<a href="http://developer.android.com/reference/android/view/KeyEvent.html">KeyEvents</a>. +These in turn trigger events on the TV App if it is in focus. </p> -<p>Only system TV Inputs are eligible to receive <code>InputEvents</code>, and only if they have the <code>RECEIVE_INPUT_EVENT</code> system permission. The TV Input is responsible to determine which InputEvents -to consume and should allow the TV App to handle the keys it does not need to -consume.</p> +<p>Only system TV Inputs are eligible to receive <code>InputEvents</code>, and only if +they have the <code>RECEIVE_INPUT_EVENT</code> system permission. The TV Input is +responsible to determine which InputEvents to consume and should allow the TV App to +handle the keys it does not need to consume.</p> <p>The TV App is responsible for knowing which system TV Input is active, meaning -selected by the user, and to disambiguate incoming <code>KeyEvents</code> and route them to the correct TV Input Manager session, calling <code>dispatchInputEvent()</code> to pass on the event to the associated TV Input. </p> +selected by the user, and to disambiguate incoming <code>KeyEvents</code> and route them to the +correct TV Input Manager session, calling <code>dispatchInputEvent()</code> to pass on the event +to the associated TV Input.</p> <h3 id="mheg-5_input_example">MHEG-5 input example</h3> -<p>The following diagram shows a more detailed view of how <code>KeyEvents</code> are routed through the Android TIF.</p> +<p>The following diagram shows a more detailed view of how <code>KeyEvents</code> are +routed through the Android TIF.</p> <img src="images/TIF_MHEG5_app.png" alt="Android TV Red button example"> <p class="img-caption"><strong>Figure 7.</strong> Android TV Red button example</p> @@ -278,11 +313,14 @@ related web pages or sports scores.</p> <ol> <li>The TV App is in focus and receives all keys. - <li><code>KeyEvents</code> (e.g. the Red button) is passed to the active TV Input as <code>InputEvents.</code> - <li>The system TV Input integrates with MHEG-5 stack and has the <code>RECEIVE_INPUT_EVENT</code> system permission. + <li><code>KeyEvents</code> (e.g. the Red button) is passed to the active TV Input as + <code>InputEvents.</code> + <li>The system TV Input integrates with MHEG-5 stack and has the + <code>RECEIVE_INPUT_EVENT</code> system permission. <li>On receiving activation keycode (e.g. Red button), the TV Input activates broadcast app. - <li>TV input consumes <code>KeyEvents</code> as <code>InputEvents</code> and the broadcast app is the focus and handles <code>InputEvents</code> until dismissed. + <li>TV input consumes <code>KeyEvents</code> as <code>InputEvents</code> and the broadcast + app is the focus and handles <code>InputEvents</code> until dismissed. </ol> <p class="note"><strong>Note</strong>: Third-party TV inputs never receive keys. </p> @@ -394,13 +432,17 @@ inputs.</p> <img src="images/LiveChannels_Add_channel.png" alt="Add channels from your source"> <p class="img-caption"><strong>Figure 11.</strong> Add channels from your source</p> -<p>In addition a notification card is shown at the top of the TV App menu after a new TvInput is installed, to take the user directly to the Setup:</p> +<p>In addition a notification card is shown at the top of the TV App menu after a +new TvInput is installed, to take the user directly to the Setup:</p> <img src="images/LiveChannels_set_up_sources.png" alt="Notification that shows new channel sources are available."> -<p class="img-caption"><strong>Figure 12.</strong> Notification that shows new channel sources are available.</p> +<p class="img-caption"><strong>Figure 12.</strong> Notification that shows new channel +sources are available.</p> -<p>If the user takes action through the notification, they can select to set up their sources as seen in Figure 10.</p> -<p>See <a href="http://developer.android.com/training/tv/tif/tvinput.html#setup">Define Your TV Input Service</a> +<p>If the user takes action through the notification, they can select to set up their +sources as seen in Figure 10.</p> +<p>See <a href="http://developer.android.com/training/tv/tif/tvinput.html#setup">Define +Your TV Input Service</a> for developer expectations in this area.</p> <h4 id=customize_the_channel_list>Customize the channel list</h4> @@ -432,7 +474,9 @@ is that users are able to find the channels they have installed. </p> <p>Manufacturers must implement the TV App to include search results for global search requests in order to ensure the best user experience. Live TV provides an -implementation (see <a href="https://android.googlesource.com/platform/packages/apps/TV/+/android-live-tv/src/com/android/tv/search/TvProviderSearch.java">com.android.tv.search.TvProviderSearch</a>) which provides results from third-party inputs (required for platform +implementation (see +<a href="https://android.googlesource.com/platform/packages/apps/TV/+/android-live-tv/src/com/android/tv/search/TvProviderSearch.java">com.android.tv.search.TvProviderSearch</a>) +which provides results from third-party inputs (required for platform compatibility) as well as built-in inputs.</p> <h4 id="time-shifting">Time shifting</h4> @@ -526,7 +570,8 @@ Recording</a> article. Running this against Live TV may be a useful way to see the EPG, Search, Parental Control, and other requirements in the context of third-party inputs. - <li> See <a href="http://developer.android.com/training/tv/tif/tvinput.html#setup">Define Your TV Input Service</a> + <li> See <a href="http://developer.android.com/training/tv/tif/tvinput.html#setup">Define Your + TV Input Service</a> for developer expectations in this area. </ul> @@ -636,7 +681,7 @@ different source. <li> The TV Input Manager service generates an intent for the TV App to switch the source. <li> The TV App then creates a TV Input Manager Session for the TV Input being -switched to and calls <code>setMain</code> on that session. +switched to and calls <code>setMain</code> on that session. <li> The TV Input Manager Session passes this information on to the HDMI TV Input. <li> The HDMI TV input requests to set sideband surface. <li> The TV Input Manager Service generates a corresponding routing control command @@ -654,7 +699,7 @@ the broadcast app, for example:</p> <ul> <li> MHEG: native stack <li> Teletext: native stack - <li> HbbTV: webkit modification by Opera browser + <li> HbbTV: HbbTV solution from Vewd Software </ul> <p>In the Android L release, Android TV expects device manufacturers to use systems |