Google is committed to advancing racial equity for Black communities. See how.

Media

Media provides a platform on which to build media apps that provide safe, seamless, and connected infotainment 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 with Android Open Source Project (AOSP).

Media screens

Figure 1. Media screens

Terminology

These terms are used throughout this article:

Term Description
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" as well as:

  • 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 expectations of MediaSession and Browser APIs and the interoperability with Media:
    • Respect browse structure.
    • Respect custom actions.
    • Delegate to the app for sign-in, settings, and so on.
    • Respect the app branding elements explicitly supported by the APIs. For example, the 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 elements such as APIs, customizations, review, and certification processes
  • 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 uses Car UI Library to enable customization, and 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 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 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.

    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 no other operation is possible until sign-in is completed.

Radio

The Radio UI is implemented as an independent application. Instructions on how to integrate a Radio UI to the radio hardware can be found at [Implementing Radio](/devices/automotive/radio).

The following section describes how to integrate Radio UI with Media to provide users with a seamless experience that enables users to interact with media sources and radio as if they were 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

To provide a seamless transition between Radio and other apps in Media, the car-media-common library defines Android intents that can be used to launch a media source selector. In AOSP, this selector is implemented in the App Launcher, presenting the same UI for launching apps, but filtered to display only media sources.

OEMs can opt to take the current App Launcher implementation as is, or implement a customized media source selector.

The selector can act in two modes:

  • Normal flow. After using the selector, the selected source will be displayed in Media so the user can browse its content.

  • As a switch. A selector is used to switch sources, but the Media is not displayed to the user. This is true of the Selector icon on the Home Page. After selecting a source, the most recent previous screen is displayed to the user (in this case, the Home page).

The intent used to switch between media sources can be obtained from the MediaSource#getSourceSelectorIntent() method, which accepts a popup Boolean that returns an intent to launch each of the flows described above.

The actual intents are defined at packages/apps/Car/libs/car-media-common/res/values/config.xml. To customize this configuration, use build-time overlays.

Replacing the Radio Application

Given that the Radio app implements Media Browse and Media Session, Radio is displayed in the App launcher. To prevent launching Media when a user clicks the icon, two elements are required. Radio must:

  • Have a launcher activity.
  • Be declared as a custom source. To do so, add the component name to the custom_media_packages key in car-media-common/res/values/config.xml.

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

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

  • framework/base. All Android base styles are defined here.

  • packages/services/Car/car_product/overlay. Contains build-time overlays that modify standard framework/base resources to produce the AOSP look-and-feel of Android Automotive OS. OEMs may opt to exclude this overlay and use their own.

  • packages/apps/Car/libs/car-ui-lib. This library defines AAOS components and resources common to system applications and unbundled applications (for example, GAS apps) designed for customization. For more details, refer to the Car UI Library Integration Guide.

  • packages/apps/Car/libs/car_app_common. Common colors and styles shared between Automotive system applications. OEMs can use overlays to customize these elements (similar to car_product/overlay described above).

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

  • packages/apps/Car/Media . All system applications use their own theme, which extends from Theme.CarUi (defined in car-ui-lib).

For more information on customization, see the Car UI Library Integration Guide.

Android Automotive AOSP provides two presentations of media.

  • Media UI. Enables users to sign in, browse content, and use detailed playback controls.
  • Home screen media widget. Enables the use of core media playback control features to the Home screen.

Media UI

This figure describes the structure of the Media UI:

Media UI

Figure 7. Media UI

For details about UX and UI guidelines as well as the spatial structure of the different components of Media, see Spatial Model.

AppBarView: Toolbar

The Media UI toolbar is a component shared with other system applications, such as Dialer and Radio. For a description on its customization, see the Car UI Library Integration Guide.

Browse Fragment

Browse consists primarily of a Car UI RecyclerView (which handles scrollbar position, arrows, and margins) and browse items of different types, such as headers, grid items, icon grid items, list items, and icon list items.

Minimized Playback Controls

When the browse fragment is being displayed, and when a media item is selected, a minimized playback controls view is displayed. The following figure illustrates the structure of this view:

Minimized playback controls

Figure 8. Minimized playback controls

Browse List

Developers can use a set of style hint (see Apply Content Styles) to customize the presentation of media browse content. OEMs must adhere to these styles, adjusting presentation to their design system.

Supported item types and the respective layouts are located as follows:

Playback Screen

To display this screen, expand the minimized playback controls:

  • Currently playing media item medata (including title and subtitle).
  • Complete playback controls.
  • Playback queue (used to display recently played or next items to play).

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

Playback screen

Figure 9. Playback screen

Playback screen doesn’t share the toolbar with the rest of the application. Instead, the elements on the top of the screen are individually managed by this screen.

Playback Controls

The playback screen includes an extended set of playback controls, organized in control rows. The secondary row (displayed below as the row on the top) is only displayed if the space on the first row is not enough to display all the actions returned by the media app from PlaybackStateCompat#getActions().

Playback controls

Figure 10. Playback controls.

OEMs can customize the icons of standard actions, but they must present custom action icons as they are provided by the media applications.

Home Screen Media Widget

This widget is implemented as a fragment in car-media-common. This fragment includes a minimized version of the Playback Screen described above. All the same customization rules and capabilities apply.

Home screen media widget

Figure 11. Home screen media widget

The App Selector button dislayed above uses the switch functionality described in Media Source Switching User Flow.