Como criar um serviço de navegador de mídia

O app precisa declarar o MediaBrowserService com um filtro de intent no manifesto. Você pode escolher um nome de serviço próprio. No exemplo a seguir, é "MediaPlaybackService".

<service android:name=".MediaPlaybackService">
      <intent-filter>
        <action android:name="android.media.browse.MediaBrowserService" />
      </intent-filter>
    </service>
    

Observação: a implementação recomendada de MediaBrowserService é MediaBrowserServiceCompat, que é definido na Biblioteca de Suporte media-compat. Nesta página, o termo “MediaBrowserService” se refere a uma instância de MediaBrowserServiceCompat.

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:

• Criar e inicializar 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() abaixo demonstra estas etapas:

    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)
            }
        }
    }
    

    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 .

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:

    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 hierachy
            // so onLoadChildren returns nothing. This disables the ability to browse for content.
            MediaBrowserServiceCompat.BrowserRoot(MY_EMPTY_MEDIA_ROOT_ID, null)
        }
    }
    

    @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 hierachy
            // so onLoadChildren returns nothing. This disables the ability to browse for content.
            return new BrowserRoot(MY_EMPTY_MEDIA_ROOT_ID, null);
        }
    }
    

Em alguns casos, convém implementar um esquema de lista de permissões/proibições para controlar as conexões. Para ver um exemplo de lista de permissões, consulte a classe PackageValidator no app de amostra 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 IU. 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 código. O serviço é responsável por associar o código ao nó do menu ou ao item de conteúdo apropriado.

Uma implementação simples de onLoadChildren() teria esta aparência:

    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)
    }
    

    @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: MediaItem os objetos 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(), veja 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 estar 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 IU é 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 IU 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 a funcionar, 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 chama startService(). Isso garante que o serviço seja iniciado e continue em execução, mesmo quando todas as atividades MediaBrowser da IU que estão vinculadas a ele forem desvinculadas.
• O callback onStop() precisa chamar stopSelf(). 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 chamada startService() 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 do processo, 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 que você crie um controlador de mídia diretamente da sua sessão de mídia.

    // 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())
    

    // 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 dessas 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 exibidas no ContentView de tamanho padrão da notificação. Aqui o botão de pausa é especificado.
• No Android 5.0 (API de nível 21) e versões posteriores, é 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 (API de nível 21), você pode adicionar um botão de cancelamento no canto superior direito da notificação, chamando setShowCancelButton(true) e setCancelButtonIntent().

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.