AndroidX Media3 taşıma kılavuzu

Ş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 olan MediaController API.
• Ayrıntılı erişim denetimi ile oynatma özelliklerinin reklamını yapın.
• MediaSessionConnector ve öğelerini kaldırarak uygulamanızı basitleştirin PlayerNotificationManager.
• 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 yerine androidx.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çin MediaBrowserCompat veya androidx.media3.session.MediaBrowser kullanmak için MediaControllerCompat androidx.media3.common.MediaItem ile.

Ön koşullar

1. 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.

2. 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'te com.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

Uyarı: Bağımlılık beyanları değişkenler veya gelişmiş teknikler kullanır.

1. Ş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"
   

2. Komut dosyasını yürütülebilir hale getirin:

   chmod 744 media3-migration.sh
   

3. Seçenekler hakkında bilgi edinmek için komut dosyasını --help ile çalıştırın.

4. 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
   

5. 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
   

ziyaret edin.

Not: -x parametresini kullanarak belirli bir yol için seçili yolu hariç tutabilirsiniz değiştirin.

 # 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:

1. 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).
2. 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.

ziyaret edin.

Not: Bazı durumlarda komut dosyasının projenizi bir durumda bırakması beklenir emin olun. Komut dosyası bu konuda uyarıda bulunuyor ve yürütmeye zorlamak için -f seçeneğini ister. Örneğin, bu sene Bir uygulamada MediaSessionConnector ve MediaSessionCompat kullanılıyorsa. Bkz. MediaSessionConnector ürününden Medya 3.

Önerilen takip adımları:

1. Kararsız API'lerin kullanımıyla ilgili hatalar için kaydolma sorununu çözün.
2. 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.
3. İç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.

1. 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.

2. 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"
   

3. MediaSessionCompat değerini şununla değiştirin: androidx.media3.session.MediaSession

4. Eski MediaSessionCompat kodunu oluşturduğunuz kod sitesinde bir alan oluşturmak için androidx.media3.session.MediaSession.Builder MediaSession. Oturum oluşturucuyu oluşturmak için oynatıcıyı iletin.

   Not: Uygulamanız ExoPlayer uygulamasından farklı bir oynatıcı kullanıyorsa API'ye aktarabileceğiniz özel bir Player uygulamasına Oynatıcınızı sarmalayan MediaSession. Bu konuda daha fazla bilgi vereceğiz Medya ile birlikte çalışan minimum bir Player uygulaması çevresinde oturum uygulaması.

   val player = ExoPlayer.Builder(context).build()
   mediaSession = MediaSession.Builder(context, player)
       .setSessionCallback(MySessionCallback())
       .build()
   

   Not: Player için yapılan herhangi bir yöntem çağrısını bir ForwardingPlayer(player) olmalıdır.

5. 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ız MediaSession.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 denetleyicisinin MediaController.set/addMediaItems() yöntemi, TransportControls.prepareFrom*/playFrom* yöntemlerine göz atacağız. Örnek bir onAddMediaItems uygulaması, oturum demo uygulamasının PlaybackService içinde bulabilirsiniz.

6. 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
   }
   

   Not: Yeni bir oturum oluşturmadan önce medya oturumunu serbest bırakmak önemlidir aynı kimlikle. Bir uygulama oturum sızdırıyorsa Media3 istisnayı bildirir örneğine bakalım.

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.

Şekil 1: Medya uygulaması bileşenine genel bakış

1. 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>
   

2. 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"
   

3. Hizmetinizi, MediaLibraryService yerine MediaBrowserService Daha önce belirtildiği gibi MediaLibraryService, eski sürümle uyumludur. MediaBrowserService. Buna göre, hizmetin hâlâ aynı olduğunu duymuş olabilirsiniz. Uygulama, büyük olasılıkla MediaBrowserService öğesini uygulamak için gereken mantığın çoğu ve yeni MediaLibraryService 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çin onGetSession(MediaSession.ControllerInfo) politikasını geçersiz kılması gerekiyor onCreate ürününde yerleşik olarak bulunan MediaLibrarySession.

   • 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 yerine MediaLibrarySession.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ğırma onAddMediaItems(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 denetleyicisinin MediaController.set/addMediaItems() yöntemi, TransportControls.prepareFrom*/playFrom* yöntemlerine göz atacağız. Geri çağırma örnek bir uygulaması, oturum demo uygulamasının PlaybackService 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 Medya3 MediaItem ile eşleyin.

   • Genel eşzamansız programlama modeli Futures olarak değiştirildi. ve çıkarımlı Result yaklaşımının karşıtı olarak MediaBrowserServiceCompat. Hizmet uygulamanız sonucu ayırmak yerine zaman uyumsuz ListenableFuture 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.

Not: API Düzeyi 28 ve sonraki sürümleri hedefleyen uygulamaların yine de FOREGROUND_SERVICE gerekir.

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.

Not: Kotlin kullanıcıları kotlin-coroutines-guava veya Uzantı yöntemini eklemek için build.gradle dosyasına androidx.concurrent ListenableFuture'a await. Bu sayede MediaBrowser API daha uygun hale gelir doğal olarak suspend yöntemine dönüştürülebilir.

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ı:

1. ExoPlayer sürümüne yükseltme yapmak kodun derlemeyi durdurmasına neden olabilir.
2. 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.

Şekil 3: Android Studio'daki JavaDoc ipucu, kullanımdan kaldırılan simgeler için bir alternatif önerir.

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