开发电视输入服务

电视输入服务表示媒体流源，允许您以线性、广播电视的方式呈现媒体内容作为频道和节目。通过电视输入服务，您可以提供家长控制、节目指南信息和内容分级。电视输入服务与 Android 系统电视应用协同工作。此应用最终控制并在电视上呈现频道内容。系统电视应用专为设备开发，第三方应用不可更改。有关电视输入框架 (TIF) 架构及其组件的更多信息，请参阅电视输入框架。

使用 TIF 辅助库创建电视输入服务

TIF 辅助库是一个框架，它提供了常见电视输入服务功能的可扩展实现。它仅供 OEM 在 Android 5.0 (API 级别 21) 到 Android 7.1 (API 级别 25) 之间构建频道时使用。

更新您的项目

TIF 辅助库可在 androidtv-sample-inputs 仓库中供 OEM 旧版使用。请参阅该仓库以获取如何在应用中包含该库的示例。

在清单中声明您的电视输入服务

您的应用必须提供一个与 TvInputService 兼容的服务，系统使用该服务来访问您的应用。TIF 辅助库提供了 BaseTvInputService 类，该类提供了 TvInputService 的默认实现，您可以对其进行自定义。创建一个 BaseTvInputService 的子类，并在您的清单中将其声明为服务。

在清单声明中，指定 BIND_TV_INPUT 权限，以允许服务将电视输入连接到系统。系统服务执行绑定并具有 BIND_TV_INPUT 权限。系统电视应用通过 TvInputManager 接口向电视输入服务发送请求。

在您的服务声明中，包含一个意图过滤器，该过滤器将 TvInputService 指定为要用意图执行的操作。还要将服务元数据声明为单独的 XML 资源。服务声明、意图过滤器和服务元数据声明如以下示例所示

<service android:name=".rich.RichTvInputService"
    android:label="@string/rich_input_label"
    android:permission="android.permission.BIND_TV_INPUT">
    <!-- Required filter used by the system to launch our account service. -->
    <intent-filter>
        <action android:name="android.media.tv.TvInputService" />
    </intent-filter>
    <!-- An XML file which describes this input. This provides pointers to
    the RichTvInputSetupActivity to the system/TV app. -->
    <meta-data
        android:name="android.media.tv.input"
        android:resource="@xml/richtvinputservice" />
</service>

在单独的 XML 文件中定义服务元数据。服务元数据 XML 文件必须包含一个设置接口，该接口描述电视输入的初始配置和频道扫描。元数据文件还应包含一个标志，说明用户是否可以录制内容。有关如何在应用中支持内容录制的更多信息，请参阅支持内容录制。

服务元数据文件位于您应用的 XML 资源目录中，并且必须与您在清单中声明的资源名称匹配。使用前一个示例中的清单条目，您将在 res/xml/richtvinputservice.xml 创建 XML 文件，内容如下

<?xml version="1.0" encoding="utf-8"?>
<tv-input xmlns:android="http://schemas.android.com/apk/res/android"
  android:canRecord="true"
  android:setupActivity="com.example.android.sampletvinput.rich.RichTvInputSetupActivity" />

定义频道并创建您的设置活动

您的电视输入服务必须定义至少一个用户通过系统电视应用访问的频道。您应该在系统数据库中注册您的频道，并提供一个设置活动，当系统找不到您的应用频道时会调用该活动。

首先，使您的应用能够读取和写入系统电子节目指南 (EPG)，其数据包括可供用户使用的频道和节目。要使您的应用能够执行这些操作，并在设备重启后与 EPG 同步，请将以下元素添加到您的应用清单中

<uses-permission android:name="com.android.providers.tv.permission.WRITE_EPG_DATA" />
<uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED "/>

添加以下元素以确保您的应用在 Google Play 商店中显示为在 Android TV 中提供内容频道的应用

<uses-feature
    android:name="android.software.live_tv"
    android:required="true" />

接下来，创建一个继承 EpgSyncJobService 类的类。这个抽象类使得创建在系统数据库中创建和更新频道的作业服务变得容易。

在您的子类中，在 getChannels() 中创建并返回您的完整频道列表。如果您的频道来自 XMLTV 文件，请使用 XmlTvParser 类。否则，使用 Channel.Builder 类以编程方式生成频道。

对于每个频道，当系统需要在一个给定时间窗口内在该频道上可观看的节目列表时，它会调用 getProgramsForChannel()。返回该频道的 Program 对象列表。使用 XmlTvParser 类从 XMLTV 文件获取节目，或者使用 Program.Builder 类以编程方式生成它们。

对于每个 Program 对象，使用 InternalProviderData 对象设置节目信息，例如节目的视频类型。如果您只有有限数量的节目想要在频道中循环重复播放，则在设置节目信息时，将 InternalProviderData.setRepeatable() 方法的值设置为 true。

实现作业服务后，将其添加到您的应用清单中

<service
    android:name=".sync.SampleJobService"
    android:permission="android.permission.BIND_JOB_SERVICE"
    android:exported="true" />

最后，创建一个设置活动。您的设置活动应提供同步频道和节目数据的方法。一种方法是让用户通过活动中的 UI 来完成。您也可以让应用在活动启动时自动执行此操作。当设置活动需要同步频道和节目信息时，应用应启动作业服务

val inputId = getActivity().intent.getStringExtra(TvInputInfo.EXTRA_INPUT_ID)
EpgSyncJobService.cancelAllSyncRequests(getActivity())
EpgSyncJobService.requestImmediateSync(
        getActivity(),
        inputId,
        ComponentName(getActivity(), SampleJobService::class.java)
)

String inputId = getActivity().getIntent().getStringExtra(TvInputInfo.EXTRA_INPUT_ID);
EpgSyncJobService.cancelAllSyncRequests(getActivity());
EpgSyncJobService.requestImmediateSync(getActivity(), inputId,
        new ComponentName(getActivity(), SampleJobService.class));

使用 requestImmediateSync() 方法同步作业服务。用户必须等待同步完成，因此您应该将请求周期保持相对较短。

使用 setUpPeriodicSync() 方法让作业服务在后台定期同步频道和节目数据

EpgSyncJobService.setUpPeriodicSync(
        context,
        inputId,
        ComponentName(context, SampleJobService::class.java)
)

EpgSyncJobService.setUpPeriodicSync(context, inputId,
        new ComponentName(context, SampleJobService.class));

TIF 辅助库提供了 requestImmediateSync() 的一个额外重载方法，允许您指定要同步的频道数据持续时间（以毫秒为单位）。默认方法同步一小时的频道数据。

TIF 辅助库还提供了 setUpPeriodicSync() 的一个额外重载方法，允许您指定要同步的频道数据持续时间，以及周期性同步的发生频率。默认方法每 12 小时同步 48 小时的频道数据。

有关频道数据和 EPG 的更多详细信息，请参阅使用频道数据。

处理调谐请求和媒体播放

当用户选择特定频道时，系统电视应用会使用您的应用创建的 Session 来调谐到请求的频道并播放内容。TIF 辅助库提供了几个您可以扩展的类，用于处理来自系统的频道和会话调用。

您的 BaseTvInputService 子类会创建处理调谐请求的会话。重写 onCreateSession() 方法，创建一个从 BaseTvInputService.Session 类扩展的会话，然后使用您的新会话调用 super.sessionCreated()。在以下示例中，onCreateSession() 返回一个扩展 BaseTvInputService.Session 的 RichTvInputSessionImpl 对象

override fun onCreateSession(inputId: String): Session =
        RichTvInputSessionImpl(this, inputId).apply {
            setOverlayViewEnabled(true)
        }

@Override
public final Session onCreateSession(String inputId) {
    RichTvInputSessionImpl session = new RichTvInputSessionImpl(this, inputId);
    session.setOverlayViewEnabled(true);
    return session;
}

当用户使用系统电视应用开始观看您的某个频道时，系统会调用您的会话的 onPlayChannel() 方法。如果您需要在节目开始播放之前进行任何特殊的频道初始化，请重写此方法。

系统随后获取当前计划的节目，并调用您的会话的 onPlayProgram() 方法，指定节目信息和开始时间（以毫秒为单位）。使用 TvPlayer 接口开始播放节目。

您的媒体播放器代码应实现 TvPlayer 以处理特定的播放事件。TvPlayer 类处理时移控制等功能，而不会增加您的 BaseTvInputService 实现的复杂性。

在您会话的 getTvPlayer() 方法中，返回实现 TvPlayer 的媒体播放器。电视输入服务示例应用实现了一个使用 ExoPlayer 的媒体播放器。

使用电视输入框架创建电视输入服务

如果您的电视输入服务无法使用 TIF 辅助库，则需要实现以下组件

• TvInputService 为电视输入提供长期运行和后台可用性
• TvInputService.Session 维护电视输入状态并与托管应用通信
• TvContract 描述了电视输入可用的频道和节目
• TvContract.Channels 表示有关电视频道的信息
• TvContract.Programs 描述电视节目，包括节目标题和开始时间等数据
• TvTrackInfo 表示音频、视频或字幕轨道
• TvContentRating 描述内容分级，允许自定义内容分级方案
• TvInputManager 为系统电视应用提供 API，并管理与电视输入和应用的交互

您还需要执行以下操作

1. 在清单中声明您的电视输入服务，如在清单中声明您的电视输入服务中所述。
2. 创建服务元数据文件。
3. 创建并注册您的频道和节目信息。
4. 创建您的设置活动。

定义您的电视输入服务

对于您的服务，您需要扩展 TvInputService 类。TvInputService 的实现是一个绑定服务，其中系统服务是绑定到它的客户端。您需要实现的服务生命周期方法如图 1 所示。

onCreate() 方法初始化并启动 HandlerThread，它提供一个独立于 UI 线程的进程线程来处理系统驱动的操作。在以下示例中，onCreate() 方法初始化 CaptioningManager 并准备处理 ACTION_BLOCKED_RATINGS_CHANGED 和 ACTION_PARENTAL_CONTROLS_ENABLED_CHANGED 操作。这些操作描述了当用户更改家长控制设置时以及当被阻止的分级列表发生更改时触发的系统意图。

override fun onCreate() {
    super.onCreate()
    handlerThread = HandlerThread(javaClass.simpleName).apply {
        start()
    }
    dbHandler = Handler(handlerThread.looper)
    handler = Handler()
    captioningManager = getSystemService(Context.CAPTIONING_SERVICE) as CaptioningManager

    setTheme(android.R.style.Theme_Holo_Light_NoActionBar)

    sessions = mutableListOf<BaseTvInputSessionImpl>()
    val intentFilter = IntentFilter().apply {
        addAction(TvInputManager.ACTION_BLOCKED_RATINGS_CHANGED)
        addAction(TvInputManager.ACTION_PARENTAL_CONTROLS_ENABLED_CHANGED)
    }
    registerReceiver(broadcastReceiver, intentFilter)
}

@Override
public void onCreate() {
    super.onCreate();
    handlerThread = new HandlerThread(getClass()
      .getSimpleName());
    handlerThread.start();
    dbHandler = new Handler(handlerThread.getLooper());
    handler = new Handler();
    captioningManager = (CaptioningManager)
      getSystemService(Context.CAPTIONING_SERVICE);

    setTheme(android.R.style.Theme_Holo_Light_NoActionBar);

    sessions = new ArrayList<BaseTvInputSessionImpl>();
    IntentFilter intentFilter = new IntentFilter();
    intentFilter.addAction(TvInputManager
      .ACTION_BLOCKED_RATINGS_CHANGED);
    intentFilter.addAction(TvInputManager
      .ACTION_PARENTAL_CONTROLS_ENABLED_CHANGED);
    registerReceiver(broadcastReceiver, intentFilter);
}

图 1.TvInputService 生命周期。

有关处理被阻止内容和提供家长控制的更多信息，请参阅控制内容。有关您可能希望在电视输入服务中处理的更多系统驱动操作，请参阅 TvInputManager。

TvInputService 创建一个实现 Handler.Callback 的 TvInputService.Session 来处理播放器状态更改。通过 onSetSurface()，TvInputService.Session 使用视频内容设置 Surface。有关使用 Surface 渲染视频的更多信息，请参阅将播放器与 Surface 集成。

TvInputService.Session 处理用户选择频道时的 onTune() 事件，并通知系统电视应用内容和内容元数据的更改。这些 notify() 方法在本培训的控制内容和处理轨道选择中进一步描述。

定义您的设置活动

系统电视应用与您为电视输入定义的设置活动协同工作。设置活动是必需的，并且必须为系统数据库提供至少一条频道记录。当系统找不到电视输入的频道时，系统电视应用会调用设置活动。

设置活动向系统电视应用描述通过电视输入可用的频道，如下一课创建和更新频道数据中所示。

其他参考

• android.media.tv
• 电视输入框架