คำแนะนำในการย้ายข้อมูล AndroidX Media3

แอปที่ใช้ไลบรารี com.google.android.exoplayer2 และ androidx.media แบบสแตนด์อโลนอยู่ในปัจจุบันควรย้ายข้อมูลไปยัง androidx.media3 ใช้สคริปต์การย้ายข้อมูลเพื่อย้ายข้อมูลไฟล์บิลด์ Gradle, ไฟล์ต้นฉบับ Java และ Kotlin รวมถึงไฟล์เลย์เอาต์ XML จาก ExoPlayer 2.19.1 ไปยัง AndroidX Media3 1.1.1

ภาพรวม

ก่อนย้ายข้อมูล โปรดอ่านส่วนต่อไปนี้เพื่อดูข้อมูลเพิ่มเติมเกี่ยวกับประโยชน์ของ API ใหม่, API ที่จะย้ายข้อมูล และข้อกำหนดเบื้องต้นที่โปรเจ็กต์ของแอปควรมี

เหตุผลที่ควรย้ายข้อมูลไปยัง Jetpack Media3

• ซึ่งเป็นบ้านหลังใหม่ของ ExoPlayer ส่วน com.google.android.exoplayer2 จะหยุดให้บริการ
• เข้าถึง Player API ในคอมโพเนนต์/กระบวนการต่างๆ ด้วย MediaBrowser/MediaController
• ใช้ความสามารถเพิ่มเติมของ API MediaSession และ MediaController
• โฆษณาความสามารถในการเล่นด้วยการควบคุมการเข้าถึงแบบละเอียด
• ทำให้แอปของคุณเรียบง่ายขึ้นโดยนำ MediaSessionConnector และ PlayerNotificationManager ออก
• เข้ากันได้แบบย้อนหลังกับ API ไคลเอ็นต์ media-compat (MediaBrowserCompat/MediaControllerCompat/MediaMetadataCompat)

Media API ที่จะย้ายข้อมูลไปยัง AndroidX Media3

• ExoPlayer และส่วนขยาย
  ซึ่งรวมถึงโมดูลทั้งหมดของโปรเจ็กต์ ExoPlayer เดิม ยกเว้นโมดูล mediasession ที่ปิดให้บริการแล้ว แอปหรือโมดูลที่ขึ้นอยู่กับแพ็กเกจใน com.google.android.exoplayer2 สามารถย้ายข้อมูลได้ด้วยสคริปต์การย้ายข้อมูล
• MediaSessionConnector (ขึ้นอยู่กับแพ็กเกจ androidx.media.* ของ androidx.media:media:1.4.3+)
  นำ MediaSessionConnector ออกและใช้ androidx.media3.session.MediaSession แทน
• MediaBrowserServiceCompat (ขึ้นอยู่กับแพ็กเกจ androidx.media.* ของ androidx.media:media:1.4.3+)
  ย้ายข้อมูลคลาสย่อยของ androidx.media.MediaBrowserServiceCompat ไปยัง androidx.media3.session.MediaLibraryService และโค้ดที่ใช้ MediaBrowserCompat.MediaItem ไปยัง androidx.media3.common.MediaItem
• MediaBrowserCompat (ขึ้นอยู่กับแพ็กเกจ android.support.v4.media.* ของ androidx.media:media:1.4.3+)
  ย้ายข้อมูลโค้ดไคลเอ็นต์โดยใช้ MediaBrowserCompat หรือ MediaControllerCompat เพื่อใช้ androidx.media3.session.MediaBrowser กับ androidx.media3.common.MediaItem

สิ่งที่ต้องมีก่อน

1. ตรวจสอบว่าโปรเจ็กต์อยู่ภายใต้การควบคุมแหล่งที่มา

   ตรวจสอบว่าคุณสามารถเปลี่ยนกลับการเปลี่ยนแปลงที่ใช้โดยเครื่องมือย้ายข้อมูลแบบสคริปต์ได้อย่างง่ายดาย หากคุณยังไม่มีโปรเจ็กต์ภายใต้การควบคุมแหล่งที่มา ตอนนี้เป็นเวลาที่เหมาะสมที่จะเริ่มดำเนินการ หากไม่ต้องการทำเช่นนั้นด้วยเหตุผลบางประการ ให้สำเนาสำรองของโปรเจ็กต์ก่อนเริ่มการย้ายข้อมูล

2. อัปเดตแอป

   • เราขอแนะนำให้อัปเดตโปรเจ็กต์เพื่อใช้ไลบรารี ExoPlayer เวอร์ชันล่าสุด และนำการเรียกใช้เมธอดที่เลิกใช้งานแล้วออก หากต้องการใช้สคริปต์ในการย้ายข้อมูล คุณต้องจับคู่เวอร์ชันที่กำลังอัปเดตกับเวอร์ชันที่สคริปต์จัดการ

   • เพิ่ม compileSdkVersion ของแอปเป็นอย่างน้อย 32

   • อัปเกรด Gradle และปลั๊กอิน Android Studio Gradle เป็นเวอร์ชันล่าสุดที่ใช้งานได้กับทรัพยากร Dependency ที่อัปเดตจากด้านบน เช่น

     • เวอร์ชันปลั๊กอิน Android Gradle: 7.1.0
     • เวอร์ชัน Gradle: 7.4

   • แทนที่คำสั่งการนำเข้าไวลด์การ์ดทั้งหมดที่ใช้เครื่องหมายดอกจัน (*) และใช้คำสั่งการนำเข้าที่สมบูรณ์ โดยลบคำสั่งการนำเข้าไวลด์การ์ดและใช้ Android Studio เพื่อนำเข้าคำสั่งที่สมบูรณ์ (F2 - Alt/Enter, F2 - Alt/Enter, ...)

   • ย้ายข้อมูลจาก com.google.android.exoplayer2.PlayerView ไปยัง com.google.android.exoplayer2.StyledPlayerView ซึ่งจำเป็นเนื่องจากไม่มีคลาสที่เทียบเท่ากับ com.google.android.exoplayer2.PlayerView ใน AndroidX Media3

ย้ายข้อมูล ExoPlayer ด้วยการรองรับสคริปต์

สคริปต์นี้ช่วยให้การย้ายจาก com.google.android.exoplayer2 ไปยังโครงสร้างแพ็กเกจและโมดูลใหม่ภายใต้ androidx.media3 เป็นไปอย่างราบรื่น สคริปต์จะใช้การตรวจสอบความถูกต้องบางอย่างกับโปรเจ็กต์และพิมพ์คำเตือนหากการตรวจสอบไม่สำเร็จ ไม่เช่นนั้น ระบบจะใช้การแมปคลาสและแพ็กเกจที่เปลี่ยนชื่อในทรัพยากรของโปรเจ็กต์ Android Gradle ที่เขียนด้วย Java หรือ Kotlin

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

การใช้สคริปต์การย้ายข้อมูล

1. ดาวน์โหลดสคริปต์การย้ายข้อมูลจากแท็กของโปรเจ็กต์ ExoPlayer ใน GitHub ที่สอดคล้องกับเวอร์ชันที่คุณอัปเดตแอป:

   curl -o media3-migration.sh \
     "https://raw.githubusercontent.com/google/ExoPlayer/r2.19.1/media3-migration.sh"
   

2. ทำให้สคริปต์เรียกใช้ได้โดยทำดังนี้

   chmod 744 media3-migration.sh
   

3. เรียกใช้สคริปต์ด้วย --help เพื่อดูข้อมูลเกี่ยวกับตัวเลือกต่างๆ

4. เรียกใช้สคริปต์ด้วย -l เพื่อแสดงรายการชุดไฟล์ที่เลือกสำหรับการย้ายข้อมูล (ใช้ -f เพื่อบังคับให้แสดงรายการโดยไม่มีคำเตือน)

   ./media3-migration.sh -l -f /path/to/gradle/project/root
   

5. เรียกใช้สคริปต์ด้วย -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

1. ตรวจสอบว่าสคริปต์เปลี่ยนโค้ดอย่างไร: ใช้เครื่องมือ Diff และแก้ไขปัญหาที่อาจเกิดขึ้น (พิจารณายื่นข้อบกพร่องหากคุณคิดว่าสคริปต์มีปัญหาทั่วไปที่เกิดขึ้นโดยไม่ได้ส่งตัวเลือก -f)
2. สร้างโปรเจ็กต์: ใช้ ./gradlew clean build หรือใน Android Studio ให้เลือกไฟล์ > ซิงค์โปรเจ็กต์กับไฟล์ Gradle จากนั้นเลือกสร้าง > ล้างโปรเจ็กต์ แล้วเลือกสร้าง > สร้างโปรเจ็กต์อีกครั้ง (ตรวจสอบบิลด์ในแท็บ "สร้าง - เอาต์พุตของบิลด์" ของ Android Studio)

ขั้นตอนการติดตามผลที่แนะนำ

1. แก้ไขการเลือกใช้เพื่อรับข้อผิดพลาดเกี่ยวกับการใช้ API ที่ไม่เสถียร
2. แทนที่การเรียก API ที่เลิกใช้งานแล้ว: ใช้ API ทดแทนที่แนะนำ วางเคอร์เซอร์เหนือคำเตือนใน Android Studio และดู JavaDoc ของสัญลักษณ์ที่เลิกใช้งานแล้วเพื่อดูว่าควรใช้อะไรแทนการเรียกที่ระบุ
3. จัดเรียงคำสั่งนำเข้า: เปิดโปรเจ็กต์ใน Android Studio จากนั้นคลิกขวาที่โหนดโฟลเดอร์แพ็กเกจในโปรแกรมดูโปรเจ็กต์ แล้วเลือกเพิ่มประสิทธิภาพการนำเข้าในแพ็กเกจที่มีไฟล์ต้นฉบับที่เปลี่ยนแปลง

แทนที่ MediaSessionConnector ด้วย androidx.media3.session.MediaSession

ในโลก MediaSessionCompat เดิม MediaSessionConnector มีหน้าที่ซิงค์สถานะของเพลเยอร์กับสถานะของเซสชันและรับคำสั่งจากตัวควบคุมที่ต้องมอบสิทธิ์ไปยังเมธอดเพลเยอร์ที่เหมาะสม เมื่อใช้ AndroidX Media3 การดำเนินการนี้จะทำโดย MediaSession โดยตรงโดยไม่ต้องใช้เครื่องมือเชื่อมต่อ

1. นำการอ้างอิงและการใช้งาน MediaSessionConnector ทั้งหมดออก: หากคุณใช้สคริปต์อัตโนมัติเพื่อย้ายข้อมูลคลาสและแพ็กเกจ ExoPlayer สคริปต์อาจทำให้โค้ดของคุณอยู่ในสถานะที่คอมไพล์ไม่ได้เกี่ยวกับ MediaSessionConnector ที่แก้ไขไม่ได้ Android Studio จะแสดงโค้ดที่ใช้งานไม่ได้เมื่อคุณพยายามสร้างหรือเริ่มแอป

2. ในไฟล์ build.gradle ที่คุณเก็บรักษาทรัพยากร Dependency ให้เพิ่มทรัพยากร Dependency ของการติดตั้งใช้งานลงในโมดูลเซสชัน AndroidX Media3 และนำทรัพยากร Dependency เดิมออก ดังนี้

   implementation "androidx.media3:media3-session:1.11.1"
   

3. แทนที่ MediaSessionCompat ด้วย androidx.media3.session.MediaSession

4. ในเว็บไซต์โค้ดที่คุณสร้าง MediaSessionCompat เดิม ให้ใช้ androidx.media3.session.MediaSession.Builder เพื่อสร้าง MediaSession ส่งผ่านเพลเยอร์เพื่อสร้างเครื่องมือสร้างเซสชัน

   Kotlin

   val player = ExoPlayer.Builder(context).build()
   mediaSession = MediaSession.Builder(context, player).setCallback(MySessionCallback()).build()
   MigrationGuide.kt

   Java

   ExoPlayer player = new ExoPlayer.Builder(context).build();
   mediaSession =
       new MediaSession.Builder(context, player).setCallback(new MySessionCallback()).build();
   MigrationGuide.java

5. ใช้ MySessionCallback ตามที่แอปกำหนด ขั้นตอนนี้ไม่บังคับ หากต้องการอนุญาตให้ตัวควบคุมเพิ่มรายการสื่อลงในเพลเยอร์ ให้ใช้ MediaSession.Callback.onAddMediaItems() โดยจะแสดงเมธอด API ปัจจุบันและเดิมต่างๆ ที่เพิ่มรายการสื่อลงในเพลเยอร์เพื่อเล่นในลักษณะที่เข้ากันได้แบบย้อนหลัง ซึ่งรวมถึงเมธอด MediaController.set/addMediaItems() ของตัวควบคุม Media3 และเมธอด TransportControls.prepareFrom*/playFrom* ของ API เดิม ดูตัวอย่างการใช้งาน onAddMediaItems ได้ใน PlaybackService ของแอปเดโมของเซสชัน

6. ปล่อยเซสชันสื่อที่เว็บไซต์โค้ดที่คุณทำลายเซสชันก่อนการย้ายข้อมูล ดังนี้

   Kotlin

   mediaSession?.run {
     player.release()
     release()
     mediaSession = null
   }
   MigrationGuide.kt

   Java

   if (mediaSession != null) {
     mediaSession.getPlayer().release();
     mediaSession.release();
     mediaSession = null;
   }
   MigrationGuide.java

ฟังก์ชันการทำงานของ MediaSessionConnector ใน Media3

ตารางต่อไปนี้แสดง Media3 API ที่จัดการฟังก์ชันการทำงานที่เคยใช้ใน MediaSessionConnector

ย้ายข้อมูล MediaBrowserService ไปยัง MediaLibraryService

AndroidX Media3 เปิดตัว MediaLibraryService ซึ่งจะมาแทนที่ MediaBrowserServiceCompat JavaDoc ของ MediaLibraryService และซูเปอร์คลาส MediaSessionService จะให้ข้อมูลเบื้องต้นที่ดีเกี่ยวกับ API และโมเดลการเขียนโปรแกรมแบบอะซิงโครนัสของบริการ

MediaLibraryService เข้ากันได้แบบย้อนหลังกับ MediaBrowserService แอปไคลเอ็นต์ที่ใช้ MediaBrowserCompat หรือ MediaControllerCompat จะยังคงทำงานต่อไปโดยไม่ต้องเปลี่ยนโค้ดเมื่อเชื่อมต่อกับ MediaLibraryService สำหรับไคลเอ็นต์ จะเห็นได้อย่างชัดเจนว่าแอปของคุณใช้ MediaLibraryService หรือ MediaBrowserServiceCompat เดิม

1. เพื่อให้ความเข้ากันได้แบบย้อนหลังทำงานได้ คุณต้องลงทะเบียนอินเทอร์เฟซบริการทั้ง 2 รายการกับบริการของคุณใน 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>
   

2. ในไฟล์ build.gradle ที่คุณเก็บรักษาทรัพยากร Dependency ให้เพิ่มทรัพยากร Dependency ของการติดตั้งใช้งานลงในโมดูลเซสชัน AndroidX Media3 และนำทรัพยากร Dependency เดิมออก ดังนี้

   implementation "androidx.media3:media3-session:1.11.1"
   

3. เปลี่ยนบริการให้รับค่าจาก MediaLibraryService แทน MediaBrowserService ดังที่กล่าวไว้ก่อนหน้านี้ MediaLibraryService เข้ากันได้กับ MediaBrowserService เดิม ดังนั้น API ที่กว้างขึ้นซึ่งบริการนี้เสนอให้กับไคลเอ็นต์จึงยังคงเหมือนเดิม ดังนั้นจึงเป็นไปได้ว่าแอปจะเก็บตรรกะส่วนใหญ่ที่จำเป็นในการใช้ MediaBrowserService ไว้ได้ และปรับให้เข้ากับ MediaLibraryService ใหม่

   ความแตกต่างหลักๆ เมื่อเทียบกับ MediaBrowserServiceCompat เดิมมีดังนี้

   • ใช้เมธอดวงจรของบริการ: เมธอดที่ต้องลบล้างในบริการคือ onCreate/onDestroy ซึ่งแอปจะจัดสรร/ปล่อยเซสชันไลบรารี โปรแกรมเล่น และทรัพยากรอื่นๆ นอกเหนือจากเมธอดวงจรของบริการมาตรฐานแล้ว แอปยังต้องลบล้าง onGetSession(MediaSession.ControllerInfo) เพื่อแสดงผล MediaLibrarySession ที่สร้างใน onCreate ด้วย

   • ใช้ MediaLibraryService.MediaLibrarySessionCallback: การสร้างเซสชันต้องใช้ MediaLibraryService.MediaLibrarySessionCallback ที่ใช้เมธอด API ของโดเมนจริง ดังนั้น แทนที่จะลบล้างเมธอด API ของบริการเดิม คุณจะลบล้างเมธอดของ MediaLibrarySession.Callback แทน

     จากนั้นระบบจะใช้ Callback เพื่อสร้าง MediaLibrarySession ดังนี้

     Kotlin

     mediaLibrarySession = MediaLibrarySession.Builder(context, player, MySessionCallback()).build()
     MigrationGuide.kt

     Java

     mediaLibrarySession =
         new MediaLibrarySession.Builder(context, player, new MySessionCallback()).build();
     MigrationGuide.java

     ดู API แบบเต็มของ MediaLibrarySessionCallback ในเอกสารประกอบของ API

   • ใช้ MediaSession.Callback.onAddMediaItems(): แฮนเดิล onAddMediaItems(MediaSession, ControllerInfo, List<MediaItem>) จะแสดงเมธอด API ปัจจุบันและเดิมต่างๆ ที่เพิ่มรายการสื่อลงในเพลเยอร์เพื่อเล่นในลักษณะที่เข้ากันได้แบบย้อนหลัง ซึ่งรวมถึงเมธอด MediaController.set/addMediaItems() ของตัวควบคุม Media3 และเมธอด TransportControls.prepareFrom*/playFrom* ของ API เดิม ดูตัวอย่างการใช้งาน Callback ได้ใน PlaybackService ของแอปเดโมของเซสชัน

   • AndroidX Media3 ใช้ androidx.media3.common.MediaItem แทน MediaBrowserCompat.MediaItem และ MediaMetadataCompat คุณต้องเปลี่ยนส่วนต่างๆ ของโค้ดที่เชื่อมโยงกับคลาสเดิมให้สอดคล้องกันหรือแมปกับ MediaItem ของ Media3 แทน

   • โมเดลการเขียนโปรแกรมแบบอะซิงโครนัสทั่วไปเปลี่ยนเป็น Futures ซึ่งตรงกันข้ามกับแนวทาง Result ที่แยกออกได้ของ MediaBrowserServiceCompat การติดตั้งใช้งานบริการสามารถแสดงผล ListenableFuture แบบอะซิงโครนัสแทนการแยกผลลัพธ์หรือแสดงผล Future ทันทีเพื่อแสดงผลค่าโดยตรง

นำ PlayerNotificationManager ออก

MediaLibraryService รองรับการแจ้งเตือนเกี่ยวกับสื่อโดยอัตโนมัติ และสามารถนำ PlayerNotificationManager ออกได้เมื่อใช้ MediaLibraryService หรือ MediaSessionService

แอปสามารถปรับแต่งการแจ้งเตือนได้โดยตั้งค่า MediaNotification.Provider ที่กำหนดเองใน onCreate() ซึ่งจะแทนที่ DefaultMediaNotificationProvider จากนั้น MediaLibraryService จะดูแลการเริ่มบริการที่ทำงานอยู่เบื้องหน้าตามที่จำเป็น

การลบล้าง MediaLibraryService.updateNotification() จะช่วยให้แอปเป็นเจ้าของสิทธิ์ในการโพสต์การแจ้งเตือนและเริ่ม/หยุดบริการที่ทำงานอยู่เบื้องหน้าได้อย่างเต็มที่ตามต้องการ

ย้ายข้อมูลโค้ดไคลเอ็นต์โดยใช้ MediaBrowser

เมื่อใช้ AndroidX Media3 MediaBrowser จะใช้อินเทอร์เฟซ MediaController/Player และใช้เพื่อควบคุมการเล่นสื่อได้นอกเหนือจากการเรียกดูคลังสื่อ หากคุณต้องสร้าง MediaBrowserCompat และ MediaControllerCompat ในโลกเดิม คุณสามารถทำแบบเดียวกันได้โดยใช้เพียง MediaBrowser ใน Media3

คุณสามารถสร้าง MediaBrowser และรอให้มีการเชื่อมต่อกับบริการได้โดยทำดังนี้

scope.launch {
  val sessionToken = SessionToken(context, ComponentName(context, "MusicService"))
  browser =
    MediaBrowser.Builder(context, sessionToken)
      .setListener(BrowserListener())
      .buildAsync()
      .await()
}
MigrationGuide.kt

SessionToken sessionToken =
    new SessionToken(context, new ComponentName(context, "MusicService"));
ListenableFuture<MediaBrowser> browserFuture =
    new MediaBrowser.Builder(context, sessionToken)
        .setListener(new BrowserListener())
        .buildAsync();
MigrationGuide.java

ดูควบคุมการเล่นในเซสชันสื่อเพื่อดูวิธีสร้าง MediaController สำหรับควบคุมการเล่นในเบื้องหลัง

ขั้นตอนเพิ่มเติมและการล้างข้อมูล

ข้อผิดพลาดของ API ที่ไม่เสถียร

หลังจากย้ายข้อมูลไปยัง Media3 คุณอาจเห็นข้อผิดพลาด Lint เกี่ยวกับการใช้งาน API ที่ไม่เสถียร API เหล่านี้ปลอดภัยต่อการใช้งาน และข้อผิดพลาดของ Lint เป็นผลพลอยได้จากการรับประกันความเข้ากันได้ของไบนารีใหม่ของเรา หากคุณไม่ต้องการความเข้ากันได้ของไบนารีที่เข้มงวด คุณสามารถระงับข้อผิดพลาดเหล่านี้ได้อย่างปลอดภัยด้วยคำอธิบายประกอบ @OptIn

ฉากหลัง

ทั้ง ExoPlayer v1 และ v2 ไม่ได้ให้การรับประกันที่เข้มงวดเกี่ยวกับความเข้ากันได้แบบไบนารีของไลบรารีระหว่างเวอร์ชันต่อๆ มา แพลตฟอร์ม ExoPlayer API มีขนาดใหญ่มากตามการออกแบบ เพื่อให้แอปปรับแต่งการเล่นได้เกือบทุกด้าน ExoPlayer เวอร์ชันต่อๆ มาอาจมีการเปลี่ยนชื่อสัญลักษณ์หรือการเปลี่ยนแปลงที่ส่งผลกับส่วนอื่นในระบบเป็นครั้งคราว (เช่น เมธอดใหม่ที่จำเป็นในอินเทอร์เฟซ) ในกรณีส่วนใหญ่ การหยุดทำงานเหล่านี้ได้รับการบรรเทาลงด้วยการเปิดตัวสัญลักษณ์ใหม่ควบคู่ไปกับการเลิกใช้งานสัญลักษณ์เก่าในบางเวอร์ชัน เพื่อให้นักพัฒนาซอฟต์แวร์มีเวลาในการย้ายข้อมูลการใช้งาน แต่ก็ไม่สามารถทำได้เสมอไป

การเปลี่ยนแปลงที่ส่งผลกับส่วนอื่นในระบบเหล่านี้ส่งผลให้เกิดปัญหา 2 ประการสำหรับผู้ใช้ไลบรารี ExoPlayer v1 และ v2 ดังนี้

1. การอัปเกรดจาก ExoPlayer เวอร์ชันหนึ่งเป็นอีกเวอร์ชันหนึ่งอาจทำให้โค้ดหยุดคอมไพล์
2. แอปที่ใช้ ExoPlayer ทั้งโดยตรงและผ่านไลบรารีสื่อกลางต้องตรวจสอบว่าทรัพยากร Dependency ทั้ง 2 รายการเป็นเวอร์ชันเดียวกัน ไม่เช่นนั้นความไม่เข้ากันของไบนารีอาจส่งผลให้เกิดข้อขัดข้องขณะรันไทม์

การปรับปรุงใน Media3

Media3 รับประกันความเข้ากันได้ของไบนารีสำหรับชุดย่อยของแพลตฟอร์ม API ส่วนที่ไม่รับประกันความเข้ากันได้ของไบนารีจะทำเครื่องหมายด้วย @UnstableApi เพื่อให้เห็นความแตกต่างนี้อย่างชัดเจน การใช้สัญลักษณ์ API ที่ไม่เสถียรจะสร้างข้อผิดพลาด Lint เว้นแต่จะมีการกำกับเนื้อหาด้วย @OptIn

หลังจากย้ายข้อมูลจาก ExoPlayer v2 ไปยัง Media3 คุณอาจเห็นข้อผิดพลาด Lint ของ API ที่ไม่เสถียรจำนวนมาก ซึ่งอาจทำให้ดูเหมือนว่า Media3 "มีความเสถียรน้อยกว่า" ExoPlayer v2 ซึ่งไม่เป็นความจริง ส่วนที่ "ไม่เสถียร" ของ Media3 API มีความเสถียรในระดับเดียวกับทั้ง API ของ ExoPlayer v2 และการรับประกันความเสถียรของ API ของ Media3 ไม่มีใน ExoPlayer v2 เลย ความแตกต่างก็คือตอนนี้ข้อผิดพลาดของ Lint จะแจ้งเตือนคุณเกี่ยวกับความเสถียรในระดับต่างๆ

จัดการข้อผิดพลาด Lint ของ API ที่ไม่เสถียร

ดูรายละเอียดเกี่ยวกับวิธีใส่คำอธิบายประกอบการใช้งาน Java และ Kotlin ของ API ที่ไม่เสถียรด้วย @OptIn ได้ที่ส่วนการแก้ปัญหาเกี่ยวกับข้อผิดพลาดของ Lint เหล่านี้

API ที่เลิกใช้งานแล้ว

คุณอาจสังเกตเห็นว่าการเรียก API ที่เลิกใช้งานแล้วจะถูกขีดฆ่าใน Android Studio เราขอแนะนำให้แทนที่การเรียกดังกล่าวด้วยทางเลือกที่เหมาะสม วางเมาส์เหนือสัญลักษณ์เพื่อดู JavaDoc ที่บอกว่าควรใช้ API ใดแทน

ตัวอย่างโค้ดและแอปสาธิต

• แอปเดโมเซสชัน AndroidX Media3 (อุปกรณ์เคลื่อนที่และ WearOS)
  • การทำงานที่กำหนดเอง
  • การแจ้งเตือน UI ของระบบ, MediaButton/BT
  • ตัวควบคุมการเล่นของ Google Assistant
• UAMP: Android Media Player (branch media3) (อุปกรณ์เคลื่อนที่, AutomotiveOS)
  • การแจ้งเตือน UI ของระบบ, MediaButton/BT, การกลับมาเล่นต่อ
  • ตัวควบคุมการเล่นของ Google Assistant/WearOS
  • AutomotiveOS: คำสั่งและการลงชื่อเข้าใช้ที่กำหนดเอง