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

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

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

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

การรับรหัส

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

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

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

โปรเจ็กต์ใน Android Studio

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

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

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. 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",
        "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. 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",
            "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 ข้อมูลของตัวอย่างที่จะเล่น คุณสามารถเรียกใช้ 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 [แบบยาว] จุดสิ้นสุดที่ควรรวมตัวอย่างเป็นมิลลิวินาที
    • 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 [บูลีน] เปิดใช้การหมุนเวียนคีย์หากมีการป้องกัน
    • subtitle_uri [สตริง] URI ของไฟล์ช่วยเหลือของคำบรรยาย
    • subtitle_mime_type [สตริง] ประเภท MIME ของ subtitle_uri (ต้องระบุหากตั้งค่า subtitle_uri ไว้)
    • subtitle_language [สตริง] รหัสภาษา BCP47 ของไฟล์คำบรรยาย (ยกเว้นหากไม่ได้ตั้งค่า title_uri) ไว้)
    • ad_tag_uri [สตริง] URI ของแท็กโฆษณาที่จะโหลดโดยใช้ [ส่วนขยาย IMA][]
    • prefer_extension_decoders [บูลีน] ระบุว่าควรใช้โปรแกรมถอดรหัสส่วนขยายมากกว่าโปรแกรมถอดรหัสของแพลตฟอร์มหรือไม่

เมื่อใช้ adb shell am start เพื่อเรียกใช้ Intent คุณจะตั้งค่าสตริงเพิ่มเติมที่ไม่บังคับได้โดยใช้ --es (เช่น --es extension mpd) คุณสามารถตั้งค่าบูลีนเพิ่มเติม (ไม่บังคับ) ด้วย --ez (เช่น --ez prefer_extension_decoders TRUE) คุณสามารถตั้งค่าเสริมแบบยาวด้วย --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 ของตัวอย่าง เช่น 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