AndroidX Media3 이전 가이드

현재 독립형 com.google.android.exoplayer2을(를) 사용 중인 앱 androidx.media를 androidx.media3로 이전해야 합니다. 사용 이전 스크립트: gradle 빌드 파일, 자바 및 Kotlin 소스 파일 및 ExoPlayer의 XML 레이아웃 파일 2.19.1에서 AndroidX Media3 1.1.1로

개요

이전하기 전에 다음 섹션을 검토하여 자세히 알아보세요. 새 API의 이점, 마이그레이션할 API, 기본 요건 다양한 기준을 제시합니다.

Jetpack Media3으로 이전해야 하는 이유

  • ExoPlayer의 새로운 홈인 반면 com.google.android.exoplayer2는 중단됩니다
  • 구성요소/프로세스 전체에서 Player API에 액세스 MediaBrowser/MediaController입니다.
  • MediaSession 및 MediaController API를 사용합니다.
  • 세분화된 액세스 제어를 통해 재생 기능을 홍보하세요.
  • 앱을 간소화하여MediaSessionConnector 및 PlayerNotificationManager입니다.
  • media-compat 클라이언트 API와 하위 호환 (MediaBrowserCompat/MediaControllerCompat/MediaMetadataCompat)

AndroidX Media3으로 이전하는 Media API

  • ExoPlayer 및 확장 프로그램
    여기에는 기존 ExoPlayer 프로젝트의 모든 모듈이 포함되며, 예외적으로 mediasession 모듈을 사용할 수 없습니다. 애플리케이션 또는 모듈은 com.google.android.exoplayer2의 패키지는 다음 명령어로 마이그레이션할 수 있습니다. 마이그레이션 스크립트
  • MediaSessionConnector( androidx.media:media:1.4.3+개 중 androidx.media.*개 패키지)
    MediaSessionConnector를 삭제하고 대신 androidx.media3.session.MediaSession입니다.
  • MediaBrowserServiceCompat( androidx.media:media:1.4.3+개 중 androidx.media.*개 패키지)
    androidx.media.MediaBrowserServiceCompat의 서브클래스를 androidx.media3.session.MediaLibraryService 및 MediaBrowserCompat.MediaItem부터 androidx.media3.common.MediaItem까지입니다.
  • MediaBrowserCompat( androidx.media:media:1.4.3+개 중 android.support.v4.media.*개 패키지)
    MediaBrowserCompat를 사용하여 클라이언트 코드 마이그레이션 또는 androidx.media3.session.MediaBrowser 사용 시 MediaControllerCompat androidx.media3.common.MediaItem와(과) 비교해 보세요.

기본 요건

  1. 프로젝트가 소스 제어를 받고 있는지 확인

    스크립트 이전 도구로 적용한 변경사항을 쉽게 되돌릴 수 있어야 합니다. 아직 프로젝트를 소스 제어 대상이 아니라면 지금이 좋습니다. 살펴보겠습니다 어떤 이유로든 그렇게 하고 싶지 않다면 이전을 시작하기 전에 프로젝트의 백업 사본을 만들어야 합니다.

  2. 앱 업데이트

    • 프로젝트를 업데이트하여 최신 버전의 ExoPlayer 라이브러리를 설치한 다음 사용할 수 없습니다. 다음 작업을 수행하려는 경우: 이전에 대한 스크립트를 사용하려면 스크립트에서 처리하는 버전으로 업데이트할 새 버전입니다.

    • 앱의 compileSdkVersion을 32 이상으로 높입니다.

    • Gradle 및 Android 스튜디오 Gradle 플러그인을 최신 버전으로 업그레이드 위에서 업데이트된 종속 항목과 호환되는 버전을 제공합니다. 대상 인스턴스:

      • Android Gradle 플러그인 버전: 7.1.0
      • Gradle 버전: 7.4

    • 별표를 사용하는 모든 와일드 카드 가져오기 문 바꾸기 (*) 및 정규화된 가져오기 문 사용: 와일드 카드 삭제 import 문과 Android 스튜디오를 사용하여 정규화된 문 (F2 - Alt/Enter, F2 - Alt/Enter, ...).

    • com.google.android.exoplayer2.PlayerView에서 com.google.android.exoplayer2.StyledPlayerView 이는 필수 항목입니다. 이에 해당하는 AndroidX Media3의 com.google.android.exoplayer2.PlayerView

스크립트 지원으로 ExoPlayer 이전

이 스크립트는 com.google.android.exoplayer2에서 새 androidx.media3의 패키지 및 모듈 구조 스크립트는 프로젝트에 대한 일부 유효성 검사 검사를 하고 유효성 검사에 실패할 경우 경고를 출력합니다. 그렇지 않으면 이름이 변경된 클래스 및 패키지의 매핑을 Java 또는 Kotlin으로 작성된 Android Gradle 프로젝트의 리소스입니다.

usage: ./media3-migration.sh [-p|-c|-d|-v]|[-m|-l [-x <path>] [-f] PROJECT_ROOT]
 PROJECT_ROOT: path to your project root (location of 'gradlew')
 -p: list package mappings and then exit
 -c: list class mappings (precedence over package mappings) and then exit
 -d: list dependency mappings and then exit
 -l: list files that will be considered for rewrite and then exit
 -x: exclude the path from the list of file to be changed: 'app/src/test'
 -m: migrate packages, classes and dependencies to AndroidX Media3
 -f: force the action even when validation fails
 -v: print the exoplayer2/media3 version strings of this script
 -h, --help: show this help text

마이그레이션 스크립트 사용

  1. ExoPlayer 프로젝트의 태그에서 이전 스크립트를 다운로드합니다. 앱을 업데이트한 버전에 해당하는 GitHub입니다.

    curl -o media3-migration.sh \
  "https://raw.githubusercontent.com/google/ExoPlayer/r2.19.1/media3-migration.sh"

  2. 스크립트를 실행 가능하게 만듭니다.

    chmod 744 media3-migration.sh

  3. --help로 스크립트를 실행하여 옵션에 관해 알아봅니다.

  4. -l로 스크립트를 실행하여 선택된 파일 집합을 나열합니다. 이전 (-f을 사용하여 경고 없이 목록을 강제 표시):

    ./media3-migration.sh -l -f /path/to/gradle/project/root

  5. -m로 스크립트를 실행하여 패키지, 클래스, 모듈을 Media3에 매핑합니다. -m 옵션으로 스크립트를 실행하면 선택한 할 수 있습니다.

    • 유효성 검사 오류 발생 시 변경하지 않고 중지
    ./media3-migration.sh -m /path/to/gradle/project/root
    • 강제 실행

    스크립트가 기본 요건 위반을 발견하면 이전은 -f 플래그로 강제 적용됩니다.

    ./media3-migration.sh -m -f /path/to/gradle/project/root
를 통해 개인정보처리방침을 정의할 수 있습니다. 
 # list files selected for migration when excluding paths
 ./media3-migration.sh -l -x "app/src/test/" -x "service/" /path/to/project/root
 # migrate the selected files
 ./media3-migration.sh -m -x "app/src/test/" -x "service/" /path/to/project/root

-m 옵션을 사용하여 스크립트를 실행한 후 다음 수동 단계를 완료합니다.

  1. 스크립트에서 코드를 변경한 방식 확인: diff 도구를 사용하여 수정 잠재적 문제 (스크립트에 -f 옵션을 전달하지 않고 발생한 일반적인 문제).
  2. 프로젝트 빌드: ./gradlew clean build 또는 Android를 사용합니다. 스튜디오에서 파일 > Sync Project with Gradle Files로 이동한 후 Build > 프로젝트를 정리한 다음 Build >를 선택합니다. 프로젝트 다시 빌드 (다음 위치에서 빌드 모니터링 '빌드 - 빌드 출력' 탭으로 이동합니다.
를 통해 개인정보처리방침을 정의할 수 있습니다.

권장되는 후속 단계:

  1. 불안정한 API 사용 관련 오류 수신 동의 문제를 해결합니다.
  2. 지원 중단된 API 호출 대체: 제안된 대체 API를 사용합니다. Android 스튜디오에서 경고 위로 포인터를 가져가고 JavaDoc를 참조합니다. 특정 호출 대신 무엇을 사용해야 할지 알아봅니다.
  3. import 문 정렬: Android 스튜디오에서 프로젝트를 열고 프로젝트 뷰어에서 패키지 폴더 노드를 마우스 오른쪽 버튼으로 클릭하고 변경된 소스 파일이 포함된 패키지의 가져오기를 최적화합니다.

MediaSessionConnector를 androidx.media3.session.MediaSession로 바꿉니다.

기존 MediaSessionCompat 환경에서 MediaSessionConnector는 플레이어의 상태와 세션의 상태를 동기화합니다. 컨트롤러로부터 적절한 권한을 위임받아야 하는 사용할 수 있습니다. AndroidX Media3을 사용하면 MediaSession에서 직접 이 작업을 실행합니다. Google Cloud 서비스를 제공할 수 있습니다

  1. MediaSessionConnector의 모든 참조 및 사용 삭제: ExoPlayer 클래스 및 패키지를 마이그레이션하기 위해 자동화된 스크립트를 실행한 다음 스크립트가 컴파일할 수 없는 상태로 코드를 남겨두었을 가능성이 있으며 해결할 수 없는 MediaSessionConnector입니다. Android 스튜디오는 앱을 빌드하거나 시작하려고 할 때 손상된 코드가 표시됩니다.

  2. 종속 항목을 유지관리하는 build.gradle 파일에서 AndroidX Media3 세션 모듈에 대한 구현 종속 항목을 적용하고 기존 종속 항목은 다음과 같습니다.

    implementation "androidx.media3:media3-session:1.4.0"

  3. MediaSessionCompat를 다음으로 바꿉니다. androidx.media3.session.MediaSession

  4. 기존 MediaSessionCompat를 만든 코드 사이트에서 다음을 사용합니다. androidx.media3.session.MediaSession.Builder를 사용하여 MediaSession). 플레이어를 전달하여 세션 빌더를 구성합니다.

    val player = ExoPlayer.Builder(context).build()
mediaSession = MediaSession.Builder(context, player)
    .setSessionCallback(MySessionCallback())
    .build()

  5. 앱의 필요에 따라 MySessionCallback를 구현합니다. 이는 선택사항입니다. 만약 컨트롤러가 플레이어에 미디어 항목을 추가하고 MediaSession.Callback.onAddMediaItems() 그것은 다양한 현재 및 다양한 기존 API 메서드는 미디어 항목을 플레이어에 추가하여 이전 버전과 호환되는 방식으로 작동합니다 여기에는 Media3 컨트롤러의 MediaController.set/addMediaItems() 메서드 및 TransportControls.prepareFrom*/playFrom* 기존 API의 메서드와 비교됩니다. onAddMediaItems의 샘플 구현은 다음을 수행할 수 있습니다. 세션 데모 앱의 PlaybackService에서 확인할 수 있습니다.

  6. 세션을 폐기한 코드 사이트에서 미디어 세션 해제 해야 합니다.

    mediaSession?.run {
  player.release()
  release()
  mediaSession = null
}

Media3의 MediaSessionConnector 기능

다음 표는 기능을 처리하는 Media3 API를 보여줍니다. 이전에 MediaSessionConnector에 구현되어 있습니다.

MediaSessionConnectorAndroidX 미디어3
CustomActionProvider MediaSession.Callback.onCustomCommand()/ MediaSession.setCustomLayout()
PlaybackPreparer MediaSession.Callback.onAddMediaItems() (prepare()는 내부적으로 호출됨)
QueueNavigator ForwardingPlayer
QueueEditor MediaSession.Callback.onAddMediaItems()
RatingCallback MediaSession.Callback.onSetRating()
PlayerNotificationManager DefaultMediaNotificationProvider/ MediaNotification.Provider

MediaBrowserService를 MediaLibraryService로 이전

AndroidX Media3에는 MediaLibraryService이 도입되어 MediaBrowserServiceCompat입니다. MediaLibraryService의 JavaDoc 및 슈퍼 MediaSessionService 클래스는 API에 대한 유용한 소개와 서비스의 비동기 프로그래밍 모델입니다.

MediaLibraryService는 MediaBrowserService입니다. MediaBrowserCompat 또는 MediaControllerCompat, 연결 시 코드 변경 없이 계속 작동 MediaLibraryService로 변환합니다. 클라이언트의 경우 앱이 MediaLibraryService 또는 기존 MediaBrowserServiceCompat 사용

<ph type="x-smartling-placeholder">
</ph> 서비스, 활동, 외부 앱이 표시된 앱 구성요소 다이어그램
그림 1: 미디어 앱 구성요소 개요

  1. 이전 버전과의 호환성이 작동하려면 두 서비스를 모두 등록해야 함 인터페이스를 AndroidManifest.xml에서 서비스와 연결합니다. 이렇게 하면 필요한 서비스 인터페이스로 서비스를 찾습니다.

    <service android:name=".MusicService" android:exported="true">
    <intent-filter>
        <action android:name="androidx.media3.session.MediaLibraryService"/>
        <action android:name="android.media.browse.MediaBrowserService" />
    </intent-filter>
</service>

  2. 종속 항목을 유지관리하는 build.gradle 파일에서 AndroidX Media3 세션 모듈에 관한 구현 종속 항목 기존 종속 항목을 삭제합니다.

    implementation "androidx.media3:media3-session:1.4.0"

  3. 서비스가 MediaLibraryService에서 상속되도록 변경하는 대신 MediaBrowserService 앞서 언급했듯이 MediaLibraryService는 레거시와 호환됩니다. MediaBrowserService입니다. 따라서 서비스에 사용되는 더 광범위한 API는 고객에게 제공하는 기능은 여전히 동일합니다. 따라서 앱은 사용자가 MediaBrowserService를 구현하는 데 필요한 대부분의 로직 새 MediaLibraryService에 맞게 조정합니다.

    기존 버전과의 주요 차이점은 MediaBrowserServiceCompat는 다음과 같습니다.

    • 서비스 수명 주기 메서드 구현: 서비스 수명 주기 메서드 구현 시 onCreate/onDestroy인 경우 서비스 자체에서 재정의될 수 있습니다. 여기서 앱이 라이브러리 세션, 플레이어 및 기타 리소스를 배포합니다 앱은 표준 서비스 수명 주기 메서드 외에도 반환하려면 onGetSession(MediaSession.ControllerInfo)를 재정의해야 함 onCreate에 빌드된 MediaLibrarySession입니다.

    • MediaLibraryService.MediaLibrarySessionCallback 구현: 빌드 세션마다 다음을 구현하는 MediaLibraryService.MediaLibrarySessionCallback 실제 도메인 API 메서드에 대해 알아보겠습니다. 따라서 클러스터의 API 메서드를 재정의하는 대신 사용하는 경우 대신 MediaLibrarySession.Callback하세요.

      그런 다음 이 콜백은 MediaLibrarySession를 빌드하는 데 사용됩니다.

      mediaLibrarySession =
      MediaLibrarySession.Builder(this, player, MySessionCallback())
         .build()

      API에서 MediaLibrarySessionCallback의 전체 API를 찾습니다. 문서를 참조하세요.

    • MediaSession.Callback.onAddMediaItems() 구현: 콜백 onAddMediaItems(MediaSession, ControllerInfo, List<MediaItem>) 제공 플레이어에 미디어 항목을 추가하는 다양한 현재 및 기존 API 메서드 이전 버전과 호환되는 방식으로 재생할 수 있습니다. 여기에는 Media3 컨트롤러의 MediaController.set/addMediaItems() 메서드 TransportControls.prepareFrom*/playFrom* 기존 API의 메서드와 비교됩니다. 콜백의 샘플 구현은 세션 데모 앱의 PlaybackService에서 확인할 수 있습니다.

    • AndroidX Media3에서 androidx.media3.common.MediaItem를 대신 사용합니다. MediaBrowserCompat.MediaItem 및 MediaMetadataCompat입니다. 부품 이에 따라 기존 클래스에 연결된 코드의 일부를 변경해야 함 또는 Media3 MediaItem에 매핑합니다.

    • 일반 비동기 프로그래밍 모델이 Futures로 변경되었습니다. 분리 가능한 Result 접근법과 대비되는 MediaBrowserServiceCompat입니다. 서비스 구현은 결과를 분리하는 대신 비동기 ListenableFuture로 처리하거나 즉각적인 Future를 반환하여 값을 직접 반환합니다.

PlayerNotificationManager 삭제

MediaLibraryService는 미디어 알림을 자동으로 지원하며 PlayerNotificationManager은 MediaLibraryService 또는 MediaSessionService입니다.

앱은 알림 설정을 통해 알림을 맞춤설정할 수 있습니다. onCreate()의 MediaNotification.Provider로, DefaultMediaNotificationProvider입니다. 그러면 MediaLibraryService가 필요에 따라 포그라운드에서 서비스를 시작할 수 있습니다

MediaLibraryService.updateNotification()를 재정의하면 앱이 Google에서 알림을 게시하고 서비스를 시작/중지할 수 있는 포그라운드로 전환할 수 있습니다

MediaBrowser를 사용하여 클라이언트 코드 이전

AndroidX Media3을 사용하면 MediaBrowser가 MediaController/Player를 구현합니다. 인터페이스로, 미디어를 둘러보는 것 외에 미디어 재생을 제어하는 데 사용할 수 있습니다. 있습니다. MediaBrowserCompat 및 MediaControllerCompat를 실행하는 경우 Media3의 MediaBrowser입니다.

MediaBrowser를 빌드하고 서비스:

scope.launch {
    val sessionToken =
        SessionToken(context, ComponentName(context, MusicService::class.java)
    browser =
        MediaBrowser.Builder(context, sessionToken))
            .setListener(BrowserListener())
            .buildAsync()
            .await()
    // Get the library root to start browsing the library.
    root = browser.getLibraryRoot(/* params= */ null).await();
    // Add a MediaController.Listener to listen to player state events.
    browser.addListener(playerListener)
    playerView.setPlayer(browser)
}

살펴볼 항목 미디어 세션에서 재생 제어 에서 재생을 제어하는 MediaController 방법에 대해 알아보려면 있습니다.

추가 단계 및 정리

불안정한 API 오류

Media3으로 이전한 후 불안정한 API 사용에 관한 린트 오류가 표시될 수 있습니다. 이러한 API는 사용하기 안전하며 린트 오류는 새로운 API 호출의 부산물이며 바이너리 호환성 보장입니다. 엄격한 바이너리가 필요하지 않은 경우 호환성이 있는 경우 @OptIn를 사용하여 이러한 오류를 안전하게 억제할 수 있습니다. 주석을 추가합니다.

배경

ExoPlayer v1과 v2 모두 바이너리 호환성을 엄격하게 보장하지 않았습니다. 라이브러리의 다른 버전 간에 데이터를 가져올 수 있습니다 ExoPlayer API 노출 영역은 앱이 데이터의 거의 모든 측면을 맞춤설정할 수 있도록 하기 위해 있습니다. ExoPlayer의 후속 버전에서 때때로 기호를 도입함 이름 변경 또는 기타 브레이킹 체인지 (예: 인터페이스의 새로운 필수 메서드) 포함 대부분의 경우 새로운 기호를 도입하여 이러한 중단을 완화했습니다. 몇 가지 버전의 이전 기호에 대한 지원을 중단하여 개발자가 사용 방법을 마이그레이션하는 데 많은 시간이 걸렸지만 항상 가능한 것은 아니었습니다.

이 브레이킹 체인지로 인해 ExoPlayer v1 사용자에게 두 가지 문제가 발생했습니다. 및 v2 라이브러리:

  1. ExoPlayer 버전으로 업그레이드하면 코드의 컴파일이 중지될 수 있습니다.
  2. 직접 및 중간 라이브러리를 통해 ExoPlayer에 종속된 앱 두 종속 항목이 동일한 버전인지 확인해야 했습니다. 바이너리 비호환성으로 인해 런타임 비정상 종료가 발생할 수 있습니다.

Media3 개선사항

Media3은 API 노출 영역의 하위 집합에 관한 바이너리 호환성을 보장합니다. 이 바이너리 호환성을 보장하지 않는 부분은 @UnstableApi 이 구분을 명확히 하기 위해 API 기호는 @OptIn로 주석이 지정되지 않는 한 린트 오류를 생성합니다.

ExoPlayer v2에서 Media3으로 이전한 후 불안정한 API가 많이 표시될 수 있습니다. 린트 오류를 반환합니다. 이로 인해 Media3이 '덜 안정적'인 것처럼 보일 수 있습니다. ExoPlayer보다 v2 호출은 건너뛸 수 없습니다. '불안정' Media3 API의 일부는 ExoPlayer v2 API 노출 영역 전체의 안정성 및 안정적인 Media3 API 노출 영역 보장은 ExoPlayer v2 있습니다. 차이점은 간단히 말하자면, 린트 오류가 안정성 수준을 갖출 수 있습니다

불안정한 API 린트 오류 처리

자세한 내용은 린트 오류에 관한 문제 해결 섹션을 참고하세요. 불안정한 API의 Java 및 Kotlin 사용에 @OptIn로 주석을 추가합니다.

지원 중단된 API

Android에서는 지원 중단된 API 호출이 취소선 처리됨을 알 수 있습니다. 있습니다. 이러한 호출은 적절한 대안으로 대체하는 것이 좋습니다. 기호 위로 마우스를 가져가면 대신 사용할 API를 알려주는 JavaDoc가 표시됩니다.

<ph type="x-smartling-placeholder">
</ph> 스크린샷: 지원 중단된 메서드의 대안으로 JavaDoc를 표시하는 방법
그림 3: Android 스튜디오의 JavaDoc 도움말에서 지원 중단된 기호의 대안을 제안함

코드 샘플 및 데모 앱

  • AndroidX Media3 세션 데모 앱 (모바일 및 WearOS) <ph type="x-smartling-placeholder">
      </ph>
    • 맞춤 작업
    • 시스템 UI 알림, MediaButton/BT
    • Google 어시스턴트 재생 컨트롤
  • UAMP: Android 미디어 플레이어 (브랜치 media3) (모바일, AutomotiveOS) <ph type="x-smartling-placeholder">
      </ph>
    • 시스템 UI 알림, MediaButton/BT, 재생 재개
    • Google 어시스턴트/WearOS 재생 컨트롤
    • AutomotiveOS: 커스텀 명령어 및 로그인