1page.title=Developing a TV Input Service 2page.tags=tv, tif 3helpoutsWidget=true 4 5trainingnavtop=true 6 7@jd:body 8 9<div id="tb-wrapper"> 10<div id="tb"> 11 <h2>This lesson teaches you to</h2> 12 <ol> 13 <li><a href="#manifest">Declare Your TV Input Service in the Manifest</a></li> 14 <li><a href="#tvinput">Define Your TV Input Service</a></li> 15 <li><a href="#setup">Define Your Setup Activity</a></li> 16 </ol> 17 <h2>You should also read</h2> 18 <ul> 19 <li><a href="{@docRoot}reference/android/media/tv/package-summary.html"> 20 android.media.tv</a></li> 21 <li><a class="external-lin" href="http://source.android.com/devices/tv/index.html"> 22 TV Input Framework</a></li> 23 </ul> 24 <h2>Try It Out</h2> 25 <ul> 26 <li><a class="external-link" href="https://github.com/googlesamples/androidtv-sample-inputs"> 27 TV Input Service sample app</a></li> 28 </ul> 29</div> 30</div> 31 32<p>A TV input service represents a media stream source, and lets you present your media content in a 33linear, broadcast TV fashion as channels and programs. With the TV input service, you can provide 34parental controls, program guide information, and content ratings. The TV input service works 35with the Android system TV app, developed for the device and immutable by third-party apps, which 36ultimately controls and presents content on the TV. See 37<a class="external-link" href="http://source.android.com/devices/tv/index.html"> 38TV Input Framework</a> for more information about the framework architecture and its components.</p> 39 40<p>To develop a TV input service, you implement the following components:</p> 41 42<ul> 43 <li>{@link android.media.tv.TvInputService} provides long-running and background availability for 44 the TV input</li> 45 <li>{@link android.media.tv.TvInputService.Session} maintains the TV input state and communicates 46 with the hosting app</li> 47 <li>{@link android.media.tv.TvContract} describes the channels and programs available to the TV 48 input</li> 49 <li>{@link android.media.tv.TvContract.Channels} represents information about a TV channel</li> 50 <li>{@link android.media.tv.TvContract.Programs} describes a TV program with data such as program 51 title and start time</li> 52 <li>{@link android.media.tv.TvTrackInfo} represents an audio, video, or subtitle track</li> 53 <li>{@link android.media.tv.TvContentRating} describes a content rating, allows for custom content 54 rating schemes</li> 55 <li>{@link android.media.tv.TvInputManager} provides an API to the system TV app and manages 56 the interaction with TV inputs and apps</li> 57</ul> 58 59<h2 id="manifest">Declare Your TV Input Service in the Manifest</h2> 60 61<p>Your app manifest must declare your {@link android.media.tv.TvInputService}. Within that 62declaration, specify the {@link android.Manifest.permission#BIND_TV_INPUT} permission to allow the 63service to connect the TV input to the system. A system service (<code>TvInputManagerService</code>) 64performs the binding and has that permission. The system TV app sends requests to TV input services 65via the {@link android.media.tv.TvInputManager} interface. The service declaration must also 66include an intent filter that specifies the {@link android.media.tv.TvInputService} 67as the action to perform with the intent. Also within the service declaration, declare the service 68meta data in a separate XML resource. The service declaration, the intent filter and the service 69meta data are described in the following example.</p> 70 71<pre> 72<service android:name="com.example.sampletvinput.SampleTvInput" 73 android:label="@string/sample_tv_input_label" 74 android:permission="android.permission.BIND_TV_INPUT"> 75 <intent-filter> 76 <action android:name="android.media.tv.TvInputService" /> 77 </intent-filter> 78 <meta-data android:name="android.media.tv.input" 79 android:resource="@xml/sample_tv_input" /> 80</service> 81</pre> 82 83<p>Define the service meta data in separate XML file, as shown in the following example. The service 84meta data must include a setup interface that describes the TV input's initial configuration and 85channel scan. The service meta data file is located in the XML resources directory 86for your application and must match the name of the resource in the manifest. Using the example 87manifest entries above, you would create an XML file in the location 88<code>res/xml/sample_tv_input.xml</code>, with the following contents:</p> 89 90<pre> 91<tv-input xmlns:android="http://schemas.android.com/apk/res/android" 92 android:setupActivity="com.example.sampletvinput.SampleTvInputSetupActivity" /> 93</pre> 94 95<h2 id="tvinput">Define Your TV Input Service</h2> 96 97<div class="figure"> 98<img id="tvinputlife" src="{@docRoot}images/tv/tvinput-life.png" alt=""/> 99<p class="img-caption"><strong>Figure 1.</strong>TvInputService lifecycle.</p> 100</div> 101 102<p>For your service, you extend the {@link android.media.tv.TvInputService} class. A 103{@link android.media.tv.TvInputService} implementation is a 104<a href="{@docRoot}guide/components/bound-services.html">bound service</a> where the system service 105(<code>TvInputManagerService</code>) is the client that binds to it. The service life cycle methods 106you need to implement are illustrated in figure 1.</p> 107 108<p>The {@link android.app.Service#onCreate()} method initializes and starts the 109{@link android.os.HandlerThread} which provides a process thread separate from the UI thread to 110handle system-driven actions. In the following example, the {@link android.app.Service#onCreate()} 111method initializes the {@link android.view.accessibility.CaptioningManager} and prepares to handle 112the {@link android.media.tv.TvInputManager#ACTION_BLOCKED_RATINGS_CHANGED} 113and {@link android.media.tv.TvInputManager#ACTION_PARENTAL_CONTROLS_ENABLED_CHANGED} actions. These 114actions describe system intents fired when the user changes the parental control settings, and when 115there is a change on the list of blocked ratings.</p> 116 117<pre> 118@Override 119public void onCreate() { 120 super.onCreate(); 121 mHandlerThread = new HandlerThread(getClass() 122 .getSimpleName()); 123 mHandlerThread.start(); 124 mDbHandler = new Handler(mHandlerThread.getLooper()); 125 mHandler = new Handler(); 126 mCaptioningManager = (CaptioningManager) 127 getSystemService(Context.CAPTIONING_SERVICE); 128 129 setTheme(android.R.style.Theme_Holo_Light_NoActionBar); 130 131 mSessions = new ArrayList<BaseTvInputSessionImpl>(); 132 IntentFilter intentFilter = new IntentFilter(); 133 intentFilter.addAction(TvInputManager 134 .ACTION_BLOCKED_RATINGS_CHANGED); 135 intentFilter.addAction(TvInputManager 136 .ACTION_PARENTAL_CONTROLS_ENABLED_CHANGED); 137 registerReceiver(mBroadcastReceiver, intentFilter); 138} 139</pre> 140 141<p> See <a href="{@docRoot}training/tv/tif/ui.html#control"> 142Control Content</a> for more information about working with blocked content and providing 143parental control. See {@link android.media.tv.TvInputManager} for more system-driven actions that 144you may want to handle in your TV input service.</p> 145 146<p>The {@link android.media.tv.TvInputService} creates a 147{@link android.media.tv.TvInputService.Session} that implements {@link android.os.Handler.Callback} 148to handle player state changes. With {@link android.media.tv.TvInputService.Session#onSetSurface(android.view.Surface) onSetSurface()}, 149the {@link android.media.tv.TvInputService.Session} sets the {@link android.view.Surface} with the 150video content. See <a href="{@docRoot}training/tv/tif/ui.html#surface">Integrate Player with Surface</a> 151for more information about working with {@link android.view.Surface} to render video.</p> 152 153<p>The {@link android.media.tv.TvInputService.Session} handles the 154{@link android.media.tv.TvInputService.Session#onTune(android.net.Uri) onTune()} 155event when the user selects a channel, and notifies the system TV app for changes in the content and 156content meta data. These <code>notify()</code> methods are described in 157<a href="{@docRoot}training/tv/tif/ui.html#control"> 158Control Content</a> and <a href="{@docRoot}training/tv/tif/ui.html#track">Handle Track Selection</a> 159further in this training.</p> 160 161<h2 id="setup">Define Your Setup Activity</h2> 162 163<p>The system TV app works with the setup activity you define for your TV input. The 164setup activity is required and must provide at least one channel record for the system database. The 165system TV app will invoke the setup activity when it cannot find a channel for the TV input. 166<p>The setup activity describes to the system TV app the channels made available through the TV 167input, as demonstrated in the next lesson, <a href="{@docRoot}training/tv/tif/channel.html">Creating 168and Updating Channel Data</a>.</p> 169
