Android TV Samples

The Android TV Classics Sample is a reference implementation for building media playback applications on Android TV. It demonstrates how to integrate key platform features, including:

• MediaSession support: Managing media playback state and controls.
• ExoPlayer: Implementing robust media playback.
• TV Launcher Home Screen Channels: Making your app content discoverable on the Android TV home screen.
• Content Provider: Enabling global search capabilities and Google Assistant integration.
• Leanback UI: Providing the standard TV browsing and playback experience.

The JetStream sample is a dark-themed media streaming application designed to demonstrate real-world architecture and typical Material design patterns for Android TV using Compose.

Key TV Compose components showcased in this sample include:

• Layout & Grids: TvLazyRow, TvLazyColumn, TvVerticalGrid, ImmersiveList, Carousel, and TabRow.
• Material Components: Tv Material Surface, Tv Material Cards, Buttons, Icon, Text, Chips, ListItem, Switch, and Dialogs.

The Watch Next feature allows users to quickly resume content (e.g., a paused movie or the next episode in a series) directly from the device home screen.

• Android TV: All apps can add content to the Watch Next row.
• Google TV: Apps must be certified before their content appears in the Watch Next row.
• Testing: To test this on a device, run the sample, watch a movie for a few minutes, and return to the home screen. The content should appear just below the apps row.

The sample app leverages LiveData to create a reactive architecture for several key scenarios:

• Network Connectivity: Network status is represented as LiveData. The application observes this to automatically re-fetch data or set up the database as soon as the network becomes available.
• Sharing States: Instead of using nested callbacks or listeners to sync states (like downloading, removing, rented, or downloaded), all video states are persisted in the database. Different UI components (Presenters or Fragments) observe the same LiveData source, allowing them to stay in sync without interfering with each other.
• Reactive Search: The search query field is encapsulated as LiveData. This allows search results to change reactively based on user input.

The application uses a state machine to decouple playback logic from specific features. Instead of features managing state transitions themselves, they act as listeners that react to state changes emitted by the state machine. This allows distinct modules to respond to specific events without knowing how those events were triggered.

Common use cases for listening to states include:

• Errors: Triggering error UI when a connection failure or playback problem occurs.
• Watch Progress: Updating local progress when a video is paused, or loading progress when a video is first prepared.
• Watch Next: Updating 'Watch Next' tiles when a video is paused or completed.
• Video Completion: Stopping playback and returning to the previous screen when a video finishes.

The app's playback architecture is built on several key components:

• UI: Uses VideoSupportFragment to simplify the creation of the video playback user interface.
• Engine: Uses [ExoPlayer] for actual video playback.
• Controls: Supports playback via voice, remote controls, and Bluetooth headsets through [MediaSession] integration.
• State Management: Uses a basic state machine to allow components to respond to playback changes (e.g., pausing). See STATE_MACHINE.md for details.
• Persistence: Watch progress is stored locally in a SQL database using Room to support resuming playback.

To prevent complexity, the state machine follows three core architectural principles:

1. Statelessness: The state machine informs listeners of changes but does not track the current state or the previous state itself.
2. Immutability: The same state instance is sent to every listener, and listeners are prohibited from manipulating the state objects.
3. Decoupling of dependencies: Because the machine is stateless and broadcasts the same state to everyone, listeners (e.g., 'Watch Progress' and 'Play Next') remain completely independent and unaware of each other.

The app uses the Cast Connect library to act as a Cast receiver. This allows mobile sender applications to communicate with the TV app via the Cast protocol.

• Functionality: Cast Connect allows your TV app to receive messages and broadcast media status as if it were a Chromecast.
• Capabilities: A mobile device can send cast signals to the TV app to open it for casting, playback, and media control.
• Configuration: See CAST_CONNECT.md for steps on how to configure a Cast Sender application to work with this app.

The backend server implements OAuth endpoints (authentication callback, token exchange, revocation, and user info) required for Account Linking.

Deployment Steps:

1. Ensure Node.js, npm, and Firebase CLI are installed.
2. Run npm install in the root directory.
3. Link your Firebase project:

   firebase use --add {your_firebase_project_id}

4. Install server dependencies:

   cd {project_folder}/firebase/server
   npm install

5. Deploy to Cloud Functions:

   firebase deploy

Note on Testing: To run tests in server/test/authentication.test.ts, you must replace the REPLACE_ME placeholders for project ID, database URL, and storage bucket with values from your google-services.json file.

To run the TV Reference App sample, follow these steps:

1. Clone the repository:

   git clone https://github.com/android/tv-samples.git

2. Open the ReferenceAppKotlin project in Android Studio.
3. Compile and deploy the app to an Android TV emulator or a physical device (e.g., ADT-3).