Integration with preview playback requires that you play channel content within a player that can use a Surface provided by the live TV app.
Create TvInputService.Session
When a user selects a specific channel, theTvInputService class is called to create a Session. The session is where you can choose the content, prepare the player, and render channel content. Add this into the TvInputService class, RichTvInputService.
The following code shows an example of a concrete Session class.
- Java
- Kotlin
Identify the correct channel
You can identify the current channel users are tuning to through theonTune() callback by the channelId.
The following code shows an example of how to get the channel ID from the channelUri.
- Java
- Kotlin
Play the channel content in preview playback
Implement a media player that can play your TV feed on a configurable surface. When a user moves the focus to a specific channel card when browsing, the live app uses the session from the previous step. Your app defines the session as part of theTvInputService.Session class, and uses it to tune to the requested channel and play content.
Create a media player
There are several options for implementing a media player. You must have a well-defined media player inside your app that you can directly use. There is no hard requirement as to which media player you must use, as long as the player can play your TV feeds and you can configure it to use a customizedSurface class. For details, see #onSetSurface. Because of this case-by-case player implementation, the following options are provided for reference only.
ExoPlayer: a good candidate for the underlying media player.
SampleTvApp’s RichTvInputService: an example of how to define the customized media player in TvInputService.
onSetSurface
During the tuning process, Android’s TIF framework calls theonSetSurface(@Nullable Surface surface) callback, which is defined in the TvInputService.Session (refer to previous steps). It’s your responsibility to set the provided Surface instance to your media player, which is used for preview playback.
onTune
TheonTune(Uri channelUri) callback is called next, where you identify the correct channel (refer to Identify the Correct Channel), retrieve the corresponding channel feed, and prepare the media player to play the feed when ready.
Here are some typical scenarios for not calling onTune() for the second playback:
- When the user moves focus to a channel card,
onTune()calls for preview playback. - When the user clicks the current card and enters the full-screen playback.
- When full-screen playback seamlessly displays full-screen. You won’t receive another
onTune()in this case.
Notify tuning status
You must notifyTvInputService about the most recent tuning status based on the player’s loading status. Fire TV’s Live app refers to the status to adjust the preview UI.
Here is an example of notifying the tuning status. In this case, the status is “temporarily unavailable.” Place this code in TvInputService.Session.
- Java
- Kotlin
- Java
- Kotlin
Parental controls
Based on the product requirements, don’t play preview playback videos if parental controls (PCON) is enabled. The following code shows an example of how to listen to parental controls with live preview or native full screen playback.- Java
- Kotlin
Checkpoint: Preview playback in browse
- Build and install your APK on a Fire TV.
- Navigate to the On Now row and focus on a channel card. Preview playback should start to play in the top right corner.
- If not using deep link: select channel card and playback should continue in full screen.
- Navigate to the parental control menu to turn on parental controls.
- Navigate back to the On Now row and focus on a channel card. Preview playback should NOT start to play, but poster art should show up on the browse screen if provided.
- If not using deep link: select channel card and a PIN prompt appears. Insert the PIN for playback to start in full screen.
Troubleshooting
This section contains steps to troubleshoot issues you might encounter. I don’t see theonTune() callback being triggered when focusing on my channel card.
Verify the input ID of that channel. Android won’t identify your TvInputService to call it if the InputId is not correct.
I can see onTune() being called, but the playback preview doesn’t start.
- Check if your player is correctly implemented for playing the feed.
- Ensure you are calling
notifyVideoAvailable()to notify that your tuning status is ready.
TvInputService. Your player should stop if PCON is on, and you use notifyContentBlocked() to notify the UI. For more information, see Live TV Resources.
After enabling parental controls (PCON), I don’t see the preview playback nor the poster image. I only see a black background.
Make sure your channel has valid poster art to show. It should show the image of the program currently airing.
If it is, verify that you are calling notifyContentBlocked(). The UI won’t update to use the poster image if you don’t send a notification about the PCON status.

