Şu anda bağımsız com.google.android.exoplayer2
kitaplığını ve androidx.media
kitaplığını kullanan uygulamalar androidx.media3
hedefine taşınmalıdır. Gradle derleme dosyalarını, Java ve Kotlin kaynak dosyalarını ve XML düzen dosyalarını ExoPlayer 2.19.1
'den AndroidX Media3 1.1.1
'e taşımak için taşıma komut dosyasını kullanın.
Genel bakış
Taşıma işleminden önce yeni API'lerin avantajları, taşınacak API'ler ve uygulama projenizin karşılaması gereken ön koşullar hakkında daha fazla bilgi edinmek için aşağıdaki bölümleri inceleyin.
Neden Jetpack Media3'e geçiş yapmalısınız?
- ExoPlayer'ın yeni adresidir.
com.google.android.exoplayer2
kullanımdan kaldırılmıştır. MediaBrowser
/MediaController
ile bileşenler/işlemler genelinde Player API'ye erişin.MediaSession
veMediaController
API'nin gelişmiş özelliklerini kullanın.- Ayrıntılı erişim denetimi ile oynatma özelliklerinin reklamını yapın.
MediaSessionConnector
vePlayerNotificationManager
öğelerini kaldırarak uygulamanızı basitleştirin.- Medya uyumlu istemci API'leriyle geriye dönük uyumlu
(
MediaBrowserCompat
/MediaControllerCompat
/MediaMetadataCompat
)
AndroidX Media3'e taşınacak medya API'leri
- ExoPlayer ve uzantıları
Buna, kullanımdan kaldırılan mediasession modülü hariç eski ExoPlayer projesinin tüm modülleri dahildir.com.google.android.exoplayer2
hizmetindeki paketlere bağlı olarak uygulamalar veya modüller, taşıma komut dosyasıyla taşınabilir. - MediaSessionConnector (
androidx.media:media:1.4.3+
paketininandroidx.media.*
paketine bağlı olarak)
MediaSessionConnector
öğesini kaldırın ve onun yerineandroidx.media3.session.MediaSession
kullanın. - MediaTarayıcıServiceCompat (
androidx.media:media:1.4.3+
paketininandroidx.media.*
paketine bağlı olarak)
androidx.media.MediaBrowserServiceCompat
alt sınıflarınıandroidx.media3.session.MediaLibraryService
öğesine ve kodlarıMediaBrowserCompat.MediaItem
kullanarakandroidx.media3.common.MediaItem
öğesine taşıyın. - MediaTarayıcıCompat (
androidx.media:media:1.4.3+
paketininandroid.support.v4.media.*
paketine bağlı olarak)
androidx.media3.session.MediaBrowser
öğesiniandroidx.media3.common.MediaItem
ile kullanmak içinMediaBrowserCompat
veyaMediaControllerCompat
kullanarak istemci kodunu taşıyın.
Ön koşullar
Projenizin kaynak kontrolü altında olduğundan emin olma
Komut dosyası tabanlı taşıma araçları tarafından uygulanan değişiklikleri kolayca geri döndürebileceğinizden emin olun. Projeniz henüz kaynak denetimi altında değilse projeye başlamanın tam zamanı. Herhangi bir nedenle bunu yapmak istemezseniz taşıma işlemine başlamadan önce projenizin yedek kopyasını oluşturun.
Uygulamanızı güncelleme
Projenizi ExoPlayer kitaplığının en son sürümünü kullanacak şekilde güncellemenizi ve kullanımdan kaldırılan yöntemlere yapılan tüm çağrıları kaldırmanızı öneririz. Taşıma işleminde komut dosyasını kullanmayı planlıyorsanız güncelleme yaptığınız sürümü, komut dosyası tarafından işlenen sürümle eşleştirmeniz gerekir.
Uygulamanızın derlemeSdkVersion değerini en az 32'ye yükseltin.
Gradle ve Android Studio Gradle eklentisini yukarıdaki güncellenmiş bağımlılıklarla çalışan yeni bir sürüme yükseltin. Örneğin:
- Android Gradle Eklentisi sürümü: 7.1.0
- Gradle sürümü: 7.4
Yıldız işareti (*) kullanan ve tam nitelikli içe aktarma ifadeleri kullanan tüm joker karakter içe aktarma ifadelerini değiştirin: Joker karakter içe aktarma ifadelerini silin ve tam nitelikli ifadeleri (F2 - Alt/Enter, F2 - Alt/Enter, ...) içe aktarmak için Android Studio'yu kullanın.
com.google.android.exoplayer2.PlayerView
-com.google.android.exoplayer2.StyledPlayerView
arasında geçiş yapın. AndroidX Media3'tecom.google.android.exoplayer2.PlayerView
öğesinin eşdeğeri olmadığından bu gereklidir.
Komut dosyası desteğiyle ExoPlayer'ı taşıyın
Komut dosyası, com.google.android.exoplayer2
ürününden androidx.media3
altındaki yeni paket ve modül yapısına geçişi kolaylaştırır. Komut dosyası, projenizde bazı doğrulama kontrolleri uygular ve doğrulama başarısız olursa uyarıları yazdırır.
Aksi takdirde, Java veya Kotlin'de yazılmış bir Android gradle projesinin kaynaklarına yeniden adlandırılan sınıfların ve paketlerin eşlemelerini uygular.
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
Taşıma komut dosyasını kullanma
GitHub'da, uygulamanızı güncellediğiniz sürüme karşılık gelen ExoPlayer projesinin etiketinden taşıma komut dosyasını indirin:
curl -o media3-migration.sh \ "https://raw.githubusercontent.com/google/ExoPlayer/r2.19.1/media3-migration.sh"
Komut dosyasını yürütülebilir hale getirin:
chmod 744 media3-migration.sh
Seçenekler hakkında bilgi edinmek için komut dosyasını
--help
ile çalıştırın.Taşıma için seçilen dosya grubunu listelemek amacıyla komut dosyasını
-l
ile çalıştırın (girişi uyarı olmadan zorunlu kılmak için-f
kullanın):./media3-migration.sh -l -f /path/to/gradle/project/root
Paketleri, sınıfları ve modülleri Media3 ile eşlemek için komut dosyasını
-m
ile çalıştırın. Komut dosyası-m
seçeneğiyle çalıştırıldığında değişiklikler seçilen dosyalara uygulanır.- Değişiklik yapmadan doğrulama hatasında durdurun
./media3-migration.sh -m /path/to/gradle/project/root
- Zorunlu yürütme
Komut dosyası ön koşulların ihlal edildiğini tespit ederse taşıma işlemi
-f
işaretiyle zorlanabilir:./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
Komut dosyasını -m
seçeneğiyle çalıştırdıktan sonra bu manuel adımları tamamlayın:
- Komut dosyasının kodunuzu nasıl değiştirdiğini kontrol edin: Bir fark aracı kullanın ve olası sorunları düzeltin (komut dosyasında
-f
seçeneği iletilmeden ortaya çıkan genel bir sorun olduğunu düşünüyorsanız hata bildiriminde bulunun). - Projeyi derleme:
./gradlew clean build
komutunu kullanın veya Android Studio'da Dosya > Projeyi Gradle Dosyalarıyla Senkronize Et'i, Derle > Projeyi temizle'yi ve ardından Derle > Projeyi yeniden oluştur'u seçin (derlemenizi Android Studio'nun "Derleme - Derleme Çıkışı" sekmesinde izleyin).
Önerilen takip adımları:
- Kararsız API'lerin kullanımıyla ilgili hatalar için kaydolma sorununu çözün.
- Desteği sonlandırılan API çağrılarını değiştirin: Önerilen yedek API'yi kullanın. İşaretçiyi Android Studio'da uyarının üzerinde tutun ve belirli bir çağrı yerine ne kullanılacağını öğrenmek için desteği sonlandırılan simgenin JavaDoc'una bakın.
- İçe aktarma ifadelerini sıralama: Projeyi Android Studio'da açın, ardından proje görüntüleyicide bir paket klasörü düğümünü sağ tıklayın ve değiştirilen kaynak dosyaları içeren paketlerde İçe aktarma işlemlerini optimize et'i seçin.
MediaSessionConnector
yerine androidx.media3.session.MediaSession
yazın
Eski MediaSessionCompat
dünyasında MediaSessionConnector
, oynatıcının durumunu oturumun durumuyla senkronize etmekten ve denetleyicilerden, uygun oynatıcı yöntemleri için yetki verilmesi gereken komutları almaktan sorumluydu. AndroidX Media3'te bu işlem, bağlayıcı gerekmeden doğrudan MediaSession
tarafından yapılır.
MediaSessionConnector'ın tüm referanslarını ve kullanımını kaldırın: ExoPlayer sınıflarını ve paketlerini taşımak için otomatik komut dosyası kullandıysanız komut dosyası, muhtemelen kodunuzu çözümlenemeyen
MediaSessionConnector
ile ilgili olarak derlenemez durumda bırakmıştır. Android Studio, uygulamayı derlemeye veya başlatmaya çalıştığınızda bozuk kodu gösterir.Bağımlılıklarınızı yönettiğiniz
build.gradle
dosyasına AndroidX Media3 oturum modülüne bir uygulama bağımlılığı ekleyin ve eski bağımlılığı kaldırın:implementation "androidx.media3:media3-session:1.3.1"
MediaSessionCompat
değeriniandroidx.media3.session.MediaSession
ile değiştirin.Eski
MediaSessionCompat
kodunu oluşturduğunuz kod sitesinde, birMediaSession
oluşturmak içinandroidx.media3.session.MediaSession.Builder
komutunu kullanın. Oturum oluşturucuyu oluşturmak için oynatıcıyı iletin.val player = ExoPlayer.Builder(context).build() mediaSession = MediaSession.Builder(context, player) .setSessionCallback(MySessionCallback()) .build()
MySessionCallback
özelliğini uygulamanızın gerektirdiği şekilde uygulayın. Bu, isteğe bağlıdır. Denetleyicilerin oynatıcıya medya öğeleri eklemesine izin vermek istiyorsanızMediaSession.Callback.onAddMediaItems()
kodunu uygulayın. Geriye dönük uyumlu bir şekilde oynatma için oynatıcıya medya öğeleri ekleyen çeşitli mevcut ve eski API yöntemlerini sunar. Buna Media3 denetleyicisininMediaController.set/addMediaItems()
yöntemlerinin yanı sıra eski API'ninTransportControls.prepareFrom*/playFrom*
yöntemleri de dahildir.onAddMediaItems
örneğinin bir kullanımını oturum demo uygulamasınınPlaybackService
bölümünde bulabilirsiniz.Taşıma işleminden önce, oturumunuzu kaldırdığınız kod sitesinde medya oturumunu serbest bırakın:
mediaSession?.run { player.release() release() mediaSession = null }
Medya3'te MediaSessionConnector
işlevi
Aşağıdaki tabloda, daha önce MediaSessionConnector
ürününde uygulanmış olan işlevleri gerçekleştiren Media3 API'leri gösterilmektedir.
MediaSessionConnector | AndroidX Medya 3 |
---|---|
CustomActionProvider |
MediaSession.Callback.onCustomCommand()/
MediaSession.setCustomLayout() |
PlaybackPreparer |
MediaSession.Callback.onAddMediaItems()
(prepare() dahili olarak çağrılıyor)
|
QueueNavigator |
ForwardingPlayer |
QueueEditor |
MediaSession.Callback.onAddMediaItems() |
RatingCallback |
MediaSession.Callback.onSetRating() |
PlayerNotificationManager |
DefaultMediaNotificationProvider/
MediaNotification.Provider |
MediaBrowserService
alanını MediaLibraryService
kuruluşuna taşıyın
AndroidX Media3, MediaBrowserServiceCompat
yerine MediaLibraryService
ürününü kullanıma sundu. MediaLibraryService
JavaDoc'u ve üst sınıfı MediaSessionService
, hizmetin eşzamansız programlama modeline ve API'ye iyi bir giriş yapar.
MediaLibraryService
, MediaBrowserService
ile geriye dönük uyumludur. MediaBrowserCompat
veya MediaControllerCompat
kullanan bir istemci uygulaması, MediaLibraryService
cihazına bağlanırken kod değişikliği olmadan çalışmaya devam ediyor. İstemciler için, uygulamanızın MediaLibraryService
mi yoksa eski MediaBrowserServiceCompat
mi kullandığı şeffaftır.
Geriye dönük uyumluluğun çalışması için her iki hizmet arayüzünü de
AndroidManifest.xml
içinde hizmetinize kaydetmeniz gerekir. Bu şekilde müşteri, hizmetinizi gerekli hizmet arayüzü aracılığıyla bulur:<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>
Bağımlılıklarınızı yönettiğiniz
build.gradle
dosyasında AndroidX Media3 oturum modülüne bir uygulama bağımlılığı ekleyin ve eski bağımlılığı kaldırın:implementation "androidx.media3:media3-session:1.3.1"
Hizmetinizi
MediaBrowserService
yerine birMediaLibraryService
öğesinden devralacak şekilde değiştirin Daha önce de belirtildiği gibi,MediaLibraryService
eskiMediaBrowserService
ile uyumludur. Buna göre, hizmetin müşterilere sunduğu daha kapsamlı API hâlâ aynı. Dolayısıyla bir uygulama,MediaBrowserService
öğesini uygulamak için gerekli mantığın çoğunu koruyabilir ve bunu yeniMediaLibraryService
ürününe uyarlayabilir.Eski
MediaBrowserServiceCompat
ile karşılaştırıldığında temel farklar şunlardır:Hizmet yaşam döngüsü yöntemlerini uygulayın: Hizmetin kendisinde geçersiz kılınması gereken yöntemler
onCreate/onDestroy
'dır. Bu yöntemde uygulama; kitaplık oturumunu, oynatıcıyı ve diğer kaynakları ayırır/yayınlar. Standart hizmet yaşam döngüsü yöntemlerine ek olarak, bir uygulamanınonCreate
ürününde yerleşik olarak bulunanMediaLibrarySession
öğesini döndürebilmesi içinonGetSession(MediaSession.ControllerInfo)
öğesini geçersiz kılması gerekir.MediaLibraryService.MediaLibrarySessionCallback: Oturum oluşturmak, gerçek alan API yöntemlerini uygulayan bir
MediaLibraryService.MediaLibrarySessionCallback
gerektirir. Dolayısıyla, eski hizmetin API yöntemlerini geçersiz kılmak yerineMediaLibrarySession.Callback
yöntemini geçersiz kılarsınız.Daha sonra geri çağırma işlevi
MediaLibrarySession
oluşturmak için kullanılır:mediaLibrarySession = MediaLibrarySession.Builder(this, player, MySessionCallback()) .build()
MediaLibrarySessionCallback'in tam API'sini API belgelerinde bulabilirsiniz.
MediaSession.Callback.onAddMediaItems()
uygulayın: Geri çağırmaonAddMediaItems(MediaSession, ControllerInfo, List<MediaItem>)
, medya öğelerini geriye dönük olarak uyumlu bir şekilde oynatmak için oynatıcıya ekleyen çeşitli mevcut ve eski API yöntemlerini sunar. Buna Media3 denetleyicisininMediaController.set/addMediaItems()
yöntemlerinin yanı sıra eski API'ninTransportControls.prepareFrom*/playFrom*
yöntemleri de dahildir. Geri çağırmanın örnek bir uygulamasını oturum demo uygulamasınınPlaybackService
sayfasında bulabilirsiniz.AndroidX Media3, MediaTarayıcıCompat.MediaItem ve MediaMetadataCompat yerine
androidx.media3.common.MediaItem
kullanıyor. Kodunuzun eski sınıflara bağlı bölümlerinin uygun şekilde değiştirilmesi veya Media3MediaItem
ile eşlenmesi gerekir.MediaBrowserServiceCompat
'nin çıkarılabilirResult
yaklaşımının aksine, genel eşzamansız programlama modeliFutures
olarak değiştirildi. Hizmet uygulamanız, bir sonucu çıkarmak yerine eşzamansız birListenableFuture
döndürebilir veya doğrudan bir değer döndürmek için yakın bir Gelecek döndürebilir.
PlayerBildirim Yöneticisini Kaldır
MediaLibraryService
, medya bildirimlerini otomatik olarak destekler ve MediaLibraryService
veya MediaSessionService
kullanılırken PlayerNotificationManager
kaldırılabilir.
Bir uygulama, onCreate()
ürününde DefaultMediaNotificationProvider
öğesinin yerini alan özel bir MediaNotification.Provider
ayarlayarak bildirimi özelleştirebilir. Daha sonra MediaLibraryService
, gerektiği şekilde hizmetin ön planda başlatılmasını sağlar.
MediaLibraryService.updateNotification()
geçersiz kılındığında bir uygulama, bildirim yayınlama ve hizmeti ön planda başlatma/durdurma konusunda tam sahiplik elde edebilir.
MediaTarayıcı kullanarak istemci kodunu taşıma
AndroidX Media3 ile bir MediaBrowser
, MediaController/Player
arayüzlerini uygular ve medya kitaplığına göz atmanın yanı sıra medya oynatmayı kontrol etmek için de kullanılabilir. Eski dünyada hem MediaBrowserCompat
hem de MediaControllerCompat
oluşturmanız gerekiyorsa aynı işlemi yalnızca Media3'teki MediaBrowser
öğesini kullanarak yapabilirsiniz.
Bir MediaBrowser
oluşturulabilir ve oluşturulan hizmetle bağlantının kurulmasını bekleyebilirsiniz:
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)
}
Arka planda oynatmayı kontrol etmek üzere nasıl MediaController
oluşturacağınızı öğrenmek için Medya oturumunda oynatmayı kontrol etme bölümüne göz atın.
Daha fazla işlem yapın ve yer açın
Kararsız API hataları
Media3'e geçiş yaptıktan sonra, kararsız API kullanımlarıyla ilgili lint hataları görebilirsiniz.
Bu API'lerin kullanımı güvenlidir ve lint hataları, yeni ikili uyumluluk garantilerimizin bir yan ürünüdür. Katı ikili uyumluluğu gerekmiyorsa bu hatalar bir @OptIn
ek açıklamasıyla güvenli bir şekilde bastırılabilir.
Arka plan
ExoPlayer v1 veya v2, kitaplığın sonraki sürümler arasında ikili program uyumluluğuna ilişkin katı garantiler vermemiştir. ExoPlayer API yüzeyi, uygulamaların oynatmanın neredeyse her yönünü özelleştirmesine olanak tanımak için tasarım gereği çok büyüktür. ExoPlayer'ın sonraki sürümleri, zaman zaman sembol yeniden adlarını veya zarar veren diğer değişiklikleri (ör. arayüzlerde yeni gerekli yöntemler) kullanıma sunar. Çoğu durumda bu kesintiler, yeni simgenin kullanıma sunulması ve birkaç sürümde eski simgenin kullanımdan kaldırılmasıyla azaltılarak geliştiricilere kullanımlarını taşımaları için zaman tanımakla birlikte bu durum her zaman mümkün olmuyordu.
Bu zarar veren değişiklikler, ExoPlayer v1 ve v2 kitaplıkları kullanıcıları için iki soruna yol açmıştır:
- ExoPlayer sürümüne yükseltme yapmak kodun derlemeyi durdurmasına neden olabilir.
- Hem doğrudan hem de ara bir kitaplık aracılığıyla ExoPlayer'a dayanan bir uygulama, her iki bağımlının da aynı sürümde olmasını sağlamak zorundaydı. Aksi takdirde, ikili program uyumsuzlukları çalışma zamanı kilitlenmelerine neden olabilirdi.
Media3'teki İyileştirmeler
Media3, API yüzeyinin bir alt kümesi için ikili program uyumluluğunu garanti eder. İkili program uyumluluğunu garanti etmeyen bölümler @UnstableApi
ile işaretlenmiştir. Bu ayrımı netleştirmek amacıyla, kararsız API simgelerinin kullanımları, @OptIn
ile ek açıklama eklenmedikçe lint hatası oluşturur.
ExoPlayer v2'den Media3'e geçiş yaptıktan sonra çok sayıda kararsız API lint hatasıyla karşılaşabilirsiniz. Bu durum, Media3'ün ExoPlayer v2'den "daha az kararlı" görünmesine neden olabilir. Böyle bir durum söz konusu değildir. Media3 API'nin "kararsız" bölümleri, ExoPlayer v2 API yüzeyinin tümüyle aynı istikrar düzeyine sahiptir ve kararlı Media3 API yüzeyinin garantileri ExoPlayer v2'de hiçbir şekilde geçerli değildir. Aradaki fark, lint hatasının artık sizi farklı kararlılık düzeyleri hakkında uyarmasıdır.
Kararsız API lint hatalarını işleme
Kararsız API'lerin Java ve Kotlin kullanımlarına @OptIn
ile nasıl ek açıklama yapılacağı hakkında ayrıntılı bilgi için bu lint hatalarıyla ilgili sorun giderme bölümüne bakın.
Desteği sonlandırılmış API'ler
Kullanımdan kaldırılan API'lere yapılan çağrıların Android Studio'da belirdiğini fark edebilirsiniz. Bu tür çağrıları uygun alternatifle değiştirmenizi öneririz. Bunun yerine hangi API'nin kullanılacağını belirten JavaDoc'u görmek için fareyle simgenin üzerine gelin.
Kod örnekleri ve demo uygulamaları
- AndroidX Media3 oturumu demo uygulaması (mobil cihaz ve WearOS)
- Özel işlemler
- Sistem kullanıcı arayüzü bildirimi, MediaButton/BT
- Google Asistan çalma kontrolü
- UAMP: Android Media Player (branch media3) (mobil, AutomotiveOS)
- Sistem kullanıcı arayüzü bildirimi, MediaButton/BT, Oynatmayı devam ettirme
- Google Asistan/WearOS çalma kontrolü
- AutomotiveOS: özel komut ve oturum açma