Docs: Add reference TV App article and update TV app section in TIF article
Bug: 24763218
diff --git a/src/devices/devices_toc.cs b/src/devices/devices_toc.cs
index 733b3f2..370e86b 100644
--- a/src/devices/devices_toc.cs
+++ b/src/devices/devices_toc.cs
@@ -231,6 +231,7 @@
</div>
<ul>
<li><a href="<?cs var:toroot ?>devices/tv/HDMI-CEC.html">HDMI-CEC control service</a></li>
+ <li><a href="<?cs var:toroot ?>devices/tv/reference-tv-app.html">Reference TV App</a></li>
</ul>
</li>
</ul>
diff --git a/src/devices/tv/index.jd b/src/devices/tv/index.jd
index d502872..aa26751 100644
--- a/src/devices/tv/index.jd
+++ b/src/devices/tv/index.jd
@@ -296,40 +296,135 @@
<h2 id="tv_app">TV App</h2>
-<p>The TV App provides channel and program search results (via
-<code>com.android.tv.search.TvProviderSearch</code>) and passes keys, tune, and
-volume calls to TV Inputs through the TV Input
-Manager. Manufacturers must implement the TV App to ensure search functions
-work for their users. Otherwise, users will struggle to navigate the resulting
-Android TV. Third-party developers cannot develop TV Apps as the APIs require
-system or signature permission.</p>
-<p>As with the TIF in general, the TV App does not seek to implement device
-manufacturer or country-specific features. Instead, it handles these tasks by
-default:</p>
+<p>The system TV App presents live TV content to the user. A reference TV
+App (Live Channels) is provided alongside the Android platform, which
+can be used as-is, customized, extended, or replaced by device manufacturers.
+The <a href="https://android.googlesource.com/platform/packages/apps/TV/">source code</a>
+is available in the Android Open Source Project, and you can get started with
+it in the <a href="{@docRoot}devices/tv/reference-tv-app.html">Reference TV app</a> article.</p>
+
+<p>Device manufacturers may extend their TV Apps to implement device
+manufacturer or country-specific features, however this is not in the scope of
+TIF or the reference TV App.</p>
+
+<p>At a minimum, the system TV App needs to handle the following tasks:</p>
<h3 id="setup_and_configuration">Setup and configuration</h3>
+
<ul>
- <li>Auto-detect TV Inputs
- <li>Let TV Inputs initiate channel setup
- <li>Control parental settings
- <li>Alter TV settings
- <ul>
- <li>Edit channel
- </ul>
+ <li> Auto-detect TV Inputs
+ <li> Let TV Inputs initiate channel setup
+ <li> Control parental settings
+ <li> Edit channel
</ul>
<h3 id="viewing">Viewing</h3>
+
+
<ul>
- <li>Access and navigate all TV channels
- <li>Access TV program information bar
- <li>Multiple audio and subtitle track support
- <li>Parental control PIN challenge
- <li>Allow TV Input UI overlay for:
+ <li> Access and navigate all TV channels
+ <li> Access TV program information bar
+ <li> Display Electronic Programming Guide (EPG) data
+ <li> Support multiple audio and subtitle track support
+ <li> Supply parental control PIN challenge
+ <li> Allow TV Input UI overlay for:
<ul>
- <li>TV standard (HbbTV, etc.)
+ <li> TV standard (HbbTV, etc.)
</ul>
+ <li> Populate search results for TV channels and programs
+ <li> Display app linking cards
+ <li> Support timeshifting APIs
+</ul>
+
+<p>This feature set will increase in line with new Android versions
+where the platform TIF APIs are extended. CTS Verifier provides the
+compatibility test coverage. </p>
+
+<h3 id=support_for_third-party_tv_inputs>Support for third-party TV Inputs</h3>
+
+
+<p>Android TV provides developer APIs for third-party TV inputs, enabling
+installed apps to deliver software channels into the live TV experience. To
+ensure a compatible Android device implementation, the system TV App has some
+responsibilities regarding surfacing third-party TV inputs and channels to the
+user. The reference Live Channels app provides a compatible implementation; if
+replacing the system TV App, device manufacturers must ensure their own apps
+provide similar compatibility, to meet developer expectations across all
+Android TV devices.</p>
+
+<p>The system TV App must surface third-party inputs alongside the device's
+default live TV service (even if the default live TV service is not using TIF).
+The promise of the developer APIs is that users will be able to find channels
+(once installed) within their standard TV experience.</p>
+
+<p>Visual differentiation between built-in channels and third-party channels is
+allowed, as defined in the TV App section of the Android CDD.</p>
+
+<p>The following sections show how the Live Channels application fulfills the CDD
+requirements.</p>
+
+<h4 id=new_channel_setup>New channel setup</h4>
+
+
+<p>The addition of new third-party inputs/channels begins with the user finding
+and installing a TV Input from an
+application store, such as Google Play.</p>
+
+<p>Some third-party TV inputs automatically add channels to the TvProvider
+database. However most will provide a Setup activity to enable the user to set
+up their channels, provide login details, and other actions. The system TV App
+needs to ensure the user can activate this Setup activity, which is why the CDD
+requires third-party inputs be minimal navigation actions away from the main TV
+App.</p>
+
+<p>The reference Live Channels app provides the Channel Sources menu for accessing
+inputs.</p>
+
+
+<p>See <a href="http://developer.android.com/training/tv/tif/tvinput.html#setup">Define You TV Input Sevice</a>
+for developer expectations in this area.</p>
+
+<h4 id=customize_the_channel_list>Customize the channel list</h4>
+
+
+<p>Device manufacturers may provide a UI to hide certain channels and
+enable users to manage their own EPGs. Live Channels includes this facility.</p>
+
+
+<h4 id=epg>EPG</h4>
+
+
+<p>Third-party input developers need to have confidence that users can easily
+navigate to their channels during general usage, across all compatible Android
+TV devices.</p>
+
+<p>Channels from third-party inputs must be presented as part of the device's
+standard live TV experience EPG. Visual separation or separate categories for
+third-party channels can be used (see the TV App section of the Android CDD)—what's key
+is that users are able to find the channels they have installed. </p>
+
+<h4 id=search>Search</h4>
+
+
+<p>Manufacturers must implement the TV App to include search results for global
+search requests in order to ensure the best user experience. Live Channels 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
+compatibility) as well as built-in inputs.</p>
+
+<h3 id=useful_resources>Useful resources</h3>
+
+
+<ul>
+ <li> The <a href="{@docRoot}compatibility/android-cdd.pdf">Android CDD</a>
+ and documented developer APIs are the definitive references.
+ <li> CTS Verifier exercises the APIs as part of the compatibility testing program.
+Running this against Live Channels 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>
+ for developer expectations in this area.
</ul>
<h2 id="parental_control">Parental Control</h2>
diff --git a/src/devices/tv/reference-tv-app.jd b/src/devices/tv/reference-tv-app.jd
new file mode 100644
index 0000000..fe8d601
--- /dev/null
+++ b/src/devices/tv/reference-tv-app.jd
@@ -0,0 +1,176 @@
+page.title=Reference TV App
+@jd:body
+
+<!--
+ Copyright 2015 The Android Open Source Project
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+<div id="qv-wrapper">
+ <div id="qv">
+ <h2>In this document</h2>
+ <ol id="auto-toc">
+ </ol>
+ </div>
+</div>
+
+
+<p>A TV application that plays live TV content is required for Android TV devices.
+A reference TV application (<a href="https://play.google.com/store/apps/details?id=com.google.android.tv">Live Channels</a>) is provided alongside the Android platform, which can be used as-is,
+customized, extended, or replaced. The <a href="https://android.googlesource.com/platform/packages/apps/TV/">source code</a> is available in the Android Open Source Project.</p>
+
+<p>This article summarizes how to get started with building a system TV App based
+on Live Channels on your Android television device and covers a couple of ways
+to customize the app. (You may extend your TV application to implement device
+manufacturer or country-specific features, however this is not in the scope of
+the reference TV App.)</p>
+
+<h2 id=dependencies>Dependencies</h2>
+
+
+<p>The TV application is a component of the <a href="{@docRoot}devices/tv/">TV Input Framework</a> (TIF) and cannot be used independently of the other components. This means
+that only devices with TIF will be able to run the <a href="https://play.google.com/store/apps/details?id=com.google.android.tv">Live Channels</a> application.</p>
+
+<p>The Live Channels application depends on Android APIs. Different branches have
+different dependencies on API levels:</p>
+
+<p class="table-caption" id="table-1">
+ <strong>Table 1.</strong> Live Channels branches.</p>
+<table>
+ <tr>
+ <th>Branch</th>
+ <th>API level</th>
+ </tr>
+ <tr>
+ <td><a href="https://android.googlesource.com/platform/packages/apps/TV/+/android-live-tv">android-live-tv</a></td>
+ <td>23 (Android 6.0)</td>
+ </tr>
+ <tr>
+ <td><a href="https://android.googlesource.com/platform/packages/apps/TV/+/android-live-tv-l-mr1">android-live-tv-l-mr1</a></td>
+ <td>22 (Android 5.1)</td>
+ </tr>
+</table>
+
+
+<p>There is no runtime dependency on the API level as the code is
+retro-compatible. The same APK can be used for devices with Android 5.1 and 6.0
+as runtime checks will enable/disable features with dependencies on Android 6.0
+APIs.</p>
+
+<h2 id=get_the_source>Get the source</h2>
+
+
+<p>To get started, select which version of Live Channels you’d like from Git. The
+instructions below are for the current version of Live Channels, but you can
+easily select an earlier version by appending the version name to the end of
+<code>android-live-tv</code> as seen in the table above.</p>
+
+
+<pre>
+$ mkdir android-live-tv && cd android-live-tv
+$ repo init -u <a href="https://android.googlesource.com/platform/manifest">https://android.googlesource.com/platform/manifest</a> -b android-live-tv
+$ repo sync -j8 -c
+</pre>
+
+
+<h2 id=build>Build</h2>
+
+
+<p>To build the Live Channels code, run:</p>
+
+<pre>
+$ . build/envsetup.sh
+$ tapas TV x86
+$ make LiveTv
+</pre>
+
+
+<h2 id=push>Push</h2>
+
+
+<p>To push Live Channels to your test device:</p>
+
+<pre>
+$ adb install -r -d $OUT/system/priv-app/LiveTv/LiveTv.apk
+</pre>
+
+
+<h2 id=test>Test</h2>
+
+
+<p>Once Live Channels is on your device, you should test that it is properly
+integrated. In addition to running the <a href="{@docRoot}compatibility/cts/index.html">Compatibility test suite</a> and the <a href="http://source.android.com/compatibility/cts/verifier.html">CTS Verifier tests</a> for the TV app, you can use these tests below:</p>
+
+<h3 id=unit_tests>Unit tests</h3>
+
+
+<p>There are unit and functional tests for the Live Channels app. You must have a
+device (or emulator) connected to run the tests.</p>
+
+<pre>
+$ adb shell logcat -c
+m LiveTv TVTestInput TVUnitTests -j20 &&\
+adb install -r -d $OUT/system/priv-app/LiveTv/LiveTv.apk &&\
+adb install -r -d $OUT/system/app/TVTestInput/TVTestInput.apk && \
+adb install -r -d $OUT/data/app/TVUnitTests/TVUnitTests.apk && \
+adb shell pm clear <a href="http://com.android.providers.tv/">com.android.providers.tv</a> && \
+adb shell pm clear <a href="http://com.google.android.tv/">com.google.android.tv</a> && \
+adb shell am instrument \
+ -e testSetupMode unit \
+ -w com.android.tv.testinput/.instrument.TestSetupInstrumentation &&\
+adb shell input keyevent KEYCODE_HOME &&\
+adb shell am instrument \
+ -w 'com.android.tv.tests/android.support.test.runner.AndroidJUnitRunner'
+</pre>
+
+
+<h3 id=functional_tests>Functional Tests</h3>
+
+<pre>
+$ adb shell logcat -c
+m LiveTv TVTestInput TVFuncTests -j20 &&\
+adb install -r -d $OUT/system/priv-app/LiveTv/LiveTv.apk &&\
+adb install -r -d $OUT/system/app/TVTestInput/TVTestInput.apk && \
+adb install -r -d $OUT/data/app/TVFuncTests/TVFuncTests.apk && \
+adb shell pm clear <a href="http://com.android.providers.tv/">com.android.providers.tv</a> && \
+adb shell pm clear <a href="http://com.google.android.tv/">com.google.android.tv</a> && \
+adb shell am instrument \
+ -e testSetupMode func \
+ -w com.android.tv.testinput/.instrument.TestSetupInstrumentation &&\
+adb shell input keyevent KEYCODE_HOME &&\
+adb shell am instrument \
+ -w 'com.android.tv.tests.ui/android.support.test.runner.AndroidJUnitRunner'
+</pre>
+
+
+<h3 id=jank_tests>Jank Tests</h3>
+
+
+<p>The Jank tests look for dropped frames and delays in rendering.</p>
+
+<pre>
+$ adb shell logcat -c
+m LiveTv TVTestInput TVJankTests -j20 &&\
+adb install -r -d $OUT/system/priv-app/LiveTv/LiveTv.apk &&\
+adb install -r -d $OUT/system/app/TVTestInput/TVTestInput.apk &&\
+adb install -r -d $OUT/data/app/TVJankTests/TVJankTests.apk &&\
+adb shell pm clear <a href="http://com.android.providers.tv/">com.android.providers.tv</a> &&\
+adb shell pm clear <a href="http://com.google.android.tv/">com.google.android.tv</a> &&\
+echo "Creating a lot of channels and EPG data, this may take a while" &&\
+adb shell am instrument \
+ -e testSetupMode jank \
+ -w com.android.tv.testinput/.instrument.TestSetupInstrumentation &&\
+adb shell input keyevent KEYCODE_HOME &&\
+adb shell am instrument \
+ -w 'com.android.tv.tests.jank/android.support.test.runner.AndroidJUnitRunner'
+</pre>
