แอปพลิเคชันการสาธิต ExoPlayer

แอปเดโมหลักของ ExoPlayer มีวัตถุประสงค์หลัก 2 ประการ ได้แก่

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

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

กำลังรับรหัส

ดูซอร์สโค้ดสำหรับแอปเดโมหลักได้ในโฟลเดอร์ demos/main ของโปรเจ็กต์ GitHub หากยังไม่ได้ดำเนินการ ให้โคลนโปรเจ็กต์ลงในไดเรกทอรีในเครื่องโดยทำดังนี้

git clone https://github.com/androidx/media.git

จากนั้นเปิดโปรเจ็กต์ใน Android Studio คุณควรเห็นสิ่งต่อไปนี้ในมุมมองโปรเจ็กต์ Android (โฟลเดอร์ที่เกี่ยวข้องของแอปเดโมได้รับการขยายแล้ว)

โปรเจ็กต์ใน Android Studio
รูปที่ 1 โปรเจ็กต์ใน Android Studio

การคอมไพล์และการเรียกใช้

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

SampleChooserActivity และ PlayerActivity ในแอปสาธิต ExoPlayer
รูปที่ 2 SampleChooserActivity และ PlayerActivity

แอปสาธิตจะแสดงรายการตัวอย่าง (SampleChooserActivity) การเลือกตัวอย่างจะเปิดกิจกรรมที่ 2 (PlayerActivity) สำหรับการเล่น เดโมนี้มีตัวควบคุมการเล่นและฟังก์ชันการเลือกแทร็ก นอกจากนี้ยังใช้คลาสยูทิลิตี EventLogger ของ ExoPlayer เพื่อแสดงข้อมูลการแก้ไขข้อบกพร่องที่เป็นประโยชน์ไปยังบันทึกของระบบด้วย คุณสามารถดูการบันทึกนี้ (พร้อมกับการบันทึกระดับข้อผิดพลาดสำหรับแท็กอื่นๆ) ได้โดยใช้คำสั่งต่อไปนี้

adb logcat EventLogger:V *:E

การเปิดใช้ตัวถอดรหัสที่รวมมาด้วย

ExoPlayer มีส่วนขยายจำนวนมากที่อนุญาตให้ใช้ตัวถอดรหัสซอฟต์แวร์ที่รวมมาด้วย ซึ่งรวมถึง AV1, VP9, Opus, FLAC และ FFmpeg (เสียงเท่านั้น) คุณสามารถสร้างแอปสาธิตให้รวมและใช้ส่วนขยายเหล่านี้ได้ดังนี้

  1. สร้างส่วนขยายแต่ละรายการที่ต้องการรวมไว้ โปรดทราบว่าขั้นตอนนี้เป็นกระบวนการที่ต้องดำเนินการด้วยตนเอง โปรดดูวิธีการในไฟล์ README.md ในส่วนขยายแต่ละรายการ
  2. ในมุมมองตัวแปรบิลด์ของ Android Studio ให้ตั้งค่าตัวแปรบิลด์สำหรับโมดูลเดโมเป็น withDecoderExtensionsDebug หรือ withDecoderExtensionsRelease ดังที่แสดงในรูปภาพต่อไปนี้

    การเลือกตัวแปรบิลด์ `withDecoderExtensionsDebug` ของเดโม

  3. คอมไพล์ ติดตั้ง และเรียกใช้การกำหนดค่า demo ตามปกติ

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

การเล่นเนื้อหาของคุณเอง

คุณเล่นเนื้อหาของตนเองในแอปสาธิตได้หลายวิธี

1. กำลังแก้ไข assets/media.exolist.json

ตัวอย่างที่แสดงในแอปเดโมจะโหลดจาก assets/media.exolist.json การแก้ไขไฟล์ JSON นี้จะช่วยให้เพิ่มและนำตัวอย่างออกจากแอปสาธิตได้ สคีมามีดังนี้ โดย [O] หมายถึงแอตทริบิวต์ที่ไม่บังคับ

[
  {
    "name": "Name of heading",
    "samples": [
      {
        "name": "Name of sample",
        "uri": "The URI of the sample",
        "extension": "[O] Sample type hint. Cannot be combined with mime_type. Values: mpd, ism, m3u8",
        "clip_start_position_ms": "[O] A start point to which the sample should be clipped, in milliseconds",
        "clip_end_position_ms": "[O] An end point from which the sample should be clipped, in milliseconds",
        "drm_scheme": "[O] Drm scheme if protected. Values: widevine, playready, clearkey",
        "drm_license_uri": "[O] URI of the license server if protected",
        "drm_force_default_license_uri": "[O] Whether to force use of "drm_license_uri" for key requests that include their own license URI",
        "drm_key_request_properties": "[O] Key request headers if protected",
        "drm_session_for_clear_content": "[O] Whether to attach a DRM session to clear video and audio tracks",
        "drm_multi_session": "[O] Enables key rotation if protected",
        "drm_force_software_crypto": "[O] Whether to force DRM to use the software crypto library regardless of the device's hardware crypto capability if supported by the DRM scheme",
        "mime_type": "[O] The MIME type of the sample. Cannot be combined with extension.",
        "subtitle_uri": "[O] The URI of a subtitle sidecar file",
        "subtitle_mime_type": "[O] The MIME type of subtitle_uri (required if subtitle_uri is set)",
        "subtitle_language": "[O] The BCP47 language code of the subtitle file (ignored if subtitle_uri is not set)",
        "ad_tag_uri": "[O] The URI of an ad tag to load via the IMA extension"
      },
      ...etc
    ]
  },
  ...etc
]

คุณระบุเพลย์ลิสต์ของตัวอย่างเพลงได้โดยใช้สคีมาต่อไปนี้

[
  {
    "name": "Name of heading",
    "samples": [
      {
        "name": "Name of playlist sample",
        "playlist": [
          {
            "uri": "The URI of the first sample in the playlist",
            "extension": "[O] Sample type hint. Cannot be combined with mime_type. Values: mpd, ism, m3u8",
            "clip_start_position_ms": "[O] A start point to which the sample should be clipped, in milliseconds",
            "clip_end_position_ms": "[O] An end point from which the sample should be clipped, in milliseconds",
            "drm_scheme": "[O] Drm scheme if protected. Values: widevine, playready, clearkey",
            "drm_license_uri": "[O] URI of the license server if protected",
            "drm_force_default_license_uri": "[O] Whether to force use of "drm_license_uri" for key requests that include their own license URI",
            "drm_key_request_properties": "[O] Key request headers if protected",
            "drm_session_for_clear_content": "[O] Whether to attach a DRM session to clear video and audio tracks",
            "drm_multi_session": "[O] Enables key rotation if protected",
            "drm_force_software_crypto": "[O] Whether to force DRM to use the software crypto library regardless of the device's hardware crypto capability if supported by the DRM scheme",
            "mime_type": "[O] The MIME type of the sample. Cannot be combined with extension.",
            "subtitle_uri": "[O] The URI of a subtitle sidecar file",
            "subtitle_mime_type": "[O] The MIME type of subtitle_uri (required if subtitle_uri is set)",
            "subtitle_language": "[O] The BCP47 language code of the subtitle file (ignored if subtitle_uri is not set)"
          },
          {
            "uri": "The URI of the second sample in the playlist",
            ...etc
          },
          ...etc
        ]
      },
      ...etc
    ]
  },
  ...etc
]

หากจำเป็น ระบบจะระบุส่วนหัวของคำขอคีย์เป็นออบเจ็กต์ที่มีแอตทริบิวต์สตริงสำหรับส่วนหัวแต่ละรายการ ดังนี้

"drm_key_request_properties": {
  "name1": "value1",
  "name2": "value2",
  ...etc
}

ในกิจกรรมตัวเลือกตัวอย่าง เมนูรายการเพิ่มเติมจะมีตัวเลือกสำหรับระบุว่าจะใช้ตัวถอดรหัสส่วนขยายหรือไม่

URI ของไฟล์ในเครื่องและข้อจำกัดของพื้นที่เก็บข้อมูลที่กำหนดขอบเขต

เมื่อระบุ URI ของไฟล์ในเครื่อง แอปสาธิตจะขอสิทธิ์เข้าถึงพื้นที่เก็บข้อมูลที่จำเป็นเพื่ออ่านไฟล์เหล่านี้ อย่างไรก็ตาม ตั้งแต่ Android 13 เป็นต้นไป คุณจะไม่สามารถโหลดไฟล์ที่กำหนดเองซึ่งไม่ได้ลงท้ายด้วยนามสกุลไฟล์สื่อทั่วไป (เช่น .mp4) หากต้องการโหลดไฟล์ดังกล่าว คุณสามารถวางไฟล์ไว้ในไดเรกทอรีพื้นที่เก็บข้อมูลเฉพาะของแอปสาธิตที่ไม่มีข้อจำกัดในการเข้าถึง ซึ่งโดยทั่วไปจะอยู่ที่ /sdcard/Android/data/androidx.media3.demo.main/files

2. กำลังโหลดไฟล์ exolist.json ภายนอก

แอปสาธิตสามารถโหลดไฟล์ JSON ภายนอกโดยใช้สคีมาก่อนหน้าและตั้งชื่อตามรูปแบบ *.exolist.json ตัวอย่างเช่น หากคุณโฮสต์ไฟล์ดังกล่าวที่ https://yourdomain.com/samples.exolist.json คุณจะเปิดไฟล์นั้นในแอปสาธิตได้โดยใช้คำสั่งต่อไปนี้

adb shell am start -a android.intent.action.VIEW \
    -d https://yourdomain.com/samples.exolist.json

การคลิกลิงก์ *.exolist.json (เช่น ในเบราว์เซอร์หรือโปรแกรมรับส่งอีเมล) บนอุปกรณ์ที่ติดตั้งแอปสาธิตไว้จะเปิดลิงก์นั้นในแอปสาธิตด้วย การโฮสต์ไฟล์ JSON *.exolist.json เป็นวิธีเผยแพร่เนื้อหาเพื่อให้ผู้อื่นลองใช้ในแอปสาธิต

3. การเริ่ม Intent

คุณสามารถใช้ Intent เพื่อข้ามรายการตัวอย่างและเปิดการเล่นโดยตรงได้ หากต้องการเล่นตัวอย่างเดียว ให้ตั้งค่าการดำเนินการของ Intent เป็น androidx.media3.demo.main.action.VIEW และตั้งค่า URI ข้อมูลเป็น URI ของตัวอย่างที่จะเล่น คุณสามารถเริ่ม Intent ดังกล่าวจากเทอร์มินัลได้โดยใช้คำสั่งต่อไปนี้

adb shell am start -a androidx.media3.demo.main.action.VIEW \
    -d https://yourdomain.com/sample.mp4

ส่วนเสริมที่ไม่บังคับซึ่งรองรับสำหรับ Intent ตัวอย่างรายการเดียวมีดังนี้

  • ตัวอย่างการกำหนดค่าเพิ่มเติม
    • mime_type [สตริง] ตัวอย่างคำแนะนำประเภท MIME เช่น application/dash+xml สำหรับเนื้อหา DASH
    • clip_start_position_ms [Long] จุดเริ่มต้นที่ควรตัดคลิปตัวอย่าง โดยมีหน่วยเป็นมิลลิวินาที
    • clip_end_position_ms [Long] ปลายทางที่ควรตัดคลิปตัวอย่าง มีหน่วยเป็นมิลลิวินาที
    • drm_scheme [สตริง] รูปแบบ DRM หากได้รับการคุ้มครอง ค่าที่ถูกต้องคือ widevine, playready และ clearkey นอกจากนี้ยังยอมรับ UUID ของรูปแบบ DRM ด้วย
    • drm_license_uri [สตริง] URI ของเซิร์ฟเวอร์ใบอนุญาตหากได้รับการปกป้อง
    • drm_force_default_license_uri [บูลีน] บังคับให้ใช้ drm_license_uri สำหรับคำขอคีย์ที่มี URI ใบอนุญาตของตนเองหรือไม่
    • drm_key_request_properties [อาร์เรย์สตริง] ส่วนหัวของคำขอคีย์ที่รวมเป็น name1, value1, name2, value2 ฯลฯ หากได้รับการปกป้อง
    • drm_session_for_clear_content [บูลีน] แนบเซสชัน DRM เพื่อล้างแทร็กวิดีโอและเสียงหรือไม่
    • drm_multi_session [บูลีน] เปิดใช้การหมุนเวียนคีย์หากได้รับการป้องกัน
    • drm_force_software_crypto [บูลีน] บังคับให้ DRM ใช้ไลบรารีการเข้ารหัสซอฟต์แวร์หรือไม่ โดยไม่คำนึงถึงความสามารถในการเข้ารหัสฮาร์ดแวร์ของอุปกรณ์ หากรูปแบบ DRM รองรับ
    • subtitle_uri [สตริง] URI ของไฟล์ช่วยเหลือของคำบรรยาย
    • subtitle_mime_type [สตริง] ประเภท MIME ของ subtitle_uri (ต้องระบุหากมีการตั้งค่า subtitle_uri)
    • subtitle_language [สตริง] รหัสภาษา BCP47 ของไฟล์คำบรรยาย (ระบบจะไม่สนใจหากไม่ได้ตั้งค่า subtitle_uri)
    • ad_tag_uri [สตริง] URI ของแท็กโฆษณาที่จะโหลดโดยใช้ส่วนขยาย IMA
    • prefer_extension_decoders [บูลีน] ตัวถอดรหัสส่วนขยายเป็นที่ต้องการมากกว่าตัวถอดรหัสแพลตฟอร์มหรือไม่

เมื่อใช้ adb shell am start เพื่อเริ่ม Intent คุณสามารถตั้งค่าสตริงเสริมที่ไม่บังคับได้ด้วย --es (เช่น --es extension mpd) ตั้งค่าบูลีนเสริมที่ไม่บังคับได้ด้วย --ez (เช่น --ez prefer_extension_decoders TRUE) ตั้งค่า Long เสริมที่ไม่บังคับได้ด้วย --el (เช่น --el clip_start_position_ms 5000) และตั้งค่าอาร์เรย์สตริงเสริมที่ไม่บังคับได้ด้วย --esa (เช่น --esa drm_key_request_properties name1,value1)

หากต้องการเล่นเพลย์ลิสต์ของตัวอย่าง ให้ตั้งค่าการดำเนินการของ Intent เป็น androidx.media3.demo.main.action.VIEW_LIST การกำหนดค่าตัวอย่าง จะยังคงเหมือนกับ androidx.media3.demo.main.action.VIEW ยกเว้นความแตกต่าง 2 ประการต่อไปนี้

  • คีย์ของส่วนเสริมควรมีขีดล่างและดัชนีแบบ 0-based ของตัวอย่างเป็นคำต่อท้าย ตัวอย่างเช่น extension_0 จะบอกใบ้ประเภทตัวอย่างสำหรับตัวอย่างแรก drm_scheme_1 จะตั้งค่ารูปแบบ DRM สำหรับตัวอย่างที่ 2
  • ระบบจะส่ง URI ของตัวอย่างเป็นข้อมูลเพิ่มเติมพร้อมคีย์ uri_<sample-index>

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

adb shell am start -a androidx.media3.demo.main.action.VIEW_LIST \
    --es uri_0 https://a.com/sample1.mp4 \
    --es uri_1 https://b.com/sample2.fake_mpd \
    --es extension_1 mpd