src/devices/tv/reference-tv-app.jd - platform/docs/source.android.com - Git at Google

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