O app precisa declarar o MediaBrowserService com um filtro de intent no
manifesto. Você pode escolher o nome do serviço. No exemplo a seguir, o nome do serviço escolhido é MediaPlaybackService.
<service android:name=".MediaPlaybackService">
<intent-filter>
<action android:name="android.media.browse.MediaBrowserService" />
</intent-filter>
</service>
Inicializar a sessão de mídia
Quando o serviço recebe o método de callback do ciclo de vida de onCreate(), ele executa estas etapas:
- Crie e inicialize a sessão de mídia
- Definir o callback da sessão de mídia
- Definir o token de sessão de mídia
O código onCreate() a seguir demonstra essas etapas:
Kotlin
private const val MY_MEDIA_ROOT_ID = "media_root_id" private const val MY_EMPTY_MEDIA_ROOT_ID = "empty_root_id" class MediaPlaybackService : MediaBrowserServiceCompat() { private var mediaSession: MediaSessionCompat? = null private lateinit var stateBuilder: PlaybackStateCompat.Builder override fun onCreate() { super.onCreate() // Create a MediaSessionCompat mediaSession = MediaSessionCompat(baseContext, LOG_TAG).apply { // Enable callbacks from MediaButtons and TransportControls setFlags(MediaSessionCompat.FLAG_HANDLES_MEDIA_BUTTONS or MediaSessionCompat.FLAG_HANDLES_TRANSPORT_CONTROLS ) // Set an initial PlaybackState with ACTION_PLAY, so media buttons can start the player stateBuilder = PlaybackStateCompat.Builder() .setActions(PlaybackStateCompat.ACTION_PLAY or PlaybackStateCompat.ACTION_PLAY_PAUSE ) setPlaybackState(stateBuilder.build()) // MySessionCallback() has methods that handle callbacks from a media controller setCallback(MySessionCallback()) // Set the session's token so that client activities can communicate with it. setSessionToken(sessionToken) } } }
Java
public class MediaPlaybackService extends MediaBrowserServiceCompat { private static final String MY_MEDIA_ROOT_ID = "media_root_id"; private static final String MY_EMPTY_MEDIA_ROOT_ID = "empty_root_id"; private MediaSessionCompat mediaSession; private PlaybackStateCompat.Builder stateBuilder; @Override public void onCreate() { super.onCreate(); // Create a MediaSessionCompat mediaSession = new MediaSessionCompat(context, LOG_TAG); // Enable callbacks from MediaButtons and TransportControls mediaSession.setFlags( MediaSessionCompat.FLAG_HANDLES_MEDIA_BUTTONS | MediaSessionCompat.FLAG_HANDLES_TRANSPORT_CONTROLS); // Set an initial PlaybackState with ACTION_PLAY, so media buttons can start the player stateBuilder = new PlaybackStateCompat.Builder() .setActions( PlaybackStateCompat.ACTION_PLAY | PlaybackStateCompat.ACTION_PLAY_PAUSE); mediaSession.setPlaybackState(stateBuilder.build()); // MySessionCallback() has methods that handle callbacks from a media controller mediaSession.setCallback(new MySessionCallback()); // Set the session's token so that client activities can communicate with it. setSessionToken(mediaSession.getSessionToken()); } }
Gerenciar conexões de clientes
Um MediaBrowserService tem dois métodos que gerenciam conexões de cliente: onGetRoot() controla o acesso ao serviço, e onLoadChildren() fornece a capacidade de um cliente criar e exibir um menu da hierarquia de conteúdo de MediaBrowserService.
Como controlar as conexões do cliente com onGetRoot()
O método onGetRoot() retorna o nó raiz da hierarquia de conteúdo. Se o método retornar nulo, a conexão será recusada.
Para permitir que os clientes se conectem ao serviço e naveguem no conteúdo de mídia, onGetRoot() precisa retornar um BrowserRoot não nulo, que é um ID raiz que representa a hierarquia de conteúdo.
Para permitir que os clientes se conectem à MediaSession sem navegar, onGetRoot()
ainda precisa retornar um BrowserRoot não nulo, mas o ID raiz precisa representar uma
hierarquia de conteúdo vazia.
Uma implementação típica de onGetRoot() pode ter esta aparência:
Kotlin
override fun onGetRoot( clientPackageName: String, clientUid: Int, rootHints: Bundle? ): MediaBrowserServiceCompat.BrowserRoot { // (Optional) Control the level of access for the specified package name. // You'll need to write your own logic to do this. return if (allowBrowsing(clientPackageName, clientUid)) { // Returns a root ID that clients can use with onLoadChildren() to retrieve // the content hierarchy. MediaBrowserServiceCompat.BrowserRoot(MY_MEDIA_ROOT_ID, null) } else { // Clients can connect, but this BrowserRoot is an empty hierarchy // so onLoadChildren returns nothing. This disables the ability to browse for content. MediaBrowserServiceCompat.BrowserRoot(MY_EMPTY_MEDIA_ROOT_ID, null) } }
Java
@Override public BrowserRoot onGetRoot(String clientPackageName, int clientUid, Bundle rootHints) { // (Optional) Control the level of access for the specified package name. // You'll need to write your own logic to do this. if (allowBrowsing(clientPackageName, clientUid)) { // Returns a root ID that clients can use with onLoadChildren() to retrieve // the content hierarchy. return new BrowserRoot(MY_MEDIA_ROOT_ID, null); } else { // Clients can connect, but this BrowserRoot is an empty hierarchy // so onLoadChildren returns nothing. This disables the ability to browse for content. return new BrowserRoot(MY_EMPTY_MEDIA_ROOT_ID, null); } }
Em alguns casos, talvez você queira controlar quem pode se conectar ao seu
MediaBrowserService. Uma maneira é usar uma lista de controle de acesso (ACL) que especifica quais conexões são permitidas ou, alternativamente, enumera quais conexões devem ser proibidas. Para ver um exemplo de como implementar uma ACL que
permite conexões específicas, consulte a classe PackageValidator no
app de exemplo Universal Android Music Player.
Considere a possibilidade de fornecer hierarquias de conteúdo diferentes, dependendo do tipo de cliente que está fazendo a consulta. Especificamente, o Android Auto limita a interação dos usuários com apps de áudio. Para saber mais, consulte a seção Como reproduzir áudio para o Android Auto. Você pode ver o clientPackageName no momento da conexão para determinar o tipo de cliente e retornar uma BrowserRoot dependendo do cliente (ou rootHints se houver).
Como comunicar conteúdo com onLoadChildren()
Depois que o cliente se conecta, ele pode atravessar a hierarquia de conteúdo fazendo
chamadas repetidas para MediaBrowserCompat.subscribe() para criar uma representação local
da interface. O método subscribe() envia o callback
onLoadChildren() ao serviço, que retorna uma lista de objetos MediaBrowser.MediaItem.
Cada MediaItem tem uma string de ID exclusiva, que é um token opaco. Quando um cliente quer abrir um submenu ou reproduzir um item, ele passa o ID. O serviço é responsável por associar o ID ao nó do menu ou item de conteúdo apropriado.
Uma implementação simples de onLoadChildren() teria esta aparência:
Kotlin
override fun onLoadChildren( parentMediaId: String, result: MediaBrowserServiceCompat.Result<List<MediaBrowserCompat.MediaItem>> ) { // Browsing not allowed if (MY_EMPTY_MEDIA_ROOT_ID == parentMediaId) { result.sendResult(null) return } // Assume for example that the music catalog is already loaded/cached. val mediaItems = emptyList<MediaBrowserCompat.MediaItem>() // Check if this is the root menu: if (MY_MEDIA_ROOT_ID == parentMediaId) { // Build the MediaItem objects for the top level, // and put them in the mediaItems list... } else { // Examine the passed parentMediaId to see which submenu we're at, // and put the children of that menu in the mediaItems list... } result.sendResult(mediaItems) }
Java
@Override public void onLoadChildren(final String parentMediaId, final Result<List<MediaItem>> result) { // Browsing not allowed if (TextUtils.equals(MY_EMPTY_MEDIA_ROOT_ID, parentMediaId)) { result.sendResult(null); return; } // Assume for example that the music catalog is already loaded/cached. List<MediaItem> mediaItems = new ArrayList<>(); // Check if this is the root menu: if (MY_MEDIA_ROOT_ID.equals(parentMediaId)) { // Build the MediaItem objects for the top level, // and put them in the mediaItems list... } else { // Examine the passed parentMediaId to see which submenu we're at, // and put the children of that menu in the mediaItems list... } result.sendResult(mediaItems); }
Observação : os objetos MediaItem entregues pelo MediaBrowserService
não podem conter bitmaps de ícone. Em vez disso, use Uri chamando setIconUri() ao criar MediaDescription para cada item.
Para ver um exemplo de como implementar onLoadChildren(), consulte o app de amostra Universal
Android Music Player.
O ciclo de vida do serviço do navegador de mídia
O comportamento de um serviço para Android depende de ser iniciado ou vinculado a um ou mais clientes. Depois de ser criado, um serviço pode ser iniciado, vinculado ou ambos. Em todos esses estados, ele é totalmente funcional e pode executar o trabalho para que foi projetado. A diferença é o tempo de existência do serviço. Um serviço vinculado não é destruído até que todos os seus clientes se desvinculem. Um serviço iniciado pode ser explicitamente interrompido e destruído (supondo que ele não esteja mais vinculado a nenhum cliente).
Quando um MediaBrowser em execução em outra atividade se conecta a um
MediaBrowserService, ele vincula a atividade ao serviço, tornando-o
vinculado (mas não iniciado). Esse comportamento padrão é integrado à classe
MediaBrowserServiceCompat.
Um serviço que só é vinculado (e não iniciado) é destruído quando todos os clientes se desvinculam. Se a atividade da UI é desconectada nesse momento, o serviço é destruído. Isso não é um problema, caso você ainda não tenha tocado nenhuma música. No entanto, quando a reprodução começa, o usuário provavelmente espera continuar ouvindo mesmo depois de trocar de app. Você não quer destruir o player ao desvincular a UI para funcionar com outro app.
Por esse motivo, você precisa ter certeza de que o serviço seja iniciado quando começar a ser reproduzido chamando startService(). Um serviço iniciado precisa ser explicitamente interrompido, esteja ou não vinculado. Isso
garante que o player continue funcionando mesmo que a atividade de UI de controle
seja desvinculada.
Para interromper um serviço iniciado, chame Context.stopService() ou stopSelf(). O sistema interrompe e destrói o serviço o mais rápido possível. No entanto, se um ou mais clientes ainda estiverem vinculados, a chamada para interromper o serviço será adiada até que todos os clientes se desvinculem.
O ciclo de vida de MediaBrowserService é controlado pela forma como foi criado, pelo número de clientes vinculados a ele e pelas chamadas recebidas de callbacks de sessão de mídia. Para resumir:
- O serviço é criado quando é iniciado em resposta a um botão de mídia ou quando uma atividade é vinculada a ele, depois de se conectar via
MediaBrowser. - O callback da sessão de mídia
onPlay()precisa incluir o código que chamastartService(). Isso garante que o serviço seja iniciado e continue em execução, mesmo quando todas as atividadesMediaBrowserda IU que estão vinculadas a ele forem desvinculadas. - O callback
onStop()precisa chamarstopSelf(). Se o serviço tiver sido iniciado, ele o interrompe. Além disso, o serviço será destruído se não houver atividades vinculadas a ele. Caso contrário, o serviço permanecerá vinculado até que todas as atividades dele sejam desvinculadas. Se uma chamadastartService()subsequente for recebida antes de o serviço ser destruído, a parada pendente será cancelada.
O fluxograma a seguir demonstra como o ciclo de vida de um serviço é gerenciado. O contador variável rastreia o número de clientes vinculados:

Como usar as notificações do MediaStyle com um serviço em primeiro plano
Quando um serviço está sendo reproduzido, ele precisa estar sendo executado em primeiro plano. Isso permite que o sistema saiba que o serviço está desempenhando uma função útil e não pode ser interrompido se o sistema estiver com pouca memória. Um serviço em primeiro plano precisa exibir uma notificação para que o usuário saiba sobre ele e tenha a opção de controlá-lo. O callback onPlay() precisa colocar o serviço em primeiro plano. Observe que o significado de "primeiro plano" aqui é especial. Embora o Android considere o serviço em primeiro plano para fins de gerenciamento de processos, para o usuário, o player está tocando em segundo plano enquanto algum outro app está visível em "primeiro plano" na tela.
Quando um serviço é executado em primeiro plano, ele precisa exibir uma notificação, de preferência com um ou mais controles de transporte. A notificação também precisa incluir informações úteis dos metadados da sessão.
Crie e exiba a notificação quando o player começar a tocar. O melhor lugar para fazer isso é dentro do método MediaSessionCompat.Callback.onPlay().
O exemplo abaixo usa o
NotificationCompat.MediaStyle,
que foi criado para apps de mídia. Ele mostra como criar uma notificação que exiba metadados e controles de transporte. O método de conveniência
getController()
permite criar um controlador de mídia diretamente da sua sessão de mídia.
Kotlin
// Given a media session and its context (usually the component containing the session) // Create a NotificationCompat.Builder // Get the session's metadata val controller = mediaSession.controller val mediaMetadata = controller.metadata val description = mediaMetadata.description val builder = NotificationCompat.Builder(context, channelId).apply { // Add the metadata for the currently playing track setContentTitle(description.title) setContentText(description.subtitle) setSubText(description.description) setLargeIcon(description.iconBitmap) // Enable launching the player by clicking the notification setContentIntent(controller.sessionActivity) // Stop the service when the notification is swiped away setDeleteIntent( MediaButtonReceiver.buildMediaButtonPendingIntent( context, PlaybackStateCompat.ACTION_STOP ) ) // Make the transport controls visible on the lockscreen setVisibility(NotificationCompat.VISIBILITY_PUBLIC) // Add an app icon and set its accent color // Be careful about the color setSmallIcon(R.drawable.notification_icon) color = ContextCompat.getColor(context, R.color.primaryDark) // Add a pause button addAction( NotificationCompat.Action( R.drawable.pause, getString(R.string.pause), MediaButtonReceiver.buildMediaButtonPendingIntent( context, PlaybackStateCompat.ACTION_PLAY_PAUSE ) ) ) // Take advantage of MediaStyle features setStyle(android.support.v4.media.app.NotificationCompat.MediaStyle() .setMediaSession(mediaSession.sessionToken) .setShowActionsInCompactView(0) // Add a cancel button .setShowCancelButton(true) .setCancelButtonIntent( MediaButtonReceiver.buildMediaButtonPendingIntent( context, PlaybackStateCompat.ACTION_STOP ) ) ) } // Display the notification and place the service in the foreground startForeground(id, builder.build())
Java
// Given a media session and its context (usually the component containing the session) // Create a NotificationCompat.Builder // Get the session's metadata MediaControllerCompat controller = mediaSession.getController(); MediaMetadataCompat mediaMetadata = controller.getMetadata(); MediaDescriptionCompat description = mediaMetadata.getDescription(); NotificationCompat.Builder builder = new NotificationCompat.Builder(context, channelId); builder // Add the metadata for the currently playing track .setContentTitle(description.getTitle()) .setContentText(description.getSubtitle()) .setSubText(description.getDescription()) .setLargeIcon(description.getIconBitmap()) // Enable launching the player by clicking the notification .setContentIntent(controller.getSessionActivity()) // Stop the service when the notification is swiped away .setDeleteIntent(MediaButtonReceiver.buildMediaButtonPendingIntent(context, PlaybackStateCompat.ACTION_STOP)) // Make the transport controls visible on the lockscreen .setVisibility(NotificationCompat.VISIBILITY_PUBLIC) // Add an app icon and set its accent color // Be careful about the color .setSmallIcon(R.drawable.notification_icon) .setColor(ContextCompat.getColor(context, R.color.primaryDark)) // Add a pause button .addAction(new NotificationCompat.Action( R.drawable.pause, getString(R.string.pause), MediaButtonReceiver.buildMediaButtonPendingIntent(context, PlaybackStateCompat.ACTION_PLAY_PAUSE))) // Take advantage of MediaStyle features .setStyle(new MediaStyle() .setMediaSession(mediaSession.getSessionToken()) .setShowActionsInCompactView(0) // Add a cancel button .setShowCancelButton(true) .setCancelButtonIntent(MediaButtonReceiver.buildMediaButtonPendingIntent(context, PlaybackStateCompat.ACTION_STOP))); // Display the notification and place the service in the foreground startForeground(id, builder.build());
Ao usar as notificações do MediaStyle, esteja ciente do comportamento destas configurações do NotificationCompat:
- Quando você usa
setContentIntent(), seu serviço começa automaticamente quando a notificação é clicada, um recurso útil. - Em uma situação "não confiável", como a tela de bloqueio, a visibilidade padrão para o conteúdo das notificações é
VISIBILITY_PRIVATE. É provável que você queira ver os controles de transporte na tela de bloqueio.VISIBILITY_PUBLICé a melhor opção. - Cuidado ao definir a cor do plano de fundo. Em uma notificação comum no Android versão 5.0 ou posterior, a cor é aplicada somente ao plano de fundo do ícone pequeno do app. Mas, para as notificações do MediaStyle anteriores ao Android 7.0, a cor é usada para todo o plano de fundo da notificação. Teste a cor do plano de fundo. Suavize a aparência e evite cores extremamente brilhantes ou fluorescentes.
Essas configurações só estão disponíveis quando você usa NotificationCompat.MediaStyle:
- Use
setMediaSession()para associar a notificação à sua sessão. Isso permite que apps de terceiros e dispositivos complementares acessem e controlem a sessão. - Use
setShowActionsInCompactView()para adicionar até três ações a serem mostradas no ContentView de tamanho padrão da notificação. Aqui o botão de pausa é especificado. - No Android 5.0 (nível da API 21) e versões mais recentes, é possível deslizar uma notificação para parar o player quando o serviço não estiver mais sendo executado em primeiro plano. Não é possível fazer isso em versões anteriores. Para permitir que os usuários removam a notificação e parem a reprodução antes do Android 5.0 (nível da API 21), adicione um botão de cancelamento no canto superior direito da notificação chamando
setShowCancelButton(true)esetCancelButtonIntent().
Ao adicionar os botões de pausa e cancelamento, você precisará de um PendingIntent para anexar à ação de reprodução. O método MediaButtonReceiver.buildMediaButtonPendingIntent() faz a função de converter uma ação PlaybackState em PendingIntent.
Ativar a navegação de mídia AVRCP
Além de apps personalizados, como o Android Auto, a camada Bluetooth do sistema também
funciona como um cliente do seu MediaBrowserService para facilitar a navegação remota
sem fio no catálogo (AVRCP).
No Android 16 e no Android 17, a plataforma exige que os apps que não usam o Media3 exponham uma atividade específica com um filtro de intent para serem validados para navegação.
Adicione esse filtro de intent específico a uma atividade exportada no seu
AndroidManifest.xml. Observe que CATEGORY_DEFAULT é omitido intencionalmente para
evitar que o app apareça em menus genéricos "Abrir com" para arquivos de áudio
locais:
<activity
android:name=".BluetoothValidationActivity"
android:exported="true"
android:theme="@android:style/Theme.NoDisplay"
android:excludeFromRecents="true"
android:noHistory="true">
<intent-filter>
<action android:name="android.intent.action.VIEW" />
<data android:scheme="content" />
<data android:host="media" />
<!-- Specific path check used by Bluetooth stack for validation -->
<data android:pathPrefix="/internal/audio/media/" />
<data android:mimeType="audio/*" />
</intent-filter>
</activity>