คำแนะนำในการย้ายข้อมูล 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 เป็นเวอร์ชันล่าสุดที่ทำงานร่วมกับการอ้างอิงที่อัปเดตซึ่งกล่าวถึงก่อนหน้านี้ได้ เช่น

     • เวอร์ชันปลั๊กอิน 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

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

คำเตือน: สคริปต์อาจทำให้ไฟล์บิลด์ Gradle อยู่ในสถานะที่ใช้งานไม่ได้หากการประกาศทรัพยากร Dependency ใช้ตัวแปรหรือเทคนิคขั้นสูง

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
   

หมายเหตุ: คุณสามารถใช้พารามิเตอร์ -x เพื่อยกเว้นเส้นทางไม่ให้ถูกเลือกเพื่อทำการเปลี่ยนแปลงได้

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

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

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

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 ส่งผ่านเพลเยอร์เพื่อสร้างเครื่องมือสร้างเซสชัน

   หมายเหตุ: ในกรณีที่แอปใช้เพลเยอร์อื่นที่ไม่ใช่ ExoPlayer คุณต้องใช้การติดตั้งใช้งาน Player ที่กำหนดเองซึ่งคุณสามารถส่งไปยัง MediaSession ที่รวมเพลเยอร์ของคุณไว้ได้ เราจะให้คำแนะนำเพิ่มเติมเกี่ยวกับการติดตั้งใช้งาน Player ขั้นต่ำที่ทำงานร่วมกับการติดตั้งใช้งานเซสชันสื่อ

   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

   หมายเหตุ: คุณสามารถขัดจังหวะการเล่นใดๆ ใน Player ได้โดยรวมไว้ใน ForwardingSimpleBasePlayer(player) ดูข้อมูลเพิ่มเติมเกี่ยวกับ ForwardingSimpleBasePlayer

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

   หมายเหตุ: คุณต้องปล่อยเซสชันสื่อก่อนสร้างเซสชันใหม่ที่มีรหัสเดียวกัน Media3 จะแสดงข้อยกเว้นหากแอปทำให้เกิดการรั่วไหลของอินสแตนซ์เซสชัน

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

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

MediaSessionConnector	AndroidX Media3
CustomActionProvider	MediaSession.Callback.onCustomCommand()/ MediaSession.setMediaButtonPreferences()
PlaybackPreparer	MediaSession.Callback.onAddMediaItems() (prepare() มีการเรียกใช้ภายใน)
QueueNavigator	ForwardingSimpleBasePlayer
QueueEditor	MediaSession.Callback.onAddMediaItems()
RatingCallback	MediaSession.Callback.onSetRating()
PlayerNotificationManager	DefaultMediaNotificationProvider/ MediaNotification.Provider

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

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

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

รูปที่ 1: ภาพรวมคอมโพเนนต์ของแอปสื่อ

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(): Callback 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

หมายเหตุ: แอปที่กำหนดเป้าหมายเป็น API ระดับ 28 ขึ้นไปจะยังคงต้องขอสิทธิ์ FOREGROUND_SERVICE

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

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

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

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

หมายเหตุ: ผู้ใช้ Kotlin สามารถใช้ kotlin-coroutines-guava หรือ androidx.concurrent ในไฟล์ build.gradle เพื่อเพิ่มเมธอดส่วนขยาย await ลงใน ListenableFuture ได้ ซึ่งทำให้ API ของ MediaBrowser เหมาะสมกับเมธอด suspend มากขึ้น อย่างเป็นธรรมชาติ

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

Kotlin

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

Java

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

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

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

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

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

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

ฉากหลัง

ทั้ง ExoPlayer v1 และ v2 ไม่ได้ให้ความเข้ากันได้แบบไบนารีที่เข้มงวดของไลบรารีระหว่างเวอร์ชันต่อๆ มา แพลตฟอร์ม API ของ ExoPlayer มีขนาดใหญ่มากโดยการออกแบบ เพื่อให้แอปปรับแต่งการเล่นได้เกือบทุกด้าน 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 มีความเสถียรในระดับเดียวกับทั้งแพลตฟอร์ม ExoPlayer v2 API และความเข้ากันได้แบบไบนารีของแพลตฟอร์ม Media3 API ที่เสถียรนั้นไม่มีใน ExoPlayer v2 เลย ความแตกต่างคือตอนนี้ข้อผิดพลาด Lint จะแจ้งเตือนคุณเกี่ยวกับความเสถียรในระดับต่างๆ

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

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

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

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

รูปที่ 3: เคล็ดลับเครื่องมือ JavaDoc ใน Android Studio แนะนำทางเลือกสำหรับสัญลักษณ์ที่เลิกใช้งานแล้ว

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

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