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).
Figure 1. Media playback screens
These terms are used throughout this article:
|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.|
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" and the following.
This table describes the tasks of each party.
|Car Manufacturers (OEMs)||App Developers|
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.
|SHOULD||Adjust overall theme and styling, including color pallette and sizing|
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 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).|
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.
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
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 that no other operation is possible until sign-in is completed.
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.
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.
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
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:
|Start playing the currently selected radio station.|
|Stop playing radio.|
|Scan radio bands upwards until finding one with signal.|
|Scan radio bands downwards until find one with signal.|
|Add/Remove the current radio to the favorites list.|
|Play the radio station corresponding to the provided media Id, which would correspond a media item listed through the MediaBrowserService.|
|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.
Media must subscribe to updates in the list of CarUxRestrictions and implement them as documented.
Particularly important for Media are:
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.DeviceDefaultthat 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
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
car_apps_common) or Theme.DeviceDefault (defined in
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
Figure 7. Media UI
- Home screen media widget. Enables the use of core media playback control
features to the home screen in the car.
Figure 8. Home screen media widget/p>
Use style and theme overlays to customize both presentations.
This figure describes the structure of the Media UI:
Figure 9. Media UI
Items in the app bar are presented in the figure below.
Figure 10. App bar
The structure of a browse fragment is presented below.
Figure 11. Browse fragment
Browse Fragment Playback Controls
The Browse Fragment playback controls are as illustrated below.
Figure 12. Browse fragment playback controls
Items that comprise the Browse List are identified in the following figure.
Figure 13. Browse list
Components of the Playback screen are identified in the following figures.
Figure 14. Playback screens
The Playback controls in Media are identified below:
Figure 15. Playback controls
Home Screen Media Widget
Components in the Media widget are identified in the following figure.
Figure 16. Home screen media widget