1 page.title=TV Input Framework 2 @jd:body 3 4 <!-- 5 Copyright 2015 The Android Open Source Project 6 7 Licensed under the Apache License, Version 2.0 (the "License"); 8 you may not use this file except in compliance with the License. 9 You may obtain a copy of the License at 10 11 http://www.apache.org/licenses/LICENSE-2.0 12 13 Unless required by applicable law or agreed to in writing, software 14 distributed under the License is distributed on an "AS IS" BASIS, 15 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 16 See the License for the specific language governing permissions and 17 limitations under the License. 18 --> 19 <div id="qv-wrapper"> 20 <div id="qv"> 21 <h2>In this document</h2> 22 <ol id="auto-toc"> 23 </ol> 24 </div> 25 </div> 26 27 <img style="float: right; margin: 0px 15px 15px 15px;" src="images/ape_fwk_hal_tv.png" alt="Android TV HAL icon"/> 28 29 <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> 30 <p>The framework does not seek to implement TV standards or regional requirements, but does makes 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> 31 32 <h2 id="components">Components</h2> 33 34 <p>The Android TV Input Framework implementation includes a TV Input Manager. 35 The TIF works with the TV App, a system app that cant be replaced by a 36 third-party app, to access built-in and IP tuner channels. The TV App 37 communicates with TV Input modules supplied by the device manufacturer or other 38 parties through the TV Input Manager.</p> 39 40 <p>The TV Input Framework consists of:</p> 41 42 <ul> 43 <li>TV Provider (<code>com.android.providers.tv.TvProvider</code>): a database of channels, programs, and associated permissions 44 <li>TV App (<code>com.android.tv.TvActivity</code>): the app that handles user interaction 45 <li>TV Input Manager (<code>android.media.tv.TvInputManager</code>): allows the TV Inputs to communicate with the TV App 46 <li>TV Input: an app representing physical or virtual tuners and input ports 47 <li>TV Input HAL (<code>tv_input</code> module): a hardware definition that allows system TV Inputs to access 48 TV-specific hardware when implemented 49 <li>Parental Control: the technology to allow blocking of channels and programs 50 <li>HDMI-CEC: the technology to allow remote control of various devices over HDMI 51 </ul> 52 53 <p>These components are covered in detail below. See the following diagram for a 54 detailed view of the Android TV Input Framework architecture.</p> 55 56 <img src="images/TIF_Overview.png" alt="Overview of the Android TIF architecture"> 57 <p class="img-caption"><strong>Figure 1.</strong> Android TV Input Framework (TIF) architecture</p> 58 59 <h2 id="flow">Flow</h2> 60 61 <p>Here is how the architecture is exercised:</p> 62 63 <ol> 64 <li>The user sees and interacts with the TV App, a system app that cant be 65 replaced by a third-party app. 66 <li>The TV App displays the AV content from the TV Input. 67 <li>The TV App cannot talk directly with the TV Inputs. The TV Input Manager 68 identifies the state of TV Inputs for the TV App. See <em>TV Input Manager</em> below for more details about these limitations. 69 </ol> 70 71 <h2 id="permissions">Permissions</h2> 72 73 <ul> 74 <li>Only <code><a 75 href="http://developer.android.com/guide/topics/manifest/permission-element.html#plevel">signatureOrSystem</a></code> 76 TV Inputs and TV App have full access to the TV Provider database and are able 77 to receive KeyEvents. 78 <li>Only system TV Inputs can access the TV Input HAL through the TV Input Manager 79 service. TV Inputs are accessed one-to-one via TV Input Manager sessions. 80 <li>Third-party TV Inputs have package-locked access to the TV Provider database 81 and can READ/WRITE only to matching package rows. 82 <li>Third-party TV inputs can either display their own content or content from a 83 device manufacturers passthrough TV inputs, like HDMI1. They cant display 84 content from non-passthrough TV inputs, like a built-in or IPTV tuner. 85 <li><code>TV_INPUT_HARDWARE</code> permission for a hardware TV Input app, signals the TV Input Manager Service 86 to notify the TV Input service on boot to call the TV Input Manager Service and 87 add its TV Inputs. This permission allows a hardware TV Input app to support 88 multiple TV Inputs per TV Input service, as well as being able to dynamically 89 add and remove its supported TV Inputs. 90 </ul> 91 92 <h2 id="tv_provider">TV Provider</h2> 93 94 <p>The TV Provider database stores the channels and programs from TV Inputs. The 95 TV Provider also publishes and manages the associated permissions so that TV 96 Inputs can see only their own records. For instance, a specific TV Input can 97 see only the channels and programs it has supplied and is prohibited from 98 accessing any other TV Inputs channels and programs. </p> 99 100 <p>The TV Provider maps "broadcast genre" to "canonical genre" internally. TV 101 Inputs are responsible for populating "broadcast genre" with the value in the 102 underlying broadcast standard, and the "canonical genre" field will 103 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 104 (meaning Sports), the TV Input will populate the broadcast genre with the 105 String Sports and TV Provider will populate the canonical genre field with 106 the mapped value <code>android.provider.TvContract.Genres.SPORTS</code>.</p> 107 108 <p>See the diagram below for a detailed view of the TV Provider. </p> 109 110 <img src="images/TIF_TV_Provider.png" alt="Android TV Provider"> 111 <p class="img-caption"><strong>Figure 2.</strong> Android TV Provider</p> 112 113 <p><em>Only apps in the privileged system partition can read the entire TV Provider 114 database. </em></p> 115 116 <p>Passthrough TV inputs do not store channels and programs. </p> 117 118 <p>In addition to the standard fields for channels and programs, the TV Provider 119 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 120 can include custom information, such as frequency of the associated tuner, and 121 may be provided in a protocol buffer or another form. A Searchable field is 122 available to make certain channels unavailable in search (such as to meet 123 country-specific requirements for content protection).</p> 124 125 <h3 id="tv_provider_database_field_examples">Database field examples</h3> 126 127 <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 128 like the TV App. These tables have four types of fields:</p> 129 130 <ul> 131 <li><strong>Display: </strong>Display fields contain information that apps may want to make visible to the 132 user, like a channels name (<code>COLUMN_DISPLAY_NAME</code>) or number (<code>COLUMN_DISPLAY_NUMBER</code>), or the title of the program being viewed. 133 <li><strong>Metadata:</strong> There are three fields for identifying content, according to relevant 134 standards, like a channels 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>). 135 <li><strong>Internal data</strong>: Fields that are for the custom use of TV Inputs.<br> 136 Some fields, like <code>COLUMN_INTERNAL_PROVIDER_DATA</code>, are customizable BLOB fields where a TV Input can store arbitrary metadata 137 about their channel or program. 138 <li><strong>Flag: </strong>Flag fields represent whether a channel should be restricted from search, 139 browse, or viewing. This can be set only at the channel level. All programs 140 defer to the setting on the channel. 141 <ul> 142 <li><code>COLUMN_SEARCHABLE</code>: Restricting search from some channels may be a requirement in certain 143 regions. <code>COLUMN_SEARCHABLE = 0</code> means the channel should not be exposed in search results. 144 <li><code>COLUMN_BROWSABLE</code>: Visible to system applications only. Restricting channel from being browsed 145 by applications. <code>COLUMN_BROWSABLE = 0</code> means the channel should not be included in the channel list. 146 <li><code>COLUMN_LOCKED</code>: Visible to system applications only. Restricting channel from being viewed by 147 invalid accounts without entering PIN code. <code>COLUMN_LOCKED = 1</code> means the channel should be protected by parental control. 148 </ul> 149 </ul> 150 151 <p>For a more exhaustive list of the fields, see <code>android/frameworks/base/media/java/android/media/tv/TvContract.java</code></p> 152 153 <h3 id="permissions_and_access_control">Permissions and access control</h3> 154 155 <p>All fields are visible to anyone with access to the corresponding row. No 156 fields are directly accessible to users; they see only what the TV App, System 157 apps, or TV Inputs surface.</p> 158 159 <ul> 160 <li>Each row has <code>PACKAGE_NAME</code>, the package (app) that owns that row, checked on Query, Insert, Update via 161 TvProvider.java. 162 A TV Input may access only the information it wrote and is 163 cordoned off from the information provided by other TV Inputs. 164 <li>READ, WRITE permissions via AndroidManifest.xml (requires user consent) to 165 determine available channels. 166 <li>Only <code>signatureOrSystem</code> apps can acquire <code>ACCESS_ALL_EPG_DATA</code> permission to access the entire database. 167 </ul> 168 169 <h2 id="tv_input_manager">TV Input Manager</h2> 170 171 <p>The TV Input Manager provides a central system API to the overall Android TV 172 Input Framework. It arbitrates interaction between apps and TV Inputs and 173 provides parental control functionality. TV Input Manager sessions must be 174 created one-to-one with TV Inputs. The TV Input Manager allows access to 175 installed TV Inputs so apps may:</p> 176 177 <ul> 178 <li>List TV inputs and check their status 179 <li>Create sessions and manage listeners 180 </ul> 181 182 <p>For sessions, a TV Input may be tuned by the TV App only to URIs it has added 183 to the TV Provider database, except for passthrough TV Inputs which can be 184 tuned to using <code>TvContract.buildChannelUriForPassthroughInput()</code>. A TV Input may also have its volume set. TV Inputs provided and signed by the 185 device manufacturer (signature apps) or other apps installed in the system 186 partition will have access to the entire TV Provider database. This access can 187 be used to construct apps to browse and search across all available TV channels 188 and programs.</p> 189 190 <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 Inputs state change or on the addition or removal 191 of a TV Input. For example, a TV App can react when a TV Input is disconnected 192 by displaying it as disconnected and preventing its selection.</p> 193 194 <p>The TV Input Manager abstracts communication between the TV App and TV Inputs. 195 The standard interface of TV Input Manager and TV Input allows multiple 196 device manufacturers to create their own TV Apps while helping all third-party TV Inputs 197 work on all TV Apps.</p> 198 199 <h2 id="tv_inputs">TV Inputs</h2> 200 201 <p>TV Inputs are Android apps in the sense they have an AndroidManifest.xml and 202 are installed (via Play, pre-installed, or sideloaded). Android TV supports 203 pre-installed system apps, apps signed by the device manufacturer and 204 third-party TV Inputs. </p> 205 206 <p>Some inputs, like the HDMI input or built-in tuner input, can be provided only 207 by the manufacturer as they speak directly with the underlying hardware. 208 Others, such as IPTV, place-shifting, and external STB, can be supplied by 209 third parties as APKs on Google Play Store. Once downloaded and installed, the 210 new input can be selected within the TV App.</p> 211 212 <h3 id=passthrough_input_example>Passthrough input example</h3> 213 214 <img src="images/TIF_HDMI_TV_Input.png" alt="Android TV System Input"> 215 <p class="img-caption"><strong>Figure 3.</strong> Android TV System Input</p> 216 217 <p>In this example, the TV Input provided by the device manufacturer is trusted 218 and has full access to the TV Provider. As a passthrough TV Input, it does not 219 register any channels or programs with the TV Provider. To obtain the URI used 220 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 221 Input. </p> 222 223 <h3 id=built-in_tuner_example>Built-in tuner example</h3> 224 225 <img src="images/Built-in_Tuner_TV_Input.png" alt="Android TV Built-in Tuner Input"> 226 <p class="img-caption"><strong>Figure 4.</strong> Android TV Built-in Tuner Input</p> 227 228 <p>In this example, the Built-in Tuner TV Input provided by the device 229 manufacturer is trusted and has full access to the TV Provider. </p> 230 231 <h3 id=third-party_input_example>Third-party input example</h3> 232 233 <img src="images/Third-party_Input_HDMI.png" alt="Android TV third-party input"> 234 <p class="img-caption"><strong>Figure 5.</strong> Android TV third-party input</p> 235 236 <p>In this example, the external STB TV Input is provided by a third party. Since 237 that TV Input cant directly access the HDMI video feed coming in, it must go 238 through the TV Input Manager and use the HDMI TV Input provided by the device 239 manufacture.</p> 240 241 <p>Through the TV Input Manager, the external STB TV Input can speak with the HDMI 242 TV Input and ask it to show the video on HDMI1. So the STB TV Input can control 243 the TV while the manufacturer-provided HDMI TV Input renders the video.</p> 244 245 <h3 id=picture_in_picture_pip_example>Picture in picture (PIP) example </h3> 246 247 <img src="images/TIF_PIP-PAP.png" alt="Android TV KeyEvents"> 248 <p class="img-caption"><strong>Figure 6.</strong> Android TV KeyEvents</p> 249 250 <p>The diagram above shows how buttons on a remote control are passed to a 251 specific TV Input for picture in picture (PIP) display. Those button presses 252 are interpreted by the hardware driver supplied by the device manufacturer, 253 converting hardware scancodes to Android keycodes and passing them to the 254 standard Android <a href="{@docRoot}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> 255 256 <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 257 to consume and should allow the TV App to handle the keys it does not need to 258 consume.</p> 259 260 <p>The TV App is responsible for knowing which system TV Input is active, meaning 261 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> 262 263 <h3 id="mheg-5_input_example">MHEG-5 input example</h3> 264 265 <p>The following diagram shows a more detailed view of how <code>KeyEvents</code> are routed through the Android TIF.</p> 266 267 <img src="images/TIF_MHEG5_app.png" alt="Android TV Red button example"> 268 <p class="img-caption"><strong>Figure 7.</strong> Android TV Red button example</p> 269 270 <p>It depicts the flow of a Red button app, common in Europe for letting users 271 access interactive apps on their televisions. An app can be delivered over this 272 transport stream. When the button is clicked, it lets users interact with these 273 broadcast apps. For example, you might use these broadcast apps to access 274 related web pages or sports scores.</p> 275 276 <p>See the <em>Broadcast app</em> section to learn how broadcast apps interact with the TV App.</p> 277 278 <p>In this example:</p> 279 280 <ol> 281 <li>The TV App is in focus and receives all keys. 282 <li><code>KeyEvents</code> (e.g. the Red button) is passed to the active TV Input as <code>InputEvents.</code> 283 <li>The system TV Input integrates with MHEG-5 stack and has the <code>RECEIVE_INPUT_EVENT</code> system permission. 284 <li>On receiving activation keycode (e.g. Red button), the TV Input activates 285 broadcast app. 286 <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. 287 </ol> 288 289 <p class="note"><strong>Note</strong>: Third-party TV inputs never receive keys. </p> 290 291 <h2 id="tv_input_hal">TV Input HAL</h2> 292 293 <p>The TV Input HAL aids development of TV Inputs to access TV-specific hardware. 294 As with other Android HALs, the TV Input HAL (<code>tv_input</code>) is 295 available in the AOSP source tree and the vendor develops its implementation.</p> 296 297 <h2 id="tv_app">TV App</h2> 298 299 <p>The TV App provides channel and program search results (via 300 <code>com.android.tv.search.TvProviderSearch</code>) and passes keys, tune, and 301 volume calls to TV Inputs through the TV Input 302 Manager. Manufacturers must implement the TV App to ensure search functions 303 work for their users. Otherwise, users will struggle to navigate the resulting 304 Android TV. Third-party developers cannot develop TV Apps as the APIs require 305 system or signature permission.</p> 306 307 <p>As with the TIF in general, the TV App does not seek to implement device 308 manufacturer or country-specific features. Instead, it handles these tasks by 309 default:</p> 310 311 <h3 id="setup_and_configuration">Setup and configuration</h3> 312 313 <ul> 314 <li>Auto-detect TV Inputs 315 <li>Let TV Inputs initiate channel setup 316 <li>Control parental settings 317 <li>Alter TV settings 318 <ul> 319 <li>Edit channel 320 </ul> 321 </ul> 322 323 <h3 id="viewing">Viewing</h3> 324 <ul> 325 <li>Access and navigate all TV channels 326 <li>Access TV program information bar 327 <li>Multiple audio and subtitle track support 328 <li>Parental control PIN challenge 329 <li>Allow TV Input UI overlay for: 330 <ul> 331 <li>TV standard (HbbTV, etc.) 332 </ul> 333 </ul> 334 335 <h2 id="parental_control">Parental Control</h2> 336 337 <p>Parental control lets a user block undesired channels and programs, but bypass 338 the block by entering a PIN code.</p> 339 340 <p>Responsibility for parental control functionality is shared amongst the TV App, 341 TV Input Manager service, TV Provider, and TV Input. </p> 342 343 <h3 id="tv_provider">TV Provider</h3> 344 345 <p>Each channel row has a <code>COLUMN_LOCKED</code> field that is used to lock 346 specific channels from viewing without entering a PIN code. The program field 347 <code>COLUMN_CONTENT_RATING</code> is intended for display and is not used to 348 enforce parental control.</p> 349 350 <h3 id="tv_input_manager">TV Input Manager</h3> 351 352 <p>The TV Input Manager stores every blocked <code>TvContentRating</code> and 353 responds to <code>isRatingBlocked()</code> to advise if content with the given 354 rating should be blocked.</p> 355 356 <h3 id="tv_input">TV Input</h3> 357 358 <p>The TV Input checks if the current content should be blocked by calling 359 <code>isRatingBlocked()</code> on the TV Input Manager when the rating of the 360 displayed content has changed 361 (on program or channel change), or parental control settings have changed (on 362 <code>ACTION_BLOCKED_RATINGS_CHANGED</code> and 363 <code>ACTION_PARENTAL_CONTROLS_ENABLED_CHANGED</code>). If the content should 364 be blocked, the TV Input disables the audio and video 365 and notifies the TV app that the current content is blocked by calling 366 <code>notifyContentBlocked(TvContentRating)</code>. If the content should not 367 be blocked, the TV Input enables audio and video and notifies the TV App 368 the current content is allowed by calling <code>notifyContentAllowed()</code>.</p> 369 370 <h3 id="tv_app">TV App</h3> 371 372 <p>The TV App shows parental control settings to users and a PIN code UI when it 373 is notified by a TV Input that the current content is blocked or when the user 374 attempts to view a blocked channel.</p> 375 376 <p>The TV App does not directly store the parental control settings. When the user 377 changes the parental control settings, every blocked 378 <code>TvContentRating</code> is stored by the TV Input Manager, and blocked 379 channels are stored by the TV Provider.</p> 380 381 <h2 id="hdmi-cec">HDMI-CEC</h2> 382 383 <p>HDMI-CEC allows one device to control another, thereby enabling a single remote 384 to control multiple appliances in a home theater. It is used by Android TV to 385 speed setup and allow distant control over various TV Inputs via the central TV 386 App. For instance, it may switch inputs, power up or down devices, and more.</p> 387 388 <p>The Android TIF implements HDMI-CEC as the HDMI Control Service so that 389 device manufacturers merely need to develop low-level drivers that interact with the 390 lightweight Android TV HAL, skipping more complex business logic. In providing 391 a standard implementation, Android seeks to mitigate compatibility issues by 392 reducing fragmented implementations and selective feature support. The HDMI 393 Control Service uses the existing Android services, including input and power.</p> 394 395 <p>This means existing HDMI-CEC implementations will need to be redesigned to 396 interoperate with the Android TIF. We recommend the hardware platform contain a 397 microprocessor to receive CEC power on and other commands.</p> 398 399 <img src="images/TV_App_CEC_integration.png" alt="CEC integration on Android TV"> 400 <p class="img-caption"><strong>Figure 8.</strong> CEC integration on Android TV</p> 401 402 <ol> 403 <li> The CEC bus receives a command from the currently active source to switch to a 404 different source. 405 <li> The driver passes the command to the HDMI-CEC HAL. 406 <li> The HAL notifies all <code>ActiveSourceChangeListeners</code>. 407 <li> THe HDMI Control Service is notified of source change via <code>ActiveSourceChangeListener</code>. 408 <li> The TV Input Manager service generates an intent for the TV App to switch the 409 source. 410 <li> The TV App then creates a TV Input Manager Session for the TV Input being 411 switched to and calls <code>setMain</code> on that session. 412 <li> The TV Input Manager Session passes this information on to the HDMI TV Input. 413 <li> The HDMI TV input requests to set sideband surface. 414 <li> The TV Input Manager Service generates a corresponding routing control command 415 back to HDMI Control Service when the surface is set. 416 </ol> 417 418 <h2 id="tv_integration_guidelines">TV integration guidelines</h2> 419 420 <h3 id="broadcast_app">Broadcast app</h3> 421 422 <p>Because each country has broadcast-specific requirements (MHEG, Teletext, 423 HbbTV, and more), manufacturers are expected to supply their own solutions for 424 the broadcast app, for example:</p> 425 426 <ul> 427 <li> MHEG: native stack 428 <li> Teletext: native stack 429 <li> HbbTV: webkit modification by Opera browser 430 </ul> 431 432 <p>In the Android L release, Android TV expects device manufacturers to use systems 433 integrators or the Android solutions for regional TV stacks, pass the surface 434 to TV software stacks, or pass the necessary key code to interact with legacy 435 stacks.</p> 436 437 <p>Heres how the broadcast app and TV App interact:</p> 438 439 <ol> 440 <li>The TV App is in focus, receiving all keys. 441 <li>The TV App passes keys (e.g. Red button) to the TV Input device. 442 <li>The TV Input device internally integrates with legacy TV stack. 443 <li>On receiving an activation keycode (e.g. Red button), the TV Input device 444 activates broadcast apps. 445 <li>A broadcast app takes focus in the TV App and handles user actions. 446 </ol> 447 448 <p>For voice search/recommendation, the broadcast app may support In-app search 449 for voice search.</p> 450 451 <h3 id="dvr">DVR</h3> 452 453 <p>Android TV supports digital video recording (DVR) with device manufacturer development. The 454 DVR function works like so:</p> 455 456 <ol> 457 <li> DVR recording function / Live Buffer can be implemented by any TV Input. 458 <li> TV App passes on key inputs to TV Input (including recording/pause/fast 459 forward/ rewind keys). 460 <li> When playing the recorded content, the TV Input handles it with trick play 461 overlay. 462 <li> DVR app enables users to browse and manage recorded program. 463 </ol> 464 465 <p>For voice search/recommendation:</p> 466 467 <ul> 468 <li>DVR app supports In-app search for Voice search. 469 <li>DVR app can propose recommendation using notifications. 470 </ul> 471 472 <p>See the following diagram for a view into a possible DVR implementation in 473 Android TV.</p> 474 475 <img src="images/TV_Input_DVR.png" alt="Digital video recording in Android TV"> 476 <p class="img-caption"><strong>Figure 9.</strong> Digital video recording in Android TV</p> 477
