시작하기

간단한 사용 사례의 경우 ExoPlayer를 시작하려면 다음 단계를 구현해야 합니다.

  1. 프로젝트에 종속 항목으로 ExoPlayer를 추가합니다.
  2. ExoPlayer 인스턴스를 만듭니다.
  3. 플레이어를 뷰에 연결합니다 (동영상 출력 및 사용자 입력용).
  4. 재생할 MediaItem으로 플레이어를 준비합니다.
  5. 완료되면 플레이어를 해제합니다.

이러한 단계는 아래에서 자세히 설명합니다. 전체 예는 PlayerActivity의 기본 데모 앱을 참고하세요.

종속 항목으로 ExoPlayer 추가

ExoPlayer 모듈 추가

AndroidX Media3를 시작하는 가장 쉬운 방법은 앱 모듈의 build.gradle 파일에서 필요한 라이브러리에 Gradle 종속 항목을 추가하는 것입니다.

예를 들어 DASH 재생 지원 및 UI 구성요소가 있는 ExoPlayer에 종속되려면 다음과 같이 모듈에 종속 항목을 추가하면 됩니다.

Kotlin

implementation("androidx.media3:media3-exoplayer:1.10.0")
implementation("androidx.media3:media3-exoplayer-dash:1.10.0")
implementation("androidx.media3:media3-ui:1.10.0")
implementation("androidx.media3:media3-ui-compose-material3:1.10.0")

Groovy

implementation "androidx.media3:media3-exoplayer:1.10.0"
implementation "androidx.media3:media3-exoplayer-dash:1.10.0"
implementation "androidx.media3:media3-ui:1.10.0"
implementation("androidx.media3:media3-ui-compose-material3:1.10.0")

여기서 1.10.0은 선호하는 버전입니다 (최신 버전은 출시 노트를 참고하여 확인할 수 있음). 모든 모듈은 버전이 동일해야 합니다.

AndroidX Media3에는 추가 기능을 제공하기 위해 외부 라이브러리에 종속되는 라이브러리 모듈이 있습니다. 일부는 Maven 저장소에서 사용할 수 있지만 다른 일부는 수동으로 빌드해야 합니다. 라이브러리 디렉터리를 탐색하고 개별 README에서 세부정보를 확인하세요.

사용 가능한 라이브러리 모듈에 관한 자세한 내용은 Google Maven AndroidX Media 페이지를 참고하세요.

Java 8 지원 사용 설정

아직 사용 설정되지 않은 경우 android 섹션에 다음을 추가하여 ExoPlayer에 종속되는 모든 build.gradle 파일에서 Java 8 지원을 사용 설정해야 합니다.

compileOptions {
  targetCompatibility JavaVersion.VERSION_1_8
}

플레이어 만들기

다양한 맞춤설정 옵션을 제공하는 ExoPlayer.Builder를 사용하여 ExoPlayer 인스턴스를 만들 수 있습니다. 다음 코드는 인스턴스를 만드는 가장 간단한 예입니다.

Kotlin

val player = ExoPlayer.Builder(context).build()
HelloWorld.kt

Java

ExoPlayer player = new ExoPlayer.Builder(context).build();
HelloWorld.java

스레딩 관련 참고사항

ExoPlayer 인스턴스는 단일 애플리케이션 스레드에서 액세스해야 합니다. 대부분의 경우 이는 애플리케이션의 기본 스레드여야 합니다. 애플리케이션의 기본 스레드를 사용하는 것은 ExoPlayer의 UI 구성요소 또는 IMA 확장 프로그램을 사용할 때 필수사항입니다.

ExoPlayer 인스턴스에 액세스해야 하는 스레드는 플레이어를 만들 때 Looper를 전달하여 명시적으로 지정할 수 있습니다. Looper가 지정되지 않은 경우 플레이어가 생성된 스레드의 Looper가 사용됩니다. 또는 해당 스레드에 Looper가 없는 경우 애플리케이션의 기본 스레드의 Looper가 사용됩니다. 모든 경우에 플레이어에 액세스해야 하는 스레드의 Looper는 를 사용하여 쿼리할 수 있습니다. Player.getApplicationLooper

ExoPlayer의 스레딩 모델에 관한 자세한 내용은 ExoPlayer Javadoc의 "스레딩 모델" 섹션을 참고하세요.

플레이어를 뷰에 연결

media3-ui 라이브러리는 미디어 재생을 위한 다양한 사전 빌드된 UI 구성요소를 제공합니다. 여기에는 PlayerControlView, SubtitleView, 동영상이 렌더링되는 Surface를 캡슐화하는 PlayerView가 포함됩니다. PlayerView는 애플리케이션의 레이아웃 XML에 포함될 수 있습니다. 예를 들어 플레이어를 뷰에 바인딩하려면 다음을 실행합니다.

Kotlin

// Bind the player to the view.
playerView.player = player
HelloWorld.kt

Java

// Bind the player to the view.
playerView.setPlayer(player);
HelloWorld.java

Media3의 사전 빌드된 UI 구성요소 사용은 선택사항입니다. 자체 UI를 구현하는 동영상 앱의 경우 대상 SurfaceView, TextureView, SurfaceHolder 또는 Surface는 각각 Player의 setVideoSurfaceView, setVideoTextureView, setVideoSurfaceHolder, setVideoSurface 메서드를 사용하여 설정할 수 있습니다. Listener.onCues 콜백은 재생 중에 렌더링해야 하는 캡션을 수신하는 데 사용할 수 있으며 setImageOutput은 디코딩된 이미지를 수신하는 데 사용할 수 있습니다.

더 편안한 사용자 환경을 위해 keepScreenOn 속성을 추가하는 것이 좋습니다. 백그라운드 작업 페이지에서 기기를 절전 모드로 전환하지 않는 다른 작업을 조사할 수 있습니다. 

android:keepScreenOn="true"

앱에서 UI에 Jetpack Compose를 사용하는 경우 media3-ui-compose-material3 라이브러리의 Player 컴포저블을 사용할 수 있습니다. Player는 동영상을 표시하고 재생 컨트롤 슬롯의 사전 입력된 값을 포함합니다. androidx.media3.common.Player 객체를 androidx.media3.ui.compose.material3.Player 컴포저블에 연결하려면 인수로 전달하면 됩니다.

// Bind the player to the composable.
Player(player = player)
HelloWorld.kt

Media3 UI 구성요소 및 맞춤설정 사용에 관한 자세한 내용은 UI 페이지를 참고하세요.

재생목록 채우기 및 플레이어 준비

ExoPlayer에서 모든 미디어는 MediaItem으로 표시됩니다. 미디어를 재생하려면 해당하는 MediaItem을 빌드하고 플레이어에 추가하고 플레이어를 준비하고 play를 호출하여 재생을 시작해야 합니다.

Kotlin

// Build the media item.
val mediaItem = MediaItem.fromUri(videoUri)
// Set the media item to be played.
player.setMediaItem(mediaItem)
// Prepare the player.
player.prepare()
// Start the playback.
player.play()
HelloWorld.kt

Java

// Build the media item.
MediaItem mediaItem = MediaItem.fromUri(videoUri);
// Set the media item to be played.
player.setMediaItem(mediaItem);
// Prepare the player.
player.prepare();
// Start the playback.
player.play();
HelloWorld.java

ExoPlayer는 재생목록을 직접 지원하므로 여러 미디어 항목으로 플레이어를 준비하여 번갈아 재생할 수 있습니다.

Kotlin

// Build the media items.
val firstItem = MediaItem.fromUri(firstVideoUri)
val secondItem = MediaItem.fromUri(secondVideoUri)
// Add the media items to be played.
player.addMediaItem(firstItem)
player.addMediaItem(secondItem)
// Prepare the player.
player.prepare()
// Start the playback.
player.play()
HelloWorld.kt

Java

// Build the media items.
MediaItem firstItem = MediaItem.fromUri(firstVideoUri);
MediaItem secondItem = MediaItem.fromUri(secondVideoUri);
// Add the media items to be played.
player.addMediaItem(firstItem);
player.addMediaItem(secondItem);
// Prepare the player.
player.prepare();
// Start the playback.
player.play();
HelloWorld.java

재생 중에 플레이어를 다시 준비하지 않고 재생목록을 업데이트할 수 있습니다. 재생목록 채우기 및 조작에 관한 자세한 내용은 재생목록 페이지를 참고하세요. 미디어 항목 페이지에서 클리핑 및 자막 파일 연결과 같이 미디어 항목을 빌드할 때 사용할 수 있는 다양한 옵션에 관해 자세히 알아보세요.

플레이어 제어

플레이어가 준비되면 플레이어에서 메서드를 호출하여 재생을 제어할 수 있습니다. 가장 흔히 사용되는 몇 가지 메서드를 소개합니다.

  • play 및 pause는 재생을 시작하고 일시중지합니다.
  • seekTo를 사용하면 미디어 내에서 탐색할 수 있습니다.
  • hasPrevious, hasNext, previous, next를 사용하면 재생목록을 탐색할 수 있습니다.
  • setRepeatMode는 미디어가 반복되는지 여부와 방법을 제어합니다.
  • setShuffleModeEnabled는 재생목록 셔플링을 제어합니다.
  • setPlaybackParameters는 재생 속도와 오디오 피치를 조정합니다.

플레이어가 PlayerView 또는 PlayerControlView에 바인딩되면 이러한 구성요소와의 사용자 상호작용으로 인해 플레이어에서 해당하는 메서드가 호출됩니다.

플레이어 해제

더 이상 필요하지 않은 경우 플레이어를 해제하여 다른 애플리케이션에서 사용할 수 있도록 동영상 디코더와 같은 제한된 리소스를 확보하는 것이 중요합니다. 이는 ExoPlayer.release를 호출하여 실행할 수 있습니다.