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).
Figure 1. Media screens
These terms are used throughout this article:
|Media Source||An Android application that implements the Android MediaBrowserService API to expose playback control and browsing of its catalog of media items.|
An element in the Media Source catalog. Media items can be either:
Media provides these features.
|While Driving||While Parked|
Everything listed under "While Driving" as well as:
This table describes the tasks of each party.
|Car Manufacturers (OEMs)||App Developers|
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.
|SHOULD||Adjust overall theme and styling, including color pallette and sizing|
|MAY||Modify high-level structure of Media (for example, tab placement)|
The following diagram illustrates the components that interact with Media.
Figure 2. System components
The elements in this figure are described below:
|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).|
Media application launch
The process by which Media is launched appears below.
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.LAUNCHERactivities. 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
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:
- Account switching
- Display to which the user is currently logged in (if any)
- Service configuration
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).
Figure 5. Error handling
As part of normal PlaybackState error handling, Media must check for the following input.
PlaybackStateerror 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.
PlaybackStateerror message (set by media applications using the
PlaybackStateCompat.Builder#setErrorMessagemethod) 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.
PlaybackStatecan 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
PendingIntentpoints to a custom sign-in Activity implemented by the same media application.
PlaybackStatestate is equal to STATE_ERROR. This signals no other operation is possible until sign-in is completed.
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.
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
The actual intents are defined at
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
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.
Media must subscribe to updates in the list of CarUxRestrictions and implement them as documented.
Particularly important for Media are:
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
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
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.
This figure describes the structure of the 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.
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 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:
Figure 8. Minimized playback controls
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:
media_browse_list_item.xml). Commonly used for episodes in a podcast, such as playlist items, and favorites.
media_browse_list_icons_item.xml). Used for categories or menu options, in which the image included with the media item is not actual album art but an icon.
media_browse_grid_item.xml). Commonly used for playable items, like songs or playlists.
media_browse_grid_icons_item.xml). Used for categories, similar to
media_browse_header_item.xml). Used to organize media items into sections.
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.
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.
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
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.
Figure 11. Home screen media widget
The App Selector button dislayed above uses the switch functionality described in Media Source Switching User Flow.