Devbytes: Android Auto Audio
++ Drivers want to access their music and other audio content on the road. Audio books, podcasts, + sports commentary, and recorded talks can make a long trip educational, inspirational, and + enjoyable. The Android framework allows you to extend your audio app so users can listen to their + favorite tunes and audio content using a simpler, safer user interface. +
+ ++ Apps running on mobile devices with Android 5.0 or higher can provide audio services for + dashboard systems running Android Auto. By configuring your app with a few settings and + implementing a service for accessing music tracks, you can enable Auto devices to discover your + app and provide a browse and playback interface for your app's audio content. +
+ ++ This class assumes that you have built an app that plays audio through an Android device's + integrated speakers or connected headphones. It describes how to extend your app to allow Auto + devices to browse your content listings and play it through a car stereo system. +
+ + ++ Audio apps do not directly control a car dashboard device that runs Android Auto. When the user + connects an Android mobile device into a dashboard system, Android Auto discovers your app through + manifest entries that indicate what audio services your app can provide. The dashboard system + displays a launcher icon for your app as a music provider and the user can choose to use your + app's services. If the user launches your app, the Auto device queries your app to see what + content is available, displays your content items to the user, and sends requests to your app to + control playback with actions such as play, pause, or skip track. +
+ +To enable your app to provide audio content for Auto devices, you need to: +
+ ++ When a user plugs an Android mobile device into a dashboard device running Auto, the system + requests a list of installed apps that include app manifest entries to indicate they + support services for Auto devices and how to access them. This section describes how to configure + your app manifest to indicate your app supports audio services for Auto devices, and allow + dashboard system to connect with your app. +
+ + ++ You indicate that your app supports cars capabilities using the following manifest entry: +
+ ++<application> + ... + <meta-data android:name="com.google.android.gms.car.application" + android:resource="@xml/automotive_app_desc"/> + ... +<application> ++ +
+ This manifest entry refers to a secondary XML file, where you declare what Auto capabilities your + app supports. For an app that supports audio for cars, add an XML file to the {@code res/xml/} + resources directory as {@code automotive_app_desc.xml}, with the following content: +
+ ++<automotiveApp> + <uses name="media"/> +</automotiveApp> ++ +
+ For more information about declaring capabilities for Auto devices, see Getting Started with Auto. +
+ + ++ Auto devices expect to connect to a service in order to browse audio track + listings. You declare this service in your manifest to allow the dashboard system to discover + this service and connect to your app. +
+ +The following code example shows how to declare this listing browser service in your manifest:
+ ++<application> + ... + <service android:name=".MyMediaBrowserService" + android:exported="true"> + <intent-filter> + <action android:name= + "android.media.browse.MediaBrowserService"/> + </intent-filter> + </service> + ... +<application> ++ +
+ The service your app provides for browsing audio tracks must extend the + {@link android.service.media.MediaBrowserService}. The implementation of this service is discussed + in the Build a Browser Service section. +
+ ++ Note: Other clients can also contact your app's browser service aside from Auto + devices. These media clients might be other apps on a user's mobile device, or they might be other + remote clients. +
+ ++ The Auto user interface shows notifications about your audio app to the user during the course + of operation. For example, if the user has a navigation app running, and one song finishes + and a new song starts, the Auto device shows the user a notification to indicate the change with + an icon from your app. You can specify an icon that is used to represent your app for these + notifications using the following manifest declaration: +
+ ++<application> + ... + <meta-data android:name="com.google.android.gms.car.notification.SmallIcon" + android:resource="@drawable/ic_notification" /> + ... +<application> ++ +
Note: The icon you provide should have transparency enabled, so the +icon's background gets filled in with the app's primary color.
+ + +Auto devices interact with your app by contacting its implementation of a + {@link android.service.media.MediaBrowserService}, which +you declare in your app manifest. This service allows Auto devices to find out what content your app +provides. Connected Auto devices can also query your app's media browser service to contact the +{@link android.media.session.MediaSession} provided by your app, which handles content playback +commands.
+ +You create a media browser service by extending the +{@link android.service.media.MediaBrowserService} class. +Connected Auto devices can contact your service to do the following:
+ +Auto devices acting as audio clients call your app's {@link +android.service.media.MediaBrowserService} to find out what content you have +available. You need to implement two methods in your browser service to support +this: {@link android.service.media.MediaBrowserService#onGetRoot +onGetRoot()} and {@link +android.service.media.MediaBrowserService#onLoadChildren +onLoadChildren()}.
+ +Each node in your content hierarchy is represented by a {@link +android.media.browse.MediaBrowser.MediaItem} object. Each of these objects is +identified by a unique ID string. The client treats these ID strings as +opaque tokens. When a client wants to browse to a submenu, or play a content +item, it passes the ID token. Your app is responsible for associating the ID +token with the appropriate menu node or content item.
+ +Note: You should consider providing different content +hierarchies depending on what client is making the query. In particular, Auto +applications have strict limits on how large a menu they can display. This is +intended to prevent distracting the driver, and to make it easy for the driver +to operate the app via voice commands. For more information on the Auto user +experience restrictions, see the +Auto Media Apps guidelines.
+ +Your implementation of {@link android.service.media.MediaBrowserService#onGetRoot +onGetRoot()} returns information about the root node of the menu +hierarchy. This root node is the parent of the top items your browse hierarchy. +The method is passed information about the calling client. You can use this +information to decide if the client should have access to your content at all. +For example, if you want to limit your app's content to a list of approved +clients, you can compare the passed {@code clientPackageName} to your whitelist. +If the caller isn't an approved package, you can return null to deny access to +your content.
+ +A typical implementation of {@link +android.service.media.MediaBrowserService#onGetRoot onGetRoot()} might +look like this:
+ +
+@Override
+public BrowserRoot onGetRoot(String clientPackageName, int clientUid,
+ Bundle rootHints) {
+
+ // Check the calling client to make sure it's one you approve.
+ // For example, to limit access to just Auto, the Auto emulator,
+ // and this app:
+
+ if (!clientPackageName.equals("com.google.android.projection.gearhead") &&
+ !clientPackageName.equals("com.example.android.media") &&
+ !clientPackageName.equals(getApplication().getPackageName()) {
+
+ // If the request comes from an untrusted package, return null.
+ // No further calls will be made to other media browsing methods.
+ return null;
+ }
+
+ // Return a BrowserRoot. If you wish, you could have multiple BrowserRoot
+ // objects and return different ones depending on the calling client.
+ // In this example, there's just a single BrowserRoot.
+ return new BrowserRoot(MEDIA_BROWSER_ROOT, null);
+ }
+
+
++ The Auto device client builds the top-level menu by calling {@link + android.service.media.MediaBrowserService#onLoadChildren onLoadChildren()} with the root node + object and getting it's children. The client builds submenus by calling the same method with + other child nodes. The following example code shows a simple implementation of {@link + android.service.media.MediaBrowserService#onLoadChildren onLoadChildren()} method: +
+ +
+@Override
+public void onLoadChildren(final String parentMediaId,
+ final Result<List<MediaItem>> result) {
+
+ // Assume for example that the music catalog is already loaded/cached.
+
+ List<MediaBrowser.MediaItem> mediaItems = new ArrayList<>();
+
+ // Check if this is the root menu:
+ if (MEDIA_BROWSER_ROOT.equals(parentMediaId)) {
+
+ // build the MediaItem objects for the top level,
+ // and put them in the <result> list
+ } else {
+
+ // examine the passed parentMediaId to see which submenu we're at,
+ // and put the children of that menu in the <result> list
+ }
+}
+
+
+
++ Auto devices use {@link android.media.session.MediaSession} objects to pass playback control + commands to an app that is providing audio services. Your audio app must create an instance of + this object to pass to the dashboard device and implement callback methods to enable remote + control of audio playback. +
+ +An Auto device using your app as audio service needs to obtain a {@link +android.media.session.MediaSession} object from your app. The Auto device uses the session object +to send playback commands requested by the Auto user back to your app.
+ +When you initialize your browser service, you register that session object with your {@link +android.service.media.MediaBrowserService} by calling the {@link +android.service.media.MediaBrowserService#setSessionToken setSessionToken()} method. This step +allows clients such as an Auto device to retrieve that object by calling your browser service's +{@link android.service.media.MediaBrowserService#getSessionToken getSessionToken()} method.
+ +In your browser service's {@link +android.service.media.MediaBrowserService#onCreate() onCreate()} method, +create a {@link android.media.session.MediaSession}. You can then query +the {@link android.media.session.MediaSession} to get its token, and register +the token with your browser service:
+ +
+public void onCreate() {
+ super.onCreate();
+
+ ...
+ // Start a new MediaSession
+ MediaSession mSession = new MediaSession(this, "session tag");
+ setSessionToken(mSession.getSessionToken());
+
+ // Set a callback object to handle play control requests, which
+ // implements MediaSession.Callback
+ mSession.setCallback(new MyMediaSessionCallback());
+
+ ...
+
+
++ When you create the media session object, you set a callback object that is used to handle + playback control requests. You create this callback object by providing an implementation of the + {@link android.media.session.MediaSession.Callback} class for your app. The next section + discusses how to implement this object. +
+ + +When an Auto device requests playback of an audio track from your app, it uses the +{@link android.media.session.MediaSession.Callback} class from your app's +{@link android.media.session.MediaSession} object, which it obtained from your app's +media browse service. When an Auto user wants to play content or control content playback, +such as pausing play or skipping to the next track, Auto invokes one +of the callback object's methods.
+ +To handle content playback, your app must extend the abstract {@link +android.media.session.MediaSession.Callback} class and implement the methods +that your app supports. The most important callback methods are as follows:
+ +Your app should override these methods to provide any desired functionality. +In some cases you might not implement a method if it is not supported by your app. +For example, if your app plays a live stream (such as a sports +broadcast), the skip to next function might not make sense. In that case, you +could simply use the default implementation of +{@link android.media.session.MediaSession.Callback#onSkipToNext +onSkipToNext()}.
+ +When your app receives a request to play content, it should play audio the same way it +would in a non-Auto situation (as if the user was listening through a device speaker +or connected headphones). The audio content is automatically sent to the dashboard system +to be played over the car's speakers.
+ +For more information about playing audio content, see +Media Playback, +Managing Audio Playback, and +ExoPlayer. + + +(for example, by using a {@link +android.media.MediaPlayer} or ExoPlayer). If the phone +is connected to an Auto device, .
diff --git a/docs/html/training/training_toc.cs b/docs/html/training/training_toc.cs index f246a0f9a193a..791aef6ef9731 100644 --- a/docs/html/training/training_toc.cs +++ b/docs/html/training/training_toc.cs @@ -938,6 +938,7 @@ include the action bar on devices running Android 2.1 or higher." +