현재 독립형 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
와(과) 비교해 보세요.
기본 요건
프로젝트가 소스 제어를 받고 있는지 확인
스크립트 이전 도구로 적용한 변경사항을 쉽게 되돌릴 수 있어야 합니다. 아직 프로젝트를 소스 제어 대상이 아니라면 지금이 좋습니다. 살펴보겠습니다 어떤 이유로든 그렇게 하고 싶지 않다면 이전을 시작하기 전에 프로젝트의 백업 사본을 만들어야 합니다.
앱 업데이트
프로젝트를 업데이트하여 최신 버전의 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
마이그레이션 스크립트 사용
ExoPlayer 프로젝트의 태그에서 이전 스크립트를 다운로드합니다. 앱을 업데이트한 버전에 해당하는 GitHub입니다.
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를 사용합니다. 스튜디오에서 파일 > Sync Project with Gradle Files로 이동한 후 Build > 프로젝트를 정리한 다음 Build >를 선택합니다. 프로젝트 다시 빌드 (다음 위치에서 빌드 모니터링 '빌드 - 빌드 출력' 탭으로 이동합니다.
권장되는 후속 단계:
- 불안정한 API 사용 관련 오류 수신 동의 문제를 해결합니다.
- 지원 중단된 API 호출 대체: 제안된 대체 API를 사용합니다. Android 스튜디오에서 경고 위로 포인터를 가져가고 JavaDoc를 참조합니다. 특정 호출 대신 무엇을 사용해야 할지 알아봅니다.
- import 문 정렬: Android 스튜디오에서 프로젝트를 열고 프로젝트 뷰어에서 패키지 폴더 노드를 마우스 오른쪽 버튼으로 클릭하고 변경된 소스 파일이 포함된 패키지의 가져오기를 최적화합니다.
MediaSessionConnector
를 androidx.media3.session.MediaSession
로 바꿉니다.
기존 MediaSessionCompat
환경에서 MediaSessionConnector
는
플레이어의 상태와 세션의 상태를 동기화합니다.
컨트롤러로부터 적절한 권한을 위임받아야 하는
사용할 수 있습니다. AndroidX Media3을 사용하면 MediaSession
에서 직접 이 작업을 실행합니다.
Google Cloud 서비스를
제공할 수 있습니다
MediaSessionConnector의 모든 참조 및 사용 삭제: ExoPlayer 클래스 및 패키지를 마이그레이션하기 위해 자동화된 스크립트를 실행한 다음 스크립트가 컴파일할 수 없는 상태로 코드를 남겨두었을 가능성이 있으며 해결할 수 없는
MediaSessionConnector
입니다. Android 스튜디오는 앱을 빌드하거나 시작하려고 할 때 손상된 코드가 표시됩니다.종속 항목을 유지관리하는
build.gradle
파일에서 AndroidX Media3 세션 모듈에 대한 구현 종속 항목을 적용하고 기존 종속 항목은 다음과 같습니다.implementation "androidx.media3:media3-session:1.4.0"
MediaSessionCompat
를 다음으로 바꿉니다.androidx.media3.session.MediaSession
기존
MediaSessionCompat
를 만든 코드 사이트에서 다음을 사용합니다.androidx.media3.session.MediaSession.Builder
를 사용하여MediaSession
). 플레이어를 전달하여 세션 빌더를 구성합니다.val player = ExoPlayer.Builder(context).build() mediaSession = MediaSession.Builder(context, player) .setSessionCallback(MySessionCallback()) .build()
앱의 필요에 따라
MySessionCallback
를 구현합니다. 이는 선택사항입니다. 만약 컨트롤러가 플레이어에 미디어 항목을 추가하고MediaSession.Callback.onAddMediaItems()
그것은 다양한 현재 및 다양한 기존 API 메서드는 미디어 항목을 플레이어에 추가하여 이전 버전과 호환되는 방식으로 작동합니다 여기에는 Media3 컨트롤러의MediaController.set/addMediaItems()
메서드 및TransportControls.prepareFrom*/playFrom*
기존 API의 메서드와 비교됩니다.onAddMediaItems
의 샘플 구현은 다음을 수행할 수 있습니다. 세션 데모 앱의PlaybackService
에서 확인할 수 있습니다.세션을 폐기한 코드 사이트에서 미디어 세션 해제 해야 합니다.
mediaSession?.run { player.release() release() mediaSession = null }
Media3의 MediaSessionConnector
기능
다음 표는 기능을 처리하는 Media3 API를 보여줍니다.
이전에 MediaSessionConnector
에 구현되어 있습니다.
MediaSessionConnector | AndroidX 미디어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
사용
![서비스, 활동, 외부 앱이 표시된 앱 구성요소 다이어그램](https://developer.android.com/static/media/images/overview.png?authuser=0000&hl=ko)
이전 버전과의 호환성이 작동하려면 두 서비스를 모두 등록해야 함 인터페이스를
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.4.0"
서비스가
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입니다. 부품 이에 따라 기존 클래스에 연결된 코드의 일부를 변경해야 함 또는 Media3MediaItem
에 매핑합니다.일반 비동기 프로그래밍 모델이
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 라이브러리:
- 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의 Java 및 Kotlin 사용에 @OptIn
로 주석을 추가합니다.
지원 중단된 API
Android에서는 지원 중단된 API 호출이 취소선 처리됨을 알 수 있습니다. 있습니다. 이러한 호출은 적절한 대안으로 대체하는 것이 좋습니다. 기호 위로 마우스를 가져가면 대신 사용할 API를 알려주는 JavaDoc가 표시됩니다.
<ph type="x-smartling-placeholder">![스크린샷: 지원 중단된 메서드의 대안으로 JavaDoc를 표시하는 방법](https://developer.android.com/static/media/media3/exoplayer/images/deprecation.png?authuser=0000&hl=ko)
코드 샘플 및 데모 앱
- 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: 커스텀 명령어 및 로그인