Media

Media provides a platform on which to build media apps that provide safe, seamless, and connected info-tainment experiences in every Android-enabled car. Media is an Android system application designed to provide a Distraction Optimized (DO) playback and browse experience for media apps. A fully functional implementation of Media is included as part of the Android Open Source Project (AOSP).

Portrait layout
Portrait layout
Landscape layout
Landscape layout

Figure 1. Media playback screens

Terminology

These terms are used throughout this article:

Term Description
Distraction Optimized (DO) User flow that follows the User Experience Restrictions (UXR) and is safe while driving.
Vehicle Optimized (VO) User flow not required to follow UXR and not considered safe while driving, but which has been optimized for use in a car.
Media Source An Android application that implements the Android MediaBrowserService API to expose playback control and browsing of its catalog of media items.
Media Item

An element in the Media Source catalog. Media items can be either:

  • Playable Media Items. Audio segments that can be played by the system such as songs, chapters of books, and episodes of podcasts
  • Browsable Media Items. Organizational elements used to group playable or other browseable media items such as song categories, a recent songs folder, as well as podcasts and playable media items sorted by artist, author, or audience.

Media Features

Media provides these features.

While Driving While Parked

Playback control.

  • Presentation of currently playing media item (for example, a song), including title, album art, duration, description, and current play position.

  • Execution of standard media actions (for example, play, stop, pause, and skip forward).

  • Execution of custom media actions (custom actions provided by each media source).

  • Presentation of the playback queue, if provided by the media app.

Catalog browse.

  • Display of top-level categories.

  • Drill down into browse-able media items (for example, folders).

  • Selection of playable media items (for example, songs) including title, album art, and indicators (for example, explicit content and downloaded content).

Everything listed under "While Driving" and the following.

  • Sign-in. For those media sources that require sign-in, it should be possible to start the sign in flow directly from Media.

  • Settings. Media source can display a settings UI.

  • Search, with keyboard. Users can perform a text search on Media.

Tasks

This table describes the tasks of each party.

Car Manufacturers (OEMs) Google App Developers
  • Build a fully-compliant Android CDD infotainment system with Android Automotive.

  • Fulfill all the expectations of the MediaSession and Browser APIs and the interop with Media:

    • Respect browse structure.
    • Respect custom actions.
    • Delegate to the app for sign-in, settings, and so on.
    • Respect the app's branding elements explicitly supported by the APIs. For instance, app name.
  • >Define and evolve Media APIs.
  • Provide Media implementation in AOSP.
  • Define app review process for publishing of media apps on Play Store.
  • Provide documentation for the APIs, customizations, review/certification process, and so on.
  • Implement Media APIs:
    • Provide overall media browse structure with appropriate content.
    • Provide custom actions as appropriate.
    • Make playback states available to the system.
    • Provide branding elements, such as app name.
  • Implement the sign-in, sign-up, settings, and error resolution flows, as needed.
  • Build and publish car APKs to the Play Store.

Customization Guidelines

The Media implementation included in AOSP provides a base theme and structure that can be adopted as is, or modified according to the following restrictions. The following table describes OEM responsibilities regarding Media customization.

Media Customization Description
SHOULD Adjust overall theme and styling, including color pallette and sizing
MAY
  • Modify adaptive-responsive rules
  • Modify high-level structure of Media (for example, tab placement)
MUST NOT
  • Modify Media API contracts, including app branding:
    • MediaSession and MediaBrowser interoperability
    • Media source name, icon

  • Modify information architecture of:
    • Playback
    • Browse
    • Search

Technical Details

System Components

The following diagram illustrates the components that interact with Media.

System components

Figure 2. System components

The elements in this figure are described below:

Component Description
Home Screen Represents other surfaces in the car UI that display and control the currently playing media. In AOSP, this is the main screen displayed when the system starts. From this screen, users can view details of the media item being played and execute a limited set of standard and custom actions (for example, play and pause).
System UI Provides functionality that includes global UI navigation options such as to navigate to Media.
Assistants Android provides mechanisms for different assistants to interact with the system. If Google Automotive Services (GAS) is being used, the Google Assistant is included by default. These applications can interact with Media Sources in the background (for example, playing a song as the result of a voice command), or navigating to Media in the foreground (for example, when the assistant is ordered to display the UI of a certain Media Source).
App Launcher All Android applications start in the App Launcher, including Media Sources. Media can present its own Media Source selector, complementing or replacing the App Launcher as the starting place for media.
Google Play Store When GAS is being used, this is where users locate and install new applications in an Android device. For media, once applications are installed, users are directed to the Media to complete the sign-in process or to start interacting with the application.
Media Session Manager Android system service that tracks and controls media sessions from all media sources. It provides mechanisms to detect when a Media Source becomes the foreground media source. Media, and all other applications displaying the currently playing media source (for example, the Home screen), use Media Session Manager to detect these events and update the UI accordingly. Media Sources interact with Media Session Manager by means of the Media Session API.
Radio Specialized application to interact with the radio hardware. Radio searches for radio stations, quickly selecting recently identified stations and switching between radio bands. UI components shared by both Radio and Media enable the user to switch between the two experiences.
Driver Distraction Engine Android system service used to impose UX restrictions based on the driving state of the car. For the media sources sign-in and settings UX (where the screen is controlled directly by the media sources), this service ensures that no unsafe content is displayed when the car is in the driving state. OEMs can customize the definition of these states and how the system reacts in these situations (for example, by displaying a blocking screen overlay).

User Flows

Media application launch

The process by which Media is launched appears below.

Media application launch

Figure 3. Media application launch

Media must be launched using the following implicit CAR_INTENT_ACTION_MEDIA_TEMPLATE. This intent can have the following information as extras:

  • android.car.intent.extra.MEDIA_COMPONENT (optional). String extra to represent the flattened component name of a MediaBrowserService in the media application to which the Media is to connect. If not provided, Media displays the currently selected media application. This intent is used from the following entry points:

    • System UI. Used to return to the Media experience or to start using it for the first time. In this case, the above Intent would be used without any extras so as to cause Media to display the currently selected media application.

    • Home Screen, Assistants, and Notification Center. Users can navigate to Media to display the currently selected media application. In all cases, the implicit Intent without extras is triggered.

    • App Launcher. When users select a media application from the App Launcher, the above intent includes the CAR_EXTRA_MEDIA_COMPONENT extra, which contains the selected media application. Media designates this as the newly selected application and connects to it. For details, see the section below, App Launcher to Media integration.

App Launcher to Media Integration

Media applications are not permitted to provide any activity annotated with the android.intent.category.LAUNCHER category. As a result, the App Launcher (or its equivalent) must implement special logic to address media source integration:

  • App Launcher must scan the system for packages implementing MediaBrowserService.SERVICE_INTERFACE. For these packages, App Launcher fetches the service icon similar to that used to fetch other activities.

  • App Launcher then combines these packages with those that implement android.intent.category.LAUNCHER activities. If an application provides a MediaBrowserService implementation and a launcher activity, the service takes precedence.

    Note: As of this writing, no media source application can provide a launcher activity.

  • An example of this logic can be found in the AOSP code at AppLauncherUtils#getAllLauncherApps().

Sign-In Flow and Configuration Options

Media applications can include a vehicle-optimized Settings Activity. Such an activity can be used to implement user flows not addressed by the Android Media APIs, for example:

  • Sign-in
  • Sign-out
  • Account switching
  • Display to which the user is currently logged in (if any)
  • Service configuration

Sign-n flow

Figure 4. Sign-in flow

This Settings Activity is declared by the media application with the following intent filter.

<activity android:name=".AppSettingsActivity"
          android:exported="true
          android:theme="@style/SettingsActivity"
           android:label="@string/app_settings_activity_title">
   <intent-filter>
       <action android:name="android.intent.action.APPLICATION_PREFERENCES"/>
   </intent-filter>
</activity>

Media must implement the following logic:

  • Check that the currently selected media application includes an activity with the given Intent Filter.

  • If so, allow the user to navigate to the activity.

  • If Car UX Restrictions are in effect (for example, the car is moving), this affordance should be disabled as Settings Activity is not a Driver Optimized UI.

Error Handling and Required Sign-In

Media interacts with media applications through the Android Media Session API. As part of this API, Media receives a PlaybackState object, which communicates the current state of the media application.

The sign-in process starts when the media application changes PlaybackState to STATE_ERROR, including a specific error code (see details below). When this happens, Media displays the error description and an affordance to navigate to a sign-in Activity implemented by the media application.

This same flow can be used by applications to signal other error situations (for example, a server connectivity error).

Error handling

Figure 5. Error handling

As part of normal PlaybackState error handling, Media must check for the following input.

  • PlaybackState error code equal to PlaybackStateCompat#ERROR_CODE_AUTHENTICATION_EXPIRED. This will signal that the media application requires sign-in to continue operation. Other error codes can be received, which would indicate other types of error situations.

  • PlaybackState error message (set by media applications using the PlaybackStateCompat.Builder#setErrorMessage method) will contain a human-readable explanation (e.g. "You are not signed in."). This message must be displayed to the user and it must be driving distraction optimized (DO). For details, see UX Driving Restrictions.

  • Optionally, PlaybackState can include the following extras (set by media applications with the PlaybackStateCompat.Builder#setExtras method) with the following keys.

    • android.media.extras.ERROR_RESOLUTION_ACTION_LABEL. Set to a string that contains the human-readable message to be displayed on the button touched by the user to start the sign-in flow.

    • android.media.extras.ERROR_RESOLUTION_ACTION_INTENT. Set with a PendingIntent to be triggered when the user clicks on the above mentioned button. This PendingIntent points to a custom sign-in Activity implemented by the same media application.

  • PlaybackState state is equal to STATE_ERROR. This signals that no other operation is possible until sign-in is completed.

Radio

Radio UI is implemented as an independent application. The integration with Media provides users with a seamless experience, allowing users to interact with media sources and radio as a single application.

Media Source Switching User Flow

The following diagram illustrates how the reference implementation of Radio and Media implements the application switching user flow.

Media source switching user flow

Figure 6. Media source switching user flow

Replacing the Radio Application

OEMs who want to use their own implementation of Radio can replace that provided by the AOSP with one of their own. The following topics describe how to do so.

Creating a Radio Application

Besides implementing the radio integration and user interface, Radio must also implement the same APIs as any Automotive media application (see Providing Audio Playback for Auto).

Implementing a Media Source Switcher

Note: This task is optional and can be used to include an app switcher in the Media app.

This task is optional and can be used to include an app switcher in the Media app.

The car-media-common library contains a MediaAppSelectorWidget that must be integrated into the Radio app so as to provide a seamless transition between Radio and other apps displayed in Media.

MediaAppSelectorWidget provides an icon/dropdown view from which users can select a media source, including Radio and streaming apps. Media and the AOSP version of the Radio UI include this by default.

A Radio UI replacement can include this switch by adding the following code to the layout file.

<com.android.car.media.common.MediaAppSelectorWidget
     android:id="@+id/app_switch_container"
     android:layout_width="@dimen/app_switch_widget_width"
     android:layout_height="wrap_content"
     android:background="@drawable/app_item_background"
     android:gravity="center" />

This widget launches AppSelectionFragment, which displays a list of media sources that can be switched to.

Integrating with Assistant

In addition to the basic MediaSession implementation, the Radio app must implement the following MediaSession callbacks:

Callback Description
onPlay()
Start playing the currently selected radio station.
onStop()
Stop playing radio.
onSkipToNext()
Scan radio bands upwards until finding one with signal.
onSkipToPrevious()
Scan radio bands downwards until find one with signal.
onSetRating()
Add/Remove the current radio to the favorites list.
onPlayFromMediaId()
Play the radio station corresponding to the provided media Id, which would correspond a media item listed through the MediaBrowserService.
onPlayFromUri()
Play the radio station corresponding to the provided URI. A URI parser is provided as part of the car-broadcastradio-support library, which can be used to convert a URI to a ProgramSelector.

UX Driving Restrictions

Media must observe all UX driving distraction restrictions. To do so, Media must listen to the CarUXRestrictionManager and implement all its policies.

Customization

Additional Details

Media is part of a suite of system applications (for example, Dialer and App Launcher). These applications share common styles and assets that are defined at different levels in the AOSP structure.

  • framework/base/core. This is where all Android base styles are defined. In particular, all system application themes are based on Theme.DeviceDefault. This is the theme designed for OEMs to customize device default appearance.

  • packages/services/Car/car_product/overlay. This folder contains overrides to Theme.DeviceDefault that are used to produce the AOSP look and feel of Android Automotive. OEMs might opt to exclude this overlay and use their own.

  • packages/apps/Car/car_lib/car_app_common. Common colors and styles shared between AOSP provided system applications. OEMs can use overlays to customize these elements (similar to the car_product/overlay mentioned above).

  • packages/apps/Car/car_lib/car_media_common. This folder contains elements shared between Media and other media UIs (for example, the Home screen Media widget).

  • packages/apps/Car/Media. Finally, all system applications use their own Theme which extends from either Theme.NoActionBar.Drawer (defined in car_apps_common) or Theme.DeviceDefault (defined in framework/base).

For more information on AOSP theming and overlays, see AOSP - Customize the Build with Resource Overlays.

Android Automotive AOSP provides two presentations of media.

  • Media UI. Enables users to sign in, browse content, and use detailed playback controls.

    Media UI

    Figure 7. Media UI

  • Home screen media widget. Enables the use of core media playback control features to the home screen in the car.

    Home screen media

    Figure 8. Home screen media widget/p>

Use style and theme overlays to customize both presentations.

Media UI

This figure describes the structure of the Media UI:

Media UI

Figure 9. Media UI

App Bar

Items in the app bar are presented in the figure below.

App bar

Figure 10. App bar

Browse Fragment

The structure of a browse fragment is presented below.

Browse fragment

Figure 11. Browse fragment

Browse Fragment Playback Controls

The Browse Fragment playback controls are as illustrated below.

Browse fragment playback controls

Figure 12. Browse fragment playback controls

Browse List

Items that comprise the Browse List are identified in the following figure.

Browse list

Figure 13. Browse list

Playback Screen

Components of the Playback screen are identified in the following figures.

Playback screen

Playback screen (2)

Figure 14. Playback screens

Playback Controls

The Playback controls in Media are identified below:

Playback controls

Figure 15. Playback controls

Home Screen Media Widget

Components in the Media widget are identified in the following figure.

Home screen medai widget

Figure 16. Home screen media widget