Выходной переключатель

Переключатель вывода — это функция Cast SDK, которая обеспечивает плавную передачу между локальным и удаленным воспроизведением контента, начиная с Android 13. Цель — помочь приложениям-отправителям легко и быстро контролировать, где воспроизводится контент. Output Switcher использует библиотеку MediaRouter для переключения воспроизведения контента между динамиком телефона, сопряженными устройствами Bluetooth и удаленными устройствами с поддержкой Cast. Варианты использования можно разбить на следующие сценарии:

• Локальное-удаленное
• Удаленное-локальное

Загрузите и используйте приведенный ниже образец, чтобы узнать, как реализовать переключатель вывода в вашем аудиоприложении. Инструкции по запуску примера см. в прилагаемом файле README.md .

Скачать образец

Ключевой термин: в этом руководстве термин «локальный» относится к любому сопряженному устройству Bluetooth или мобильному устройству (например, телефонам и планшетам), на котором запускается приложение, а термин «удаленный» относится к любому устройству с поддержкой Cast.

Переключатель выходов должен быть включен для поддержки локального-удаленного и удаленного-локального каналов, выполнив действия, описанные в этом руководстве. Для поддержки передачи между динамиками локального устройства и сопряженными устройствами Bluetooth не требуется никаких дополнительных действий.

Аудиоприложения – это приложения, поддерживающие Google Cast для аудио в настройках приложения-приемника в консоли разработчика Google Cast SDK.

Пользовательский интерфейс переключателя выходов

Переключатель выходов отображает доступные локальные и удаленные устройства, а также текущее состояние устройства, включая текущий уровень громкости, если устройство выбрано и подключено. Если помимо текущего устройства есть другие устройства, нажатие на другое устройство позволяет перенести воспроизведение мультимедиа на выбранное устройство.

Известные вопросы

• Медиа-сеансы, созданные для локального воспроизведения, будут закрыты и созданы заново при переключении на уведомление Cast SDK.

Точки входа

Уведомление СМИ

Если приложение публикует мультимедийное уведомление с помощью MediaSession для локального воспроизведения (локального воспроизведения), в правом верхнем углу мультимедийного уведомления отображается чип уведомления с именем устройства (например, динамика телефона), на котором в данный момент воспроизводится контент. Нажатие на чип уведомлений открывает пользовательский интерфейс диалоговой системы переключателя вывода.

Настройки громкости

Пользовательский интерфейс диалоговой системы переключателя вывода также можно вызвать, щелкнув кнопки физической громкости на устройстве, коснувшись значка настроек внизу и коснувшись текста «Воспроизвести <Имя приложения> на <Cast Device>».

Краткое описание шагов

• Убедитесь, что предварительные условия выполнены
• Включить переключатель вывода в AndroidManifest.xml
• Обновить SessionManagerListener для фонового кастинга.
• Установите флаг setRemoteToLocalEnabled.
• Продолжить воспроизведение локально

Предварительные условия

1. Перенесите существующее приложение Android на AndroidX.
2. Обновите build.gradle вашего приложения, чтобы использовать минимально необходимую версию Android Sender SDK для переключателя вывода:

   dependencies {
     ...
     implementation 'com.google.android.gms:play-services-cast-framework:21.2.0'
     ...
   }

3. Приложение поддерживает медиа-уведомления.
4. Устройство под управлением Android 13.

Настройка медиа-уведомлений

Чтобы использовать переключатель вывода, аудио- и видеоприложения должны создать медиа-уведомление для отображения статуса воспроизведения и элементов управления медиафайлами для локального воспроизведения. Для этого необходимо создать MediaSession , установить MediaStyle с помощью токена MediaSession и настроить элементы управления мультимедиа в уведомлении.

Если вы в настоящее время не используете MediaStyle и MediaSession , в приведенном ниже фрагменте показано, как их настроить, а также доступны руководства по настройке обратных вызовов мультимедийного сеанса для аудио- и видеоприложений :

Котлин

// Create a media session. NotificationCompat.MediaStyle
// PlayerService is your own Service or Activity responsible for media playback.
val mediaSession = MediaSessionCompat(this, "PlayerService")

// Create a MediaStyle object and supply your media session token to it.
val mediaStyle = Notification.MediaStyle().setMediaSession(mediaSession.sessionToken)

// Create a Notification which is styled by your MediaStyle object.
// This connects your media session to the media controls.
// Don't forget to include a small icon.
val notification = Notification.Builder(this@PlayerService, CHANNEL_ID)
    .setStyle(mediaStyle)
    .setSmallIcon(R.drawable.ic_app_logo)
    .build()

// Specify any actions which your users can perform, such as pausing and skipping to the next track.
val pauseAction: Notification.Action = Notification.Action.Builder(
        pauseIcon, "Pause", pauseIntent
    ).build()
notification.addAction(pauseAction)

Джава

if (android.os.Build.VERSION.SDK_INT >= android.os.Build.VERSION_CODES.O) {
    // Create a media session. NotificationCompat.MediaStyle
    // PlayerService is your own Service or Activity responsible for media playback.
    MediaSession mediaSession = new MediaSession(this, "PlayerService");

    // Create a MediaStyle object and supply your media session token to it.
    Notification.MediaStyle mediaStyle = new Notification.MediaStyle().setMediaSession(mediaSession.getSessionToken());

    // Specify any actions which your users can perform, such as pausing and skipping to the next track.
    Notification.Action pauseAction = Notification.Action.Builder(pauseIcon, "Pause", pauseIntent).build();

    // Create a Notification which is styled by your MediaStyle object.
    // This connects your media session to the media controls.
    // Don't forget to include a small icon.
    String CHANNEL_ID = "CHANNEL_ID";
    Notification notification = new Notification.Builder(this, CHANNEL_ID)
        .setStyle(mediaStyle)
        .setSmallIcon(R.drawable.ic_app_logo)
        .addAction(pauseAction)
        .build();
}

Кроме того, чтобы заполнить уведомление информацией о вашем медиафайле, вам потребуется добавить метаданные вашего медиафайла и состояние воспроизведения в MediaSession .

Чтобы добавить метаданные в MediaSession , используйте setMetaData() и укажите все соответствующие константы MediaMetadata для вашего мультимедиа в MediaMetadataCompat.Builder() .

Котлин

mediaSession.setMetadata(MediaMetadataCompat.Builder()
    // Title
    .putString(MediaMetadata.METADATA_KEY_TITLE, currentTrack.title)

    // Artist
    // Could also be the channel name or TV series.
    .putString(MediaMetadata.METADATA_KEY_ARTIST, currentTrack.artist)

    // Album art
    // Could also be a screenshot or hero image for video content
    // The URI scheme needs to be "content", "file", or "android.resource".
    .putString(
        MediaMetadata.METADATA_KEY_ALBUM_ART_URI, currentTrack.albumArtUri)
    )

    // Duration
    // If duration isn't set, such as for live broadcasts, then the progress
    // indicator won't be shown on the seekbar.
    .putLong(MediaMetadata.METADATA_KEY_DURATION, currentTrack.duration)

    .build()
)

Джава

if (android.os.Build.VERSION.SDK_INT >= android.os.Build.VERSION_CODES.O) {
    mediaSession.setMetadata(
        new MediaMetadataCompat.Builder()
        // Title
        .putString(MediaMetadata.METADATA_KEY_TITLE, currentTrack.title)

        // Artist
        // Could also be the channel name or TV series.
        .putString(MediaMetadata.METADATA_KEY_ARTIST, currentTrack.artist)

        // Album art
        // Could also be a screenshot or hero image for video content
        // The URI scheme needs to be "content", "file", or "android.resource".
        .putString(MediaMetadata.METADATA_KEY_ALBUM_ART_URI, currentTrack.albumArtUri)

        // Duration
        // If duration isn't set, such as for live broadcasts, then the progress
        // indicator won't be shown on the seekbar.
        .putLong(MediaMetadata.METADATA_KEY_DURATION, currentTrack.duration)

        .build()
    );
}

Чтобы добавить состояние воспроизведения в MediaSession , используйте setPlaybackState() и укажите все соответствующие константы PlaybackStateCompat для вашего мультимедиа в PlaybackStateCompat.Builder() .

Котлин

mediaSession.setPlaybackState(
    PlaybackStateCompat.Builder()
        .setState(
            PlaybackStateCompat.STATE_PLAYING,

            // Playback position
            // Used to update the elapsed time and the progress bar.
            mediaPlayer.currentPosition.toLong(),

            // Playback speed
            // Determines the rate at which the elapsed time changes.
            playbackSpeed
        )

        // isSeekable
        // Adding the SEEK_TO action indicates that seeking is supported
        // and makes the seekbar position marker draggable. If this is not
        // supplied seek will be disabled but progress will still be shown.
        .setActions(PlaybackStateCompat.ACTION_SEEK_TO)
        .build()
)

Джава

if (android.os.Build.VERSION.SDK_INT >= android.os.Build.VERSION_CODES.O) {
    mediaSession.setPlaybackState(
        new PlaybackStateCompat.Builder()
            .setState(
                 PlaybackStateCompat.STATE_PLAYING,

                // Playback position
                // Used to update the elapsed time and the progress bar.
                mediaPlayer.currentPosition.toLong(),

                // Playback speed
                // Determines the rate at which the elapsed time changes.
                playbackSpeed
            )

        // isSeekable
        // Adding the SEEK_TO action indicates that seeking is supported
        // and makes the seekbar position marker draggable. If this is not
        // supplied seek will be disabled but progress will still be shown.
        .setActions(PlaybackStateCompat.ACTION_SEEK_TO)
        .build()
    );
}

Поведение уведомлений видеоприложений

Видеоприложения или аудиоприложения, которые не поддерживают локальное воспроизведение в фоновом режиме, должны иметь особое поведение для мультимедийных уведомлений, чтобы избежать проблем с отправкой мультимедийных команд в ситуациях, когда воспроизведение не поддерживается:

• Публикуйте медиа-уведомление при локальном воспроизведении мультимедиа, когда приложение находится на переднем плане.
• Приостановите локальное воспроизведение и закройте уведомление, когда приложение работает в фоновом режиме.
• Когда приложение вернется на передний план, локальное воспроизведение должно возобновиться, а уведомление должно быть повторно опубликовано.

Включить переключатель вывода в AndroidManifest.xml

Чтобы включить переключатель вывода, необходимо добавить MediaTransferReceiver в AndroidManifest.xml приложения. В противном случае эта функция не будет включена, а флаг функции удаленного доступа к локальному также будет недействителен.

<application>
    ...
    <receiver
         android:name="androidx.mediarouter.media.MediaTransferReceiver"
         android:exported="true">
    </receiver>
    ...
</application>

MediaTransferReceiver — это широковещательный приемник, который обеспечивает передачу мультимедиа между устройствами с системным пользовательским интерфейсом. Дополнительные сведения см. в справочнике по MediaTransferReceiver .

Локальный-удаленный

Когда пользователь переключает воспроизведение с локального на удаленное, Cast SDK автоматически запускает сеанс Cast. Однако приложениям необходимо обрабатывать переключение с локального режима на удаленный, например останавливать локальное воспроизведение и загружать медиафайлы на устройство Cast. Приложения должны прослушивать Cast SessionManagerListener , используя обратные вызовы onSessionStarted() и onSessionEnded() , и обрабатывать действие при получении обратных вызовов Cast SessionManager . Приложения должны гарантировать, что эти обратные вызовы все еще активны, когда диалоговое окно «Переключатель вывода» открыто, а приложение не находится на переднем плане.

Обновить SessionManagerListener для фонового кастинга.

Внимание: из-за жизненного цикла действий приложениям, поддерживающим фоновое воспроизведение (аудиоприложения), рекомендуется использовать службу, а не действие для обратных вызовов SessionManagerListener , чтобы предотвратить отмену регистрации необходимых обратных вызовов при остановке действия.

Устаревшая версия Cast уже поддерживает передачу данных от локального к удаленному, когда приложение находится на переднем плане. Типичный процесс трансляции начинается, когда пользователи нажимают значок Cast в приложении и выбирают устройство для потоковой передачи мультимедиа. В этом случае приложению необходимо зарегистрироваться в SessionManagerListener в onCreate() или onStart() и отменить регистрацию прослушивателя в onStop() или onDestroy() активности приложения.

Благодаря новым возможностям трансляции с помощью переключателя вывода приложения могут начинать трансляцию, когда они находятся в фоновом режиме. Это особенно полезно для аудиоприложений, которые отправляют уведомления при воспроизведении в фоновом режиме. Приложения могут зарегистрировать прослушиватели SessionManager в onCreate() службы и отменить регистрацию в onDestroy() службы. Таким образом, приложения всегда должны получать обратные вызовы между локальным и удаленным доступом (например, onSessionStarted ), когда приложение находится в фоновом режиме.

Если приложение использует MediaBrowserService , рекомендуется зарегистрировать там SessionManagerListener .

Котлин

class MyService : Service() {
    private var castContext: CastContext? = null
    protected fun onCreate() {
        castContext = CastContext.getSharedInstance(this)
        castContext
            .getSessionManager()
            .addSessionManagerListener(sessionManagerListener, CastSession::class.java)
    }

    protected fun onDestroy() {
        if (castContext != null) {
            castContext
                .getSessionManager()
                .removeSessionManagerListener(sessionManagerListener, CastSession::class.java)
        }
    }
}

Джава

public class MyService extends Service {
  private CastContext castContext;

  @Override
  protected void onCreate() {
     castContext = CastContext.getSharedInstance(this);
     castContext
        .getSessionManager()
        .addSessionManagerListener(sessionManagerListener, CastSession.class);
  }

  @Override
  protected void onDestroy() {
    if (castContext != null) {
       castContext
          .getSessionManager()
          .removeSessionManagerListener(sessionManagerListener, CastSession.class);
    }
  }
}

Благодаря этому обновлению локальная и удаленная трансляция действует так же, как и традиционная трансляция, когда приложение находится в фоновом режиме, и для переключения с устройств Bluetooth на устройства Cast не требуется дополнительных действий.

Примечание. Чтобы обеспечить плавный переход от локального режима к удаленному, рекомендуется остановить воспроизведение на локальном устройстве во время обратного вызова onSessionStarted после успешного подключения Cast SDK к получателю. Это гарантирует, что локальное воспроизведение будет остановлено только после возобновления воспроизведения на удаленном устройстве и возникнут проблемы с синхронизацией из-за задержки.

Удаленное-локальное

Переключатель вывода обеспечивает возможность передачи с удаленного воспроизведения на динамик телефона или локальное устройство Bluetooth. Это можно включить, установив для флага setRemoteToLocalEnabled значение true в CastOptions .

В случаях, когда текущее устройство-отправитель присоединяется к существующему сеансу с несколькими отправителями и приложению необходимо проверить, разрешена ли локальная передача текущего мультимедиа, приложения должны использовать обратный вызов onTransferred SessionTransferCallback для проверки SessionState .

Установите флаг setRemoteToLocalEnabled.

CastOptions предоставляет setRemoteToLocalEnabled для отображения или скрытия динамика телефона и локальных устройств Bluetooth в качестве целевых объектов передачи в диалоговом окне переключателя вывода при наличии активного сеанса трансляции.

Котлин

class CastOptionsProvider : OptionsProvider {
    fun getCastOptions(context: Context?): CastOptions {
        ...
        return Builder()
            ...
            .setRemoteToLocalEnabled(true)
            .build()
    }
}

Джава

public class CastOptionsProvider implements OptionsProvider {
    @Override
    public CastOptions getCastOptions(Context context) {
        ...
        return new CastOptions.Builder()
            ...
            .setRemoteToLocalEnabled(true)
            .build()
  }
}

Продолжить воспроизведение локально

Приложения, поддерживающие удаленный доступ к локальному, должны зарегистрировать SessionTransferCallback чтобы получать уведомления о возникновении события, чтобы они могли проверить, разрешена ли передача мультимедиа и продолжить воспроизведение локально.

CastContext#addSessionTransferCallback(SessionTransferCallback) позволяет приложению регистрировать свой SessionTransferCallback и прослушивать обратные вызовы onTransferred и onTransferFailed , когда отправитель переводится в режим локального воспроизведения.

После того как приложение отменит регистрацию SessionTransferCallback , оно больше не будет получать SessionTransferCallback .

SessionTransferCallback является расширением существующих обратных вызовов SessionManagerListener и запускается после запуска onSessionEnded . Следовательно, порядок обратных вызовов между удаленным и локальным устройствами следующий:

1. onTransferring
2. onSessionEnding
3. onSessionEnded
4. onTransferred

Поскольку переключатель вывода может быть открыт чипом мультимедийных уведомлений, когда приложение находится в фоновом режиме и выполняет трансляцию, приложениям необходимо обрабатывать передачу на локальный компьютер по-разному в зависимости от того, поддерживают ли они фоновое воспроизведение или нет. В случае неудачной передачи onTransferFailed сработает в любой момент, когда произойдет ошибка.

Приложения, поддерживающие фоновое воспроизведение

Для приложений, поддерживающих воспроизведение в фоновом режиме (обычно аудиоприложения), рекомендуется использовать Service (например, MediaBrowserService ). Службы должны прослушивать обратный вызов onTransferred и возобновлять воспроизведение локально, как когда приложение находится на переднем плане, так и в фоновом режиме.

Котлин

class MyService : Service() {
    private var castContext: CastContext? = null
    private var sessionTransferCallback: SessionTransferCallback? = null
    protected fun onCreate() {
        castContext = CastContext.getSharedInstance(this)
        castContext.getSessionManager()
                   .addSessionManagerListener(sessionManagerListener, CastSession::class.java)
        sessionTransferCallback = MySessionTransferCallback()
        castContext.addSessionTransferCallback(sessionTransferCallback)
    }

    protected fun onDestroy() {
        if (castContext != null) {
            castContext.getSessionManager()
                       .removeSessionManagerListener(sessionManagerListener, CastSession::class.java)
            if (sessionTransferCallback != null) {
                castContext.removeSessionTransferCallback(sessionTransferCallback)
            }
        }
    }

    class MySessionTransferCallback : SessionTransferCallback() {
        fun onTransferring(@SessionTransferCallback.TransferType transferType: Int) {
            // Perform necessary steps prior to onTransferred
        }

        fun onTransferred(@SessionTransferCallback.TransferType transferType: Int,
                          sessionState: SessionState?) {
            if (transferType == SessionTransferCallback.TRANSFER_TYPE_FROM_REMOTE_TO_LOCAL) {
                // Remote stream is transferred to the local device.
                // Retrieve information from the SessionState to continue playback on the local player.
            }
        }

        fun onTransferFailed(@SessionTransferCallback.TransferType transferType: Int,
                             @SessionTransferCallback.TransferFailedReason transferFailedReason: Int) {
            // Handle transfer failure.
        }
    }
}

Джава

public class MyService extends Service {
    private CastContext castContext;
    private SessionTransferCallback sessionTransferCallback;

    @Override
    protected void onCreate() {
        castContext = CastContext.getSharedInstance(this);
        castContext.getSessionManager()
                   .addSessionManagerListener(sessionManagerListener, CastSession.class);
        sessionTransferCallback = new MySessionTransferCallback();
        castContext.addSessionTransferCallback(sessionTransferCallback);
    }

    @Override
    protected void onDestroy() {
        if (castContext != null) {
            castContext.getSessionManager()
                       .removeSessionManagerListener(sessionManagerListener, CastSession.class);
            if (sessionTransferCallback != null) {
                castContext.removeSessionTransferCallback(sessionTransferCallback);
            }
        }
    }

    public static class MySessionTransferCallback extends SessionTransferCallback {
        public MySessionTransferCallback() {}

        @Override
        public void onTransferring(@SessionTransferCallback.TransferType int transferType) {
            // Perform necessary steps prior to onTransferred
        }

        @Override
        public void onTransferred(@SessionTransferCallback.TransferType int transferType,
                                  SessionState sessionState) {
            if (transferType==SessionTransferCallback.TRANSFER_TYPE_FROM_REMOTE_TO_LOCAL) {
                // Remote stream is transferred to the local device.
                // Retrieve information from the SessionState to continue playback on the local player.
            }
        }

        @Override
        public void onTransferFailed(@SessionTransferCallback.TransferType int transferType,
                                     @SessionTransferCallback.TransferFailedReason int transferFailedReason) {
            // Handle transfer failure.
        }
    }
}

Приложения, которые не поддерживают фоновое воспроизведение

Для приложений, которые не поддерживают фоновое воспроизведение (обычно видеоприложения), рекомендуется прослушивать обратный вызов onTransferred и возобновлять воспроизведение локально, если приложение находится на переднем плане.

Если приложение работает в фоновом режиме, оно должно приостановить воспроизведение и сохранить необходимую информацию из SessionState (например, метаданные мультимедиа и позицию воспроизведения). Когда приложение выходит на передний план из фона, локальное воспроизведение должно продолжаться с сохраненной информацией.

Котлин

class MyActivity : AppCompatActivity() {
    private var castContext: CastContext? = null
    private var sessionTransferCallback: SessionTransferCallback? = null
    protected fun onCreate() {
        castContext = CastContext.getSharedInstance(this)
        castContext.getSessionManager()
                   .addSessionManagerListener(sessionManagerListener, CastSession::class.java)
        sessionTransferCallback = MySessionTransferCallback()
        castContext.addSessionTransferCallback(sessionTransferCallback)
    }

    protected fun onDestroy() {
        if (castContext != null) {
            castContext.getSessionManager()
                       .removeSessionManagerListener(sessionManagerListener, CastSession::class.java)
            if (sessionTransferCallback != null) {
                castContext.removeSessionTransferCallback(sessionTransferCallback)
            }
        }
    }

    class MySessionTransferCallback : SessionTransferCallback() {
        fun onTransferring(@SessionTransferCallback.TransferType transferType: Int) {
            // Perform necessary steps prior to onTransferred
        }

        fun onTransferred(@SessionTransferCallback.TransferType transferType: Int,
                          sessionState: SessionState?) {
            if (transferType == SessionTransferCallback.TRANSFER_TYPE_FROM_REMOTE_TO_LOCAL) {
                // Remote stream is transferred to the local device.

                // Retrieve information from the SessionState to continue playback on the local player.
            }
        }

        fun onTransferFailed(@SessionTransferCallback.TransferType transferType: Int,
                             @SessionTransferCallback.TransferFailedReason transferFailedReason: Int) {
            // Handle transfer failure.
        }
    }
}

Джава

public class MyActivity extends AppCompatActivity {
  private CastContext castContext;
  private SessionTransferCallback sessionTransferCallback;

  @Override
  protected void onCreate() {
     castContext = CastContext.getSharedInstance(this);
     castContext
        .getSessionManager()
        .addSessionManagerListener(sessionManagerListener, CastSession.class);
     sessionTransferCallback = new MySessionTransferCallback();
     castContext.addSessionTransferCallback(sessionTransferCallback);
  }

  @Override
  protected void onDestroy() {
    if (castContext != null) {
       castContext
          .getSessionManager()
          .removeSessionManagerListener(sessionManagerListener, CastSession.class);
      if (sessionTransferCallback != null) {
         castContext.removeSessionTransferCallback(sessionTransferCallback);
      }
    }
  }

  public static class MySessionTransferCallback extends SessionTransferCallback {
    public MySessionTransferCallback() {}

    @Override
    public void onTransferring(@SessionTransferCallback.TransferType int transferType) {
        // Perform necessary steps prior to onTransferred
    }

    @Override
    public void onTransferred(@SessionTransferCallback.TransferType int transferType,
                               SessionState sessionState) {
      if (transferType==SessionTransferCallback.TRANSFER_TYPE_FROM_REMOTE_TO_LOCAL) {
        // Remote stream is transferred to the local device.

        // Retrieve information from the SessionState to continue playback on the local player.
      }
    }

    @Override
    public void onTransferFailed(@SessionTransferCallback.TransferType int transferType,
                                 @SessionTransferCallback.TransferFailedReason int transferFailedReason) {
      // Handle transfer failure.
    }
  }
}