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 Setup and Settings Activities</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. Also, the service meta data may (optionally) describe a settings activity for users to 86modify the TV input's behavior. The service meta data file is located in the XML resources directory 87for your application and must match the name of the resource in the manifest. Using the example 88manifest entries above, you would create an XML file in the location 89<code>res/xml/sample_tv_input.xml</code>, with the following contents:</p> 90 91<pre> 92<tv-input xmlns:android="http://schemas.android.com/apk/res/android" 93 <!-- Required: activity for setting up the input --> 94 android:setupActivity="com.example.sampletvinput.SampleTvInputSetupActivity" 95 <!-- Optional: activity for controlling the settings --> 96 android:settingsActivity="com.example.sampletvinput.SampleTvInputSettingsActivity" /> 97</pre> 98 99<h2 id="tvinput">Define Your TV Input Service</h2> 100 101<div class="figure"> 102<img id="tvinputlife" src="{@docRoot}images/tv/tvinput-life.png" alt=""/> 103<p class="img-caption"><strong>Figure 1.</strong>TvInputService lifecycle.</p> 104</div> 105 106<p>For your service, you extend the {@link android.media.tv.TvInputService} class. A 107{@link android.media.tv.TvInputService} implementation is a 108<a href="{@docRoot}guide/components/bound-services.html">bound service</a> where the system service 109(<code>TvInputManagerService</code>) is the client that binds to it. The service life cycle methods 110you need to implement are illustrated in figure 1.</p> 111 112<p>The {@link android.app.Service#onCreate()} method initializes and starts the 113{@link android.os.HandlerThread} which provides a process thread separate from the UI thread to 114handle system-driven actions. In the following example, the {@link android.app.Service#onCreate()} 115method initializes the {@link android.view.accessibility.CaptioningManager} and prepares to handle 116the {@link android.media.tv.TvInputManager#ACTION_BLOCKED_RATINGS_CHANGED} 117and {@link android.media.tv.TvInputManager#ACTION_PARENTAL_CONTROLS_ENABLED_CHANGED} actions. These 118actions describe system intents fired when the user changes the parental control settings, and when 119there is a change on the list of blocked ratings.</p> 120 121<pre> 122@Override 123public void onCreate() { 124 super.onCreate(); 125 mHandlerThread = new HandlerThread(getClass() 126 .getSimpleName()); 127 mHandlerThread.start(); 128 mDbHandler = new Handler(mHandlerThread.getLooper()); 129 mHandler = new Handler(); 130 mCaptioningManager = (CaptioningManager) 131 getSystemService(Context.CAPTIONING_SERVICE); 132 133 setTheme(android.R.style.Theme_Holo_Light_NoActionBar); 134 135 mSessions = new ArrayList<BaseTvInputSessionImpl>(); 136 IntentFilter intentFilter = new IntentFilter(); 137 intentFilter.addAction(TvInputManager 138 .ACTION_BLOCKED_RATINGS_CHANGED); 139 intentFilter.addAction(TvInputManager 140 .ACTION_PARENTAL_CONTROLS_ENABLED_CHANGED); 141 registerReceiver(mBroadcastReceiver, intentFilter); 142} 143</pre> 144 145<p> See <a href="{@docRoot}training/tv/tif/ui.html#control"> 146Control Content</a> for more information about working with blocked content and providing 147parental control. See {@link android.media.tv.TvInputManager} for more system-driven actions that 148you may want to handle in your TV input service.</p> 149 150<p>The {@link android.media.tv.TvInputService} creates a 151{@link android.media.tv.TvInputService.Session} that implements {@link android.os.Handler.Callback} 152to handle player state changes. With {@link android.media.tv.TvInputService.Session#onSetSurface(android.view.Surface) onSetSurface()}, 153the {@link android.media.tv.TvInputService.Session} sets the {@link android.view.Surface} with the 154video content. See <a href="{@docRoot}training/tv/tif/ui.html#surface">Integrate Player with Surface</a> 155for more information about working with {@link android.view.Surface} to render video.</p> 156 157<p>The {@link android.media.tv.TvInputService.Session} handles the 158{@link android.media.tv.TvInputService.Session#onTune(android.net.Uri) onTune()} 159event when the user selects a channel, and notifies the system TV app for changes in the content and 160content meta data. These <code>notify()</code>code> methods are described in 161<a href="{@docRoot}training/tv/tif/ui.html#control"> 162Control Content</a> and <a href="training/tv/tif/ui.html#track">Handle Track Selection</a> further 163in this training.</p> 164 165<h2 id="setup">Define Setup and Settings Activities</h2> 166 167<p>The system TV app works with the setup and settings activities you define for your TV input. The 168setup activity is required and must provide at least one channel record for the system database. The 169system TV app will invoke the setup activity when it cannot find a channel for the TV input. 170<p>The setup activity describes to the system TV app the channels made available through the TV 171input, as demonstrated in the next lesson, <a href="{@docRoot}training/tv/tif/channel.html">Creating 172and Updating Channel Data</a>.</p> 173 174<p>The settings activity is optional. You can define a settings activity to turn on parental 175controls, enable closed captions, set the display attributes, and so forth.</p> 176 177 178
