Şu anda bağımsız com.google.android.exoplayer2
kullanan uygulamalar
kitaplığı ve androidx.media
, androidx.media3
hedefine taşınmalıdır. Tekliflerinizi otomatikleştirmek ve optimize etmek için
Gradle derleme dosyalarını, Java ve
ExoPlayer'daki Kotlin kaynak dosyaları ve XML düzen dosyaları
2.19.1
- AndroidX Media3 1.1.1
.
Genel Bakış
Taşıma işleminden önce aşağıdaki bölümleri inceleyerek hakkında daha fazla bilgi edinin: yeni API'lerin avantajları, taşınacak API'ler ve ön koşulları en az bir tanıtım yapmanız gerekir.
Neden Jetpack Media3'e geçiş yapmalısınız?
- ExoPlayer'ın yeni adresidir.
com.google.android.exoplayer2
ise kullanımdan kaldırıldı. - Bileşenler/işlemler genelinde Player API'ye erişmek için
MediaBrowser
/MediaController
. MediaSession
ve gelişmiş özellikleri olanMediaController
API.- Ayrıntılı erişim denetimi ile oynatma özelliklerinin reklamını yapın.
MediaSessionConnector
ve öğelerini kaldırarak uygulamanızı basitleştirinPlayerNotificationManager
.- Medya uyumlu istemci API'leriyle geriye dönük uyumluluk
(
MediaControllerCompat
/MediaBrowserCompat
/MediaMetadataCompat
)
AndroidX Media3'e taşınacak medya API'leri
- ExoPlayer ve uzantıları
Eski ExoPlayer projesinin mediasession modülü. Şuna bağlı olarak uygulamalar veya modüller:com.google.android.exoplayer2
bölgesindeki paketler şu taşımayla taşınabilir: taşıma komut dosyası. - MediaSessionConnector (sayfanın değerine bağlı olarak
androidx.media.*
androidx.media:media:1.4.3+
paketi)
MediaSessionConnector
öğesini kaldırın ve Bunun yerineandroidx.media3.session.MediaSession
. - MediaTarayıcıServiceCompat (
androidx.media.*
androidx.media:media:1.4.3+
paketi)
androidx.media.MediaBrowserServiceCompat
alt sınıflarını şuraya taşı:androidx.media3.session.MediaLibraryService
ve şunu kullanarak kodlayın:MediaBrowserCompat.MediaItem
-androidx.media3.common.MediaItem
. - MediaTarayıcıCompat (
android.support.v4.media.*
androidx.media:media:1.4.3+
paketi)
İstemci kodunu taşımak içinMediaBrowserCompat
veyaandroidx.media3.session.MediaBrowser
kullanmak içinMediaControllerCompat
androidx.media3.common.MediaItem
ile.
Ö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 kontrolü altında değilse şimdi bunun tam zamanı ilk adımıdır. Herhangi bir nedenle bunu yapmak istemezseniz taşımaya başlamadan önce projenizin yedek kopyasını alın.
Uygulamanızı güncelleme
ExoPlayer kitaplığının en son sürümünü kaldırın ve çağrılarının doğru olup olmadığını kontrol edin. Şunu yapmayı amaçlıyorsanız: Taşıma için komut dosyasını kullanın; üzerinde çalıştığınız sürüme geçiş yapabilirsiniz.
Uygulamanızın derlemeSdkVersion değerini en az 32'ye yükseltin.
Gradle ve Android Studio Gradle eklentisini yeni bir sürüme yükseltin. yukarıda belirtilen güncellenmiş bağımlılıklarla çalışan yeni bir sürüm oluşturun. Örneğin, örnek:
- Android Gradle Eklentisi sürümü: 7.1.0
- Gradle sürümü: 7.4
Yıldız işareti kullanan tüm joker karakter içe aktarma ifadelerini değiştirin (*) ve tam nitelikli içe aktarma ifadeleri kullanın: Joker karakterini silin tam nitelikli dosyayı içe aktarmak için içe aktarma ifadeleri (F2 - Alt/Enter, F2 - Alt/Enter, ...).
com.google.android.exoplayer2.PlayerView
tarihinden şu tarihe kadar veri taşıma:com.google.android.exoplayer2.StyledPlayerView
. Bu gerekli çünkü bu hedefe AndroidX Media3'tecom.google.android.exoplayer2.PlayerView
.
Komut dosyası desteğiyle ExoPlayer'ı taşıyın
Komut dosyası, com.google.android.exoplayer2
ürününden yeni
paket ve modül yapısını androidx.media3
altında bulabilirsiniz. Komut dosyası
projenizde bazı doğrulama kontrollerini gerçekleştirir ve doğrulama başarısız olursa uyarıları yazdırır.
Aksi takdirde, yeniden adlandırılan sınıfların ve paketlerin eşlemelerini
bir Android gradle projesinin kaynakları hakkında daha fazla bilgi edinin.
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
Şu adreste ExoPlayer projesinin etiketinden taşıma komut dosyasını indirin: Uygulamanızı güncellediğiniz sürüme karşılık gelen GitHub:
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.Seçilen dosya grubunu listelemek için komut dosyasını
-l
ile çalıştırın taşıma (girişi uyarı verilmeden 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 öğeye uygulanır dosyası olarak da kaydedebilir.- 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 zorlanır:./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 etme: Bir fark aracı kullanarak düzeltme
komut dosyasında büyük bir hata olduğunu düşünüyorsanız hata
-f
seçeneği belirtilmeden ortaya çıkan genel bir sorun). - Projeyi oluşturma:
./gradlew clean build
veya Android'i kullanabilirsiniz Studio'da Dosya > Projeyi Gradle Dosyalarıyla senkronize edin, ardından Derleme > Projeyi temizle ve ardından Derleme > Projeyi yeniden derleyin (derlemenizi "Derleme - Derleme Çıkışı" sekmesi.
Ö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 üzerine getirin ve JavaDoc'a bakın işaretini kaldırın.
- İçe aktarma ifadelerini sıralama: Projeyi Android Studio'da açın ve 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 içe aktarma işlemlerini optimize edin.
MediaSessionConnector
yerine androidx.media3.session.MediaSession
yazın
Eski MediaSessionCompat
dünyasında MediaSessionConnector
değeri şuydu:
oynatıcının durumunu oturumun durumuyla senkronize etmekten sorumludur
ve denetleyicilerden uygun yetkiye ihtiyaç duyan komutlar almak,
oynatıcı yöntemleri. AndroidX Media3'te bu işlem doğrudan MediaSession
tarafından yapılır
olmadan da kullanabilirsiniz.
MediaSessionConnector'ın tüm referanslarını ve kullanımını kaldırın: Daha önce taşımak için otomatik komut dosyasını, ardından komut dosyası muhtemelen kodunuzu
MediaSessionConnector
için de kullanılabilir. Android Studio, uygulamayı geliştirmeye veya başlatmaya çalışırken bozuk kodu size gösterebilir.Bağımlılıklarınızı yönettiğiniz
build.gradle
dosyasına bir AndroidX Media3 oturum modülüne uygulama bağımlılığı ve kaldırma eski bağımlılığı var:implementation "androidx.media3:media3-session:1.4.0"
MediaSessionCompat
değerini şununla değiştirin:androidx.media3.session.MediaSession
Eski
MediaSessionCompat
kodunu oluşturduğunuz kod sitesinde bir alan oluşturmak içinandroidx.media3.session.MediaSession.Builder
MediaSession
. 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. Eğer denetleyicilerin oynatıcıya medya öğeleri eklemesine izin vermek istiyorsanızMediaSession.Callback.onAddMediaItems()
. Çeşitli mevcut ve şurada oynatılmak üzere oynatıcıya medya öğeleri ekleyen eski API yöntemleri: uyumlu bir şekilde kullanabilirsiniz. Bu, Media3 denetleyicisininMediaController.set/addMediaItems()
yöntemi,TransportControls.prepareFrom*/playFrom*
yöntemlerine göz atacağız. Örnek bironAddMediaItems
uygulaması, oturum demo uygulamasınınPlaybackService
içinde bulabilirsiniz.Oturumunuzu kaldırdığınız kod sitesinde medya oturumunu serbest bırakın Taşıma işleminden önce:
mediaSession?.run { player.release() release() mediaSession = null }
Medya3'te MediaSessionConnector
işlevi
Aşağıdaki tabloda, işlevsellik sağlayan Media3 API'leri gösterilmektedir
daha önce MediaSessionConnector
ürününde uygulandı.
MediaSessionConnector | AndroidX Medya 3 |
---|---|
CustomActionProvider |
MediaSession.Callback.onCustomCommand()/
MediaSession.setCustomLayout() |
PlaybackPreparer |
MediaSession.Callback.onAddMediaItems() .
(prepare() dahili olarak çağrılır)
|
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,MediaLibraryService
MediaBrowserServiceCompat
. MediaLibraryService
JavaDoc'u ve süper içeriği
MediaSessionService
sınıfı API ve
eşzamansız programlama modelidir.
MediaLibraryService
,
MediaBrowserService
. MediaBrowserCompat
veya
MediaControllerCompat
, bağlanırken kod değişiklikleri olmadan çalışmaya devam ediyor
MediaLibraryService
olarak ayarladınız. Müşteriler için, uygulamanızın güvenlik açıklarına veya
MediaLibraryService
veya eski bir MediaBrowserServiceCompat
kullanıyorsanız.
![Hizmet, etkinlik ve harici uygulamaları içeren uygulama bileşeni diyagramı.](https://developer.android.com/static/media/images/overview.png?authuser=9&hl=tr)
Geriye dönük uyumluluğun çalışması için her iki hizmeti de kaydetmeniz gerekir arayüzlerini
AndroidManifest.xml
'da hizmete sokun. Bu şekilde Müşteri, hizmetinizi gerekli hizmet arayüzüne göre 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ına bir AndroidX Media3 oturum modülüne uygulama bağımlılığı ve eski bağımlılığı kaldırın:implementation "androidx.media3:media3-session:1.4.0"
Hizmetinizi,
MediaLibraryService
yerineMediaBrowserService
Daha önce belirtildiği gibiMediaLibraryService
, eski sürümle uyumludur.MediaBrowserService
. Buna göre, hizmetin hâlâ aynı olduğunu duymuş olabilirsiniz. Uygulama, büyük olasılıklaMediaBrowserService
öğesini uygulamak için gereken mantığın çoğu ve yeniMediaLibraryService
için uyarlayacağım.Eski sürüme kıyasla temel farklar
MediaBrowserServiceCompat
aşağıdaki gibidir:Hizmet yaşam döngüsü yöntemlerini uygulama: Uygulanması gereken
onCreate/onDestroy
olduğunda geçersiz kılınır. Bu durumda Uygulama; kitaplık oturumunu, oynatıcıyı ve diğer öğeleri ayırdığında/yayınladığında kaynaklar. Uygulama, standart hizmet yaşam döngüsü yöntemlerinin yanı sıra geri dönmek içinonGetSession(MediaSession.ControllerInfo)
politikasını geçersiz kılması gerekiyoronCreate
ürününde yerleşik olarak bulunanMediaLibrarySession
.Implement MediaLibraryService.MediaLibrarySessionCallback: Oluşturma her oturum için Şunu uygulayan
MediaLibraryService.MediaLibrarySessionCallback
: alan API'si yöntemleri hakkında daha fazla bilgi edinin. Bu nedenle, API yöntemlerini geçersiz kılmak yerine eski hizmet geri dönerseniz, Bunun yerineMediaLibrarySession.Callback
.Daha sonra geri çağırma işlevi
MediaLibrarySession
oluşturmak için kullanılır:mediaLibrarySession = MediaLibrarySession.Builder(this, player, MySessionCallback()) .build()
API'de MediaLibrarySessionCallback'in tam API'sini bulun belgelerinden faydalanabilirsiniz.
MediaSession.Callback.onAddMediaItems()
uygulamasını uygulama: Geri çağırmaonAddMediaItems(MediaSession, ControllerInfo, List<MediaItem>)
hizmet veriyor oynatıcıya medya öğeleri ekleyen çeşitli mevcut ve eski API yöntemleri uyumlu bir şekilde oynatabilmenizi sağlar. Bu, Media3 denetleyicisininMediaController.set/addMediaItems()
yöntemi,TransportControls.prepareFrom*/playFrom*
yöntemlerine göz atacağız. Geri çağırma örnek bir uygulaması, oturum demo uygulamasınınPlaybackService
bölümünde bulabilirsiniz.AndroidX Media3 bunun yerine
androidx.media3.common.MediaItem
kullanıyor (MediaTarayıcıCompat.MediaItem ve MediaMetadataCompat) Parçalar eski sınıflara bağlı kodunuzun uygun şekilde değiştirilmesi gerekir veya Medya3MediaItem
ile eşleyin.Genel eşzamansız programlama modeli
Futures
olarak değiştirildi. ve çıkarımlıResult
yaklaşımının karşıtı olarakMediaBrowserServiceCompat
. Hizmet uygulamanız sonucu ayırmak yerine zaman uyumsuzListenableFuture
doğrudan bir değer döndürmek için yakın bir Gelecek döndürür.
PlayerBildirim Yöneticisini Kaldır
MediaLibraryService
, medya bildirimlerini otomatik olarak destekler ve
PlayerNotificationManager
, MediaLibraryService
veya
MediaSessionService
.
Bir uygulama, özel bir ayar yaparak bildirimi özelleştirebilir
onCreate()
dilinde, şunun yerini alan MediaNotification.Provider
:
DefaultMediaNotificationProvider
. Ardından MediaLibraryService
,
hizmetin ön planda başlatılmasını sağlar.
MediaLibraryService.updateNotification()
geçersiz kılındığında bir uygulama daha fazla işlem yapabilir
ve hizmeti başlatma/durdurma konusundaki sorumluluğun
gerektiği şekilde ön plana koyabilirsiniz.
MediaTarayıcı kullanarak istemci kodunu taşıma
AndroidX Media3 ile bir MediaBrowser
, MediaController/Player
arayüzleri vardır ve medyaya göz atmanın yanı sıra medya oynatmayı kontrol etmek için de kullanılabilir
kitaplığını açar. Bir MediaBrowserCompat
ve bir
MediaControllerCompat
kullanıyorsanız aynı işlemi yalnızca
Medya3'teki MediaBrowser
.
Bir MediaBrowser
oluşturulabilir ve
oluşturulmakta olan hizmet:
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)
}
Şu bilgileri inceleyin:
Medya oturumunda oynatmayı kontrol etme
kontrol etmek üzere bir MediaController
oluşturacağınızı öğrenin.
arka plan.
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ı,
ikili uyumluluk garantileridir. Katı ikili program gerekli değilse
Bu hatalar, @OptIn
ile güvenli bir şekilde bastırılabilir.
ek açıklaması da yer alır.
Arka plan
ExoPlayer v1 ve v2, ikili program uyumluluğu hakkında kesin garanti vermedi çıkarmanıza yardımcı olabilir. ExoPlayer API yüzeyleri, çoğu zaman büyük bir tasarıma sahip. Böylece, uygulamaların oynatmaya devam edebilirsiniz. ExoPlayer'ın sonraki sürümleri zaman zaman simge yeniden adlandırmalar veya zarar veren diğer değişiklikler (ör. arayüzlerde yeni gerekli yöntemler). İçinde çoğu durumda bu kesintiler, yeni semboller uygulanarak azaltılmıştı. birkaç sürümde eski simgenin kullanımdan kaldırılmasının yanı sıra, her zaman uygun olmadı. Ancak bu her zaman mümkün değildi.
Bu zarar veren değişiklikler, ExoPlayer v1 kullanıcıları için iki soruna neden oldu. ve v2 kitaplıkları:
- ExoPlayer sürümüne yükseltme yapmak kodun derlemeyi durdurmasına neden olabilir.
- Hem doğrudan hem de bir ara platform aracılığıyla ExoPlayer'a dayanan bir uygulama her iki bağımlılığın da aynı sürümde olması gerekiyordu. Aksi takdirde ikili program uyumsuzlukları, çalışma zamanı kilitlenmelerine neden olabilir.
Media3'teki İyileştirmeler
Media3, API yüzeyinin bir alt kümesi için ikili program uyumluluğunu garanti eder. İlgili içeriği oluşturmak için kullanılan
ikili program uyumluluğunu garanti etmeyen bölümler
@UnstableApi
. Bu ayrımı netleştirmek amacıyla, istikrarsız veri kullanımı,
API sembolleri, @OptIn
ile açıklama eklenmedikçe lint hatası oluşturur.
ExoPlayer v2'den Media3'e geçiş yaptıktan sonra çok sayıda kararsız API ile karşılaşabilirsiniz lint hatalarını gider. Bu durum, Media3'ün "daha az kararlı" görünmesine neden olabilir. ExoPlayer'dan daha sürüm 2. Böyle bir durum söz konusu değildir. 'İstikrarsız' parçaları için aynı ExoPlayer v2 API yüzeyinin tamamı olarak kararlılık düzeyi ve kararlı Media3 API yüzeyinin garantileri şu adresteki ExoPlayer v2'de yoktur: Tümü'ne dokunun. Aradaki fark basit bir şekilde, bir lint hatasının artık sizi farklı riskleri ele alacağız.
Kararsız API lint hatalarını işleme
Nasıl yapılacağıyla ilgili ayrıntılar için bu lint hatalarıyla ilgili sorun giderme bölümüne bakın
Kararsız API'lerin Java ve Kotlin kullanımlarına @OptIn
ile açıklama ekleyin.
Desteği sonlandırılmış API'ler
Kullanımdan kaldırılan API'lere yapılan çağrıların Android'de çarpıtıldığını fark edebilirsiniz. Stüdyo'yu seçin. 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.
![Ekran görüntüsü: JavaDoc'u kullanımdan kaldırılmış alternatif bir yöntemle görüntüleme](https://developer.android.com/static/media/media3/exoplayer/images/deprecation.png?authuser=9&hl=tr)
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