预览视频

预览视频是鼓励用户深层链接到您的 TV 应用的绝佳方式。预览视频可以是短片,也可以是完整的电影预告片。

在创建预览时,请注意以下准则:

  • 请勿在预览中展示广告。如果您在客户端拼接广告,请勿将其拼接到预览视频中。如果您在服务器端拼接广告,请提供无广告视频进行预览。
  • 为获得最佳品质,预览视频的宽高比应为 16:9 或 4:3。如需了解预览视频的推荐大小,请参阅视频节目属性。
  • 当预览视频和海报图片具有不同的宽高比时,主屏幕会在播放预览之前将海报视图的大小调整为视频的宽高比。视频不是信箱模式的。例如,如果海报图片宽高比为 ASPECT_RATIO_MOVIE_POSTER (1:1.441),但视频宽高比为 16:9,则海报视图会转换为 16:9 区域。
  • 创建预览后,其内容可以公开访问,也可以受 DRM 保护。每种情形采用的步骤不同。本页介绍了这两种方法。

在主屏幕中播放预览

如果您使用 ExoPlayer 支持的任何视频类型创建预览,并且该预览可公开访问,则可以直接在主屏幕上播放该预览。

构建 PreviewProgram 时,请使用 setPreviewVideoUri() 和可公开访问的 HTTPS 网址,如以下示例所示。预览可以是视频或音频。

val previewVideoUrl = Uri.parse("https://www.example.com/preview.mp4")
val builder = PreviewProgram.Builder()
builder.setChannelId(channelId)
    // ...
    .setPreviewVideoUri(previewVideoUrl)

在 Surface 上呈现预览

如果您的视频受 DRM 保护或采用 ExoPlayer 不支持的媒体类型,请使用 TvInputService。Android TV 主屏幕通过调用 onSetSurface() 将 Surface 传递给您的服务。您的应用会通过 onTune() 直接在此 Surface 上绘制视频。

通过直接 Surface 渲染,您的应用可以控制渲染的内容和渲染方式。您可以叠加频道归因等元数据。

在清单中声明 TvInputService

您的应用必须提供 TvInputService 的实现,以便主屏幕可以呈现您的预览。

在服务声明中,添加一个 intent 过滤器,用于指定 TvInputService 作为要通过 intent 执行的操作。此外,还要将服务元数据声明为单独的 XML 资源。以下示例展示了服务声明、intent 过滤器和服务元数据声明:

<service android:name=".rich.PreviewInputService"
    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. -->
    <meta-data
        android:name="android.media.tv.input"
        android:resource="@xml/previewinputservice" />
</service>

在单独的 XML 文件中定义服务元数据。 服务元数据文件位于应用的 XML 资源目录中,并且必须与您在清单中声明的资源名称一致。使用上一个示例中的清单条目,您可以在 res/xml/previewinputservice.xml 处创建一个 XML 文件,其中包含一个空的 tv-input 标记:

<tv-input/>

TV 输入框架必须包含这个标记。不过,它仅用于配置实际渠道。由于您要渲染视频,因此该标记应为空。

创建视频 URI

如需指明预览视频应由您的应用(而非 Android TV 主屏幕)呈现,您必须为 PreviewProgram 创建视频 URI。URI 应以应用为内容使用的标识符结尾,以便您稍后在 TvInputService 中检索内容。

如果您的标识符类型为 Long,请使用 TvContractCompat.buildPreviewProgramUri():

val id: Long = 1L // content identifier.
val componentName = ComponentName(context, PreviewVideoInputService::class.java)
val previewProgramVideoUri = TvContractCompat.buildPreviewProgramUri(id)
    .buildUpon()
    .appendQueryParameter("input", TvContractCompat.buildInputId(componentName))
    .build()

如果您的标识符不是 Long 类型,请使用 Uri.withAppendedPath() 构建 URI:

val previewProgramVideoUri = Uri.withAppendedPath(PreviewPrograms.CONTENT_URI, "content-identifier")
    .buildUpon()
    .appendQueryParameter("input", TvContractCompat.buildInputId(componentName))
    .build()

您的应用会调用 onTune(Uri videoUri),让 Android TV 开始播放预览视频。

创建服务

以下示例展示了如何扩展 TvInputService 以创建您自己的 PreviewInputService。请注意,该服务使用 MediaPlayer 进行播放,但您的代码可以使用任何可用的视频播放器。

// import android.content.Context
// import android.media.MediaPlayer
// import android.media.tv.TvInputService
// import android.net.Uri
// import android.util.Log
// import android.view.Surface
// import java.io.IOException

class PreviewVideoInputService : TvInputService() {

    override fun onCreateSession(inputId: String): TvInputService.Session? {
        return PreviewSession(this)
    }

    private inner class PreviewSession(
        internal var context: Context
    ) : TvInputService.Session(context) {

        internal var mediaPlayer: MediaPlayer? = MediaPlayer()

        override fun onRelease() {
            mediaPlayer?.release()
            mediaPlayer = null
        }

        override fun onTune(uri: Uri): Boolean {
            // Let the TvInputService know that the video is being loaded.
            notifyVideoUnavailable(VIDEO_UNAVAILABLE_REASON_TUNING)
            // Fetch the stream url from the TV Provider database
            // for content://android.media.tv/preview_program/<id>.
            val id = uri.lastPathSegment
            // Load your video in the background.
            retrieveYourVideoPreviewUrl(id) { videoUri ->
                if (videoUri == null) {
                    Log.d(TAG, "Could not find video $id")
                    notifyVideoUnavailable(TvInputManager.VIDEO_UNAVAILABLE_REASON_UNKNOWN)
                }

                try {
                    mediaPlayer?.setDataSource(getApplicationContext(), videoUri)
                    mediaPlayer?.prepare()
                    mediaPlayer?.start()
                    notifyVideoAvailable()
                } catch (e: IOException) {
                    Log.e(TAG, "Could not prepare media player", e)
                    notifyVideoUnavailable(TvInputManager.VIDEO_UNAVAILABLE_REASON_UNKNOWN)
                }
            }
            return true
        }

        override fun onSetSurface(surface: Surface?): Boolean {
            mediaPlayer?.setSurface(surface)
            return true
        }

        override fun onSetStreamVolume(volume: Float) {
            // The home screen may fade in and out the video's volume.
            // Your player should be updated accordingly.
            mediaPlayer?.setVolume(volume, volume)
        }

        override fun onSetCaptionEnabled(b: Boolean) {
            // enable/disable captions here.
        }
    }

    companion object {
        private const val TAG = "PreviewInputService"
    }
}