AndroidX Media3 이전 가이드

현재 독립형 com.google.android.exoplayer2 라이브러리 및 androidx.media를 사용하는 앱은 androidx.media3으로 이전해야 합니다. 이전 스크립트를 사용하여 ExoPlayer 2.19.1에서 AndroidX Media3 1.1.1으로 Gradle 빌드 파일, 자바 및 Kotlin 소스 파일, XML 레이아웃 파일을 이전합니다.

개요

이전하기 전에 다음 섹션을 검토하여 새 API의 혜택, 이전할 API, 앱 프로젝트가 충족해야 하는 기본 요건을 자세히 알아보세요.

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

com.google.android.exoplayer2가 지원 중단된 반면 ExoPlayer의 새로운 홈입니다.
MediaBrowser/MediaController를 사용하여 구성요소/프로세스 전반에서 Player API에 액세스 합니다.
및 MediaSession API의 확장된 기능 MediaController 을 사용합니다.
세분화된 액세스 제어 로 재생 기능을 알립니다.
MediaSessionConnector 및 PlayerNotificationManager를 삭제하여 앱을 간소화 합니다.
미디어 호환 클라이언트 API(MediaBrowserCompat/MediaControllerCompat/MediaMetadataCompat)와 이전 버전과 호환 됩니다.

AndroidX Media3으로 이전할 미디어 API

ExoPlayer 및 확장 프로그램
지원 중단된 mediasession 모듈을 제외한 기존 ExoPlayer 프로젝트의 모든 모듈이 포함됩니다. com.google.android.exoplayer2의 패키지에 종속된 앱 또는 모듈은 이전 스크립트를 사용하여 이전할 수 있습니다.
MediaSessionConnector (androidx.media.* 패키지에 종속됨)
MediaSessionConnector를 삭제하고 androidx.media3.session.MediaSession를 대신 사용합니다.androidx.media:media:1.4.3+
MediaBrowserServiceCompat (androidx.media.* 패키지에 종속됨)
androidx.media.MediaBrowserServiceCompat의 하위 클래스를 androidx.media3.session.MediaLibraryService로 이전하고 MediaBrowserCompat.MediaItem을 사용하는 코드를 androidx.media3.common.MediaItem로 이전합니다.androidx.media:media:1.4.3+
MediaBrowserCompat (androidx.media:media:1.4.3+의 android.support.v4.media.* 패키지에 종속됨)
MediaBrowserCompat 또는 MediaControllerCompat를 사용하는 클라이언트 코드를 이전하여 androidx.media3.common.MediaItem과 함께 androidx.media3.session.MediaBrowser를 사용합니다.

기본 요건

프로젝트가 소스 관리하에 있는지 확인

스크립트된 이전 도구에서 적용한 변경사항을 쉽게 되돌릴 수 있는지 확인합니다. 아직 프로젝트가 소스 관리하에 있지 않다면 지금 시작하는 것이 좋습니다. 어떤 이유로든 그렇게 하고 싶지 않다면 이전을 시작하기 전에 프로젝트의 백업 사본을 만드세요.
앱 업데이트
- 프로젝트를 업데이트하여 최신 버전의 ExoPlayer 라이브러리를 사용하고 지원 중단된 메서드 호출을 삭제하는 것이 좋습니다. 이전에 스크립트를 사용하려는 경우 업데이트하는 버전이 스크립트에서 처리하는 버전과 일치해야 합니다.
- 앱의 compileSdkVersion을 32 이상으로 늘립니다.
- Gradle 및 Android 스튜디오 Gradle 플러그인을 위의 업데이트된 종속 항목과 호환되는 최신 버전으로 업그레이드 합니다. 예를 들면 다음과 같습니다.
  - Android Gradle 플러그인 버전: 7.1.0
  - Gradle 버전: 7.4
- 별표(*)를 사용하는 모든 와일드카드 가져오기 문을 바꾸고 정규화된 가져오기 문을 사용합니다. 와일드카드 가져오기 문을 삭제하고 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으로 쉽게 이동할 수 있습니다. 스크립트는 프로젝트에 일부 유효성 검사 체크를 적용하고 유효성 검사가 실패하면 경고를 출력합니다. 그렇지 않으면 자바 또는 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

이전 스크립트 사용

앱을 업데이트한 버전에 해당하는 GitHub의 ExoPlayer 프로젝트 태그에서 이전 스크립트를 다운로드합니다.
```
curl -o media3-migration.sh \
  "https://raw.githubusercontent.com/google/ExoPlayer/r2.19.1/media3-migration.sh"
```
스크립트를 실행 가능하게 만듭니다.
```
chmod 744 media3-migration.sh
```
--help로 스크립트를 실행하여 옵션을 알아봅니다.
-l로 스크립트를 실행하여 이전을 위해 선택된 파일 집합을 나열합니다 (-f를 사용하여 경고 없이 목록을 강제 적용).
```
./media3-migration.sh -l -f /path/to/gradle/project/root
```
-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 옵션으로 스크립트를 실행한 후 다음 수동 단계를 완료합니다.

스크립트에서 코드를 변경한 방식 확인: diff 도구를 사용하고 잠재적 문제를 해결합니다 (버그를 신고하는 것이 좋습니다. 스크립트에 일반적인 문제가 있다고 생각되면 -f 옵션을 전달하지 않고 도입되었습니다).
프로젝트 빌드: ./gradlew clean build를 사용하거나 Android 스튜디오에서 File > Sync Project with Gradle Files를 선택한 다음 Build > Clean project, Build > Rebuild project를 선택합니다 (Android 스튜디오의 'Build - Build Output' 탭에서 빌드를 모니터링).

권장되는 후속 단계:

**불안정한 API 사용에 관한 오류를 선택** 합니다.
지원 중단된 API 호출 바꾸기: 제안된 대체 API를 사용합니다. Android 스튜디오에서 경고 위에 포인터를 가져가고 지원 중단된 기호의 JavaDoc을 참조하여 지정된 호출 대신 사용할 항목을 알아봅니다.
가져오기 문 정렬: Android 스튜디오에서 프로젝트를 연 다음 프로젝트 뷰어에서 패키지 폴더 노드를 마우스 오른쪽 버튼으로 클릭하고 변경된 소스 파일이 포함된 패키지에서 Optimize imports를 선택합니다.

`MediaSessionConnector`를 `androidx.media3.session.MediaSession`으로 바꾸기

기존 MediaSessionCompat 세계에서 MediaSessionConnector는 플레이어의 상태를 세션의 상태와 동기화하고 적절한 플레이어 메서드에 위임해야 하는 컨트롤러로부터 명령어를 수신하는 역할을 했습니다. AndroidX Media3에서는 커넥터가 필요 없이 MediaSession에서 직접 이 작업을 실행합니다.

MediaSessionConnector의 모든 참조 및 사용 삭제: 자동 스크립트를 사용하여 ExoPlayer 클래스 및 패키지를 이전한 경우 스크립트로 인해 해결할 수 없는 MediaSessionConnector에 관한 코드가 컴파일 불가능한 상태로 남아 있을 수 있습니다. 앱을 빌드하거나 시작하려고 하면 Android 스튜디오에 손상된 코드가 표시됩니다.
종속 항목을 유지관리하는 build.gradle 파일에서 AndroidX Media3 세션 모듈에 구현 종속 항목을 추가 하고 기존 종속 항목을 삭제합니다.
```
implementation "androidx.media3:media3-session:1.10.0"
```
MediaSessionCompat를 androidx.media3.session.MediaSession 으로 바꿉니다.
기존 MediaSessionCompat를 만든 코드 사이트에서 androidx.media3.session.MediaSession.Builder를 사용하여 빌드합니다 MediaSession. 플레이어를 전달 하여 세션 빌더를 구성합니다.

참고: 앱에서 ExoPlayer가 아닌 다른 플레이어를 사용하는 경우 플레이어를 래핑하는 MediaSession에 전달할 수 있는 커스텀 Player 구현이 필요합니다. 미디어 세션 구현과 함께 작동하는 최소 Player 구현에 관한 추가 안내를 제공할 예정입니다.
Kotlin
val player = ExoPlayer.Builder(context).build() mediaSession = MediaSession.Builder(context, player).setCallback(MySessionCallback()).build()
MigrationGuide.kt
자바
ExoPlayer player = new ExoPlayer.Builder(context).build(); mediaSession = new MediaSession.Builder(context, player).setCallback(new MySessionCallback()).build();
MigrationGuide.java
참고: Player를 ForwardingSimpleBasePlayer(player)로 래핑하여 모든 재생 작업을 가로챌 수 있습니다. 자세한 내용은 여기를 참고하세요.
ForwardingSimpleBasePlayer
앱에 필요한 대로 MySessionCallback을 구현합니다. 이는 선택사항입니다. 컨트롤러가 플레이어에 미디어 항목을 추가하도록 허용하려면 MediaSession.Callback.onAddMediaItems()를 구현합니다. 이 메서드는 이전 버전과 호환되는 방식으로 재생을 위해 플레이어에 미디어 항목을 추가하는 다양한 현재 및 기존 API 메서드를 제공합니다. 여기에는 Media3 컨트롤러의 MediaController.set/addMediaItems() 메서드와 기존 API의 TransportControls.prepareFrom*/playFrom* 메서드가 포함됩니다. onAddMediaItems의 샘플 구현은 세션 데모 앱의 PlaybackService에서 확인할 수 있습니다.
이전 전에 세션을 삭제한 코드 사이트에서 미디어 세션을 해제합니다.
Kotlin
mediaSession?.run { player.release() release() mediaSession = null }
MigrationGuide.kt
자바
if (mediaSession != null) { mediaSession.getPlayer().release(); mediaSession.release(); mediaSession = null; }
MigrationGuide.java
참고: 동일한 ID로 새 미디어 세션을 만들기 전에 미디어 세션을 해제하는 것이 중요합니다. 앱에서 세션 인스턴스를 누수하는 경우 Media3에서 예외가 발생합니다.

Media3의 `MediaSessionConnector` 기능

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

MediaSessionConnector	AndroidX Media3
`CustomActionProvider`	`MediaSession.Callback.onCustomCommand()/ MediaSession.setMediaButtonPreferences()`
`PlaybackPreparer`	`MediaSession.Callback.onAddMediaItems()` (`prepare()`는 내부적으로 호출됨)
`QueueNavigator`	`ForwardingSimpleBasePlayer`
`QueueEditor`	`MediaSession.Callback.onAddMediaItems()`
`RatingCallback`	`MediaSession.Callback.onSetRating()`
`PlayerNotificationManager`	`DefaultMediaNotificationProvider/ MediaNotification.Provider`

`MediaBrowserService`를 `MediaLibraryService`로 이전

AndroidX Media3에는 MediaBrowserServiceCompat를 대체하는 MediaLibraryService가 도입되었습니다. MediaLibraryService 및 슈퍼클래스 MediaSessionService의 JavaDoc은 API 및 서비스의 비동기 프로그래밍 모델에 관한 좋은 소개를 제공합니다.

MediaLibraryService는 MediaBrowserService와 이전 버전과 호환됩니다. MediaBrowserCompat 또는 MediaControllerCompat를 사용하는 클라이언트 앱은 MediaLibraryService에 연결할 때 코드 변경 없이 계속 작동합니다. 클라이언트의 경우 앱에서 MediaLibraryService 또는 기존 MediaBrowserServiceCompat를 사용하는지 여부가 투명합니다.

서비스, 활동, 외부 앱이 있는 앱 구성요소 다이어그램 — **그림 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>

종속 항목을 유지관리하는 build.gradle 파일에서 AndroidX Media3 세션 모듈에 구현 종속 항목을 추가하고 기존 종속 항목을 삭제합니다.
```
implementation "androidx.media3:media3-session:1.10.0"
```
MediaLibraryService 대신 MediaBrowserService 에서 상속하도록 서비스를 변경합니다. 앞서 말했듯이 MediaLibraryService는 기존 MediaBrowserService와 호환됩니다. 따라서 서비스가 클라이언트에 제공하는 더 광범위한 API는 여전히 동일합니다. 따라서 앱은 MediaBrowserService를 구현하는 데 필요한 대부분의 로직을 유지하고 새 MediaLibraryService에 맞게 조정할 수 있습니다.

기존 MediaBrowserServiceCompat와 비교했을 때 주요 차이점은 다음과 같습니다.
- 서비스 수명 주기 메서드 구현: 서비스 자체에서 재정의해야 하는 메서드는 앱이 라이브러리 세션, 플레이어, 기타 리소스를 할당/해제하는 onCreate/onDestroy입니다. 표준 서비스 수명 주기 메서드 외에도 앱은 onCreate에서 빌드된 MediaLibrarySession을 반환하도록 onGetSession(MediaSession.ControllerInfo)을 재정의해야 합니다.
- MediaLibraryService.MediaLibrarySessionCallback 구현: 세션을 빌드하려면 실제 도메인 API 메서드를 구현하는 MediaLibraryService.MediaLibrarySessionCallback이 필요합니다. 따라서 기존 서비스의 API 메서드를 재정의하는 대신 MediaLibrarySession.Callback의 메서드를 재정의합니다.
  
  그러면 콜백이 MediaLibrarySession을 빌드하는 데 사용됩니다.
  Kotlin
  
  mediaLibrarySession = MediaLibrarySession.Builder(context, player, MySessionCallback()).build()
  MigrationGuide.kt
  자바
  
  mediaLibrarySession = new MediaLibrarySession.Builder(context, player, new MySessionCallback()).build();
  MigrationGuide.java
  API 문서에서 MediaLibrarySessionCallback의 전체 API를 확인하세요.
- MediaSession.Callback.onAddMediaItems() 구현: 콜백 onAddMediaItems(MediaSession, ControllerInfo, List<MediaItem>)은 이전 버전과 호환되는 방식으로 재생을 위해 플레이어에 미디어 항목을 추가하는 다양한 현재 및 기존 API 메서드를 제공합니다. 여기에는 Media3 컨트롤러의 MediaController.set/addMediaItems() 메서드와 기존 API의 TransportControls.prepareFrom*/playFrom* 메서드가 포함됩니다. 콜백의 샘플 구현은 세션 데모 앱의 PlaybackService에서 확인할 수 있습니다.
- AndroidX Media3은 androidx.media3.common.MediaItem 대신 MediaBrowserCompat.MediaItem 및 MediaMetadataCompat을 사용합니다. 기존 클래스와 연결된 코드의 일부는 그에 따라 변경하거나 Media3 MediaItem에 매핑해야 합니다.
- 일반적인 비동기 프로그래밍 모델이 Futures로 변경되었습니다. 이는 분리 가능한 Result 접근 방식과 대조됩니다. MediaBrowserServiceCompat. 서비스 구현은 결과를 분리하거나 즉시 Future를 반환하여 값을 직접 반환하는 대신 비동기 ListenableFuture를 반환할 수 있습니다.

PlayerNotificationManager 삭제

MediaLibraryService는 미디어 알림을 자동으로 지원 하며 MediaLibraryService 또는 MediaSessionService를 사용할 때 PlayerNotificationManager를 삭제할 수 있습니다.

앱은 DefaultMediaNotificationProvider를 대체하는 커스텀 MediaNotification.Provider를 onCreate()에 설정하여 알림을 맞춤설정 할 수 있습니다. 그러면 MediaLibraryService가 필요한 대로 포그라운드에서 서비스를 시작합니다.

앱은 MediaLibraryService.updateNotification()을 재정의하여 알림 게시 및 필요한 대로 포그라운드에서 서비스 시작/중지를 완전히 소유할 수 있습니다.

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

AndroidX Media3에서 MediaBrowser는 MediaController/Player 인터페이스를 구현하며 미디어 라이브러리 탐색 외에 미디어 재생을 제어하는 데 사용할 수 있습니다. 기존 세계에서 MediaBrowserCompat 및 MediaControllerCompat를 만들어야 했다면 Media3에서 MediaBrowser만 사용하여 동일한 작업을 실행할 수 있습니다.

MediaBrowser를 빌드하고 서비스 연결이 설정될 때까지 기다릴 수 있습니다.

Kotlin

scope.launch {
  val sessionToken = SessionToken(context, ComponentName(context, "MusicService"))
  browser =
    MediaBrowser.Builder(context, sessionToken)
      .setListener(BrowserListener())
      .buildAsync()
      .await()
}MigrationGuide.kt

자바

SessionToken sessionToken =
    new SessionToken(context, new ComponentName(context, "MusicService"));
ListenableFuture<MediaBrowser> browserFuture =
    new MediaBrowser.Builder(context, sessionToken)
        .setListener(new BrowserListener())
        .buildAsync();MigrationGuide.java

백그라운드에서 재생을 제어하기 위한 MediaController를 만드는 방법을 알아보려면 미디어 세션에서 재생 제어 를 살펴보세요.

추가 단계 및 정리

불안정한 API 오류

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

배경

ExoPlayer v1 또는 v2는 후속 버전 간의 라이브러리 바이너리 호환성에 관한 엄격한 보장을 제공하지 않았습니다. ExoPlayer API 표시 경로는 앱에서 재생의 거의 모든 측면을 맞춤설정할 수 있도록 설계상 매우 큽니다. ExoPlayer의 후속 버전에서는 기호 이름 바꾸기 또는 기타 브레이킹 체인지 (예: 인터페이스의 새로운 필수 메서드)가 가끔 도입됩니다. 대부분의 경우 이러한 손상은 개발자가 사용을 이전할 시간을 허용하기 위해 몇 가지 버전의 기존 기호를 지원 중단하는 동시에 새 기호를 도입하여 완화되었지만 항상 가능한 것은 아니었습니다.

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

에서 ExoPlayer 버전으로 업그레이드하면 코드 컴파일이 중지될 수 있습니다.
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의 자바 및 Kotlin 사용에 @OptIn으로 주석을 추가하는 방법에 관한 자세한 내용은 이러한 린트 오류에 관한 문제 해결 섹션을 참고하세요.

지원 중단된 API

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

스크린샷: 지원 중단된 메서드의 대안으로 JavaDoc을 표시하는 방법 — **그림 3**: Android 스튜디오의 JavaDoc 툴팁은 지원 중단된 기호의 대안을 제안합니다.

코드 샘플 및 데모 앱

AndroidX Media3 세션 데모 앱 (모바일 및 WearOS)
- 맞춤 작업
- 시스템 UI 알림, MediaButton/BT
- Google 어시스턴트 재생 제어
UAMP: Android 미디어 플레이어 (브랜치 media3) (모바일, AutomotiveOS)
- 시스템 UI 알림, MediaButton/BT, 재생 재개
- Google 어시스턴트/WearOS 재생 제어
- AutomotiveOS: 맞춤 명령어 및 로그인

AndroidX Media3 이전 가이드 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

개요

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

AndroidX Media3으로 이전할 미디어 API

기본 요건

스크립트 지원으로 ExoPlayer 이전

이전 스크립트 사용

MediaSessionConnector를 androidx.media3.session.MediaSession으로 바꾸기

Kotlin

자바

Kotlin

자바

Media3의 MediaSessionConnector 기능

MediaBrowserService를 MediaLibraryService로 이전

Kotlin

자바

PlayerNotificationManager 삭제

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

Kotlin

자바

추가 단계 및 정리

불안정한 API 오류

배경

Media3의 개선사항

불안정한 API 린트 오류 처리

지원 중단된 API

코드 샘플 및 데모 앱

AndroidX Media3 이전 가이드

`MediaSessionConnector`를 `androidx.media3.session.MediaSession`으로 바꾸기

Media3의 `MediaSessionConnector` 기능

`MediaBrowserService`를 `MediaLibraryService`로 이전