1 page.title=Developing a TV Input Service 2 page.tags=tv, tif 3 helpoutsWidget=true 4 5 trainingnavtop=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 33 linear, broadcast TV fashion as channels and programs. With the TV input service, you can provide 34 parental controls, program guide information, and content ratings. The TV input service works 35 with the Android system TV app, developed for the device and immutable by third-party apps, which 36 ultimately controls and presents content on the TV. See 37 <a class="external-link" href="http://source.android.com/devices/tv/index.html"> 38 TV 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 62 declaration, specify the {@link android.Manifest.permission#BIND_TV_INPUT} permission to allow the 63 service to connect the TV input to the system. A system service (<code>TvInputManagerService</code>) 64 performs the binding and has that permission. The system TV app sends requests to TV input services 65 via the {@link android.media.tv.TvInputManager} interface. The service declaration must also 66 include an intent filter that specifies the {@link android.media.tv.TvInputService} 67 as the action to perform with the intent. Also within the service declaration, declare the service 68 meta data in a separate XML resource. The service declaration, the intent filter and the service 69 meta 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 84 meta data must include a setup interface that describes the TV input's initial configuration and 85 channel scan. The service meta data file is located in the XML resources directory 86 for your application and must match the name of the resource in the manifest. Using the example 87 manifest 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 106 you 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 110 handle system-driven actions. In the following example, the {@link android.app.Service#onCreate()} 111 method initializes the {@link android.view.accessibility.CaptioningManager} and prepares to handle 112 the {@link android.media.tv.TvInputManager#ACTION_BLOCKED_RATINGS_CHANGED} 113 and {@link android.media.tv.TvInputManager#ACTION_PARENTAL_CONTROLS_ENABLED_CHANGED} actions. These 114 actions describe system intents fired when the user changes the parental control settings, and when 115 there is a change on the list of blocked ratings.</p> 116 117 <pre> 118 @Override 119 public 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"> 142 Control Content</a> for more information about working with blocked content and providing 143 parental control. See {@link android.media.tv.TvInputManager} for more system-driven actions that 144 you 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} 148 to handle player state changes. With {@link android.media.tv.TvInputService.Session#onSetSurface(android.view.Surface) onSetSurface()}, 149 the {@link android.media.tv.TvInputService.Session} sets the {@link android.view.Surface} with the 150 video content. See <a href="{@docRoot}training/tv/tif/ui.html#surface">Integrate Player with Surface</a> 151 for 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()} 155 event when the user selects a channel, and notifies the system TV app for changes in the content and 156 content meta data. These <code>notify()</code> methods are described in 157 <a href="{@docRoot}training/tv/tif/ui.html#control"> 158 Control Content</a> and <a href="{@docRoot}training/tv/tif/ui.html#track">Handle Track Selection</a> 159 further 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 164 setup activity is required and must provide at least one channel record for the system database. The 165 system 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 167 input, as demonstrated in the next lesson, <a href="{@docRoot}training/tv/tif/channel.html">Creating 168 and Updating Channel Data</a>.</p> 169
