Ứng dụng minh hoạ ExoPlayer

Ứng dụng minh hoạ chính của ExoPlayer phục vụ hai mục đích chính:

  1. Để cung cấp một ví dụ tương đối đơn giản nhưng đầy đủ tính năng về cách sử dụng ExoPlayer. Bạn có thể sử dụng ứng dụng minh hoạ làm điểm xuất phát thuận tiện để phát triển ứng dụng của riêng mình.
  2. Để dễ dàng dùng thử ExoPlayer. Bạn có thể dùng ứng dụng minh hoạ để kiểm thử việc phát nội dung của riêng mình ngoài các mẫu có sẵn.

Trang này mô tả cách tải, biên dịch và chạy ứng dụng minh hoạ. Trang này cũng mô tả cách sử dụng ứng dụng này để phát nội dung nghe nhìn của riêng bạn.

Nhận mã

Bạn có thể tìm thấy mã nguồn cho ứng dụng minh hoạ chính trong thư mục demos/main của dự án GitHub. Nếu bạn chưa làm như vậy, hãy nhân bản dự án vào một thư mục cục bộ:

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

Tiếp theo, hãy mở dự án trong Android Studio. Bạn sẽ thấy nội dung sau trong chế độ xem Dự án Android (các thư mục có liên quan của ứng dụng minh hoạ đã được mở rộng):

Dự án trong Android Studio

Biên dịch và chạy

Để biên dịch và chạy ứng dụng minh hoạ, hãy chọn và chạy cấu hình demo trong Android Studio. Ứng dụng minh hoạ sẽ cài đặt và chạy trên một thiết bị Android được kết nối. Bạn nên sử dụng thiết bị thực tế nếu có thể. Nếu bạn muốn sử dụng trình mô phỏng, vui lòng đọc phần trình mô phỏng của Thiết bị được hỗ trợ và đảm bảo rằng Thiết bị ảo của bạn sử dụng hình ảnh hệ thống có cấp độ API tối thiểu là 23.

SampleChooserActivity và PlayerActivity

Ứng dụng minh hoạ trình bày danh sách các mẫu (SampleChooserActivity). Việc chọn một mẫu sẽ mở một hoạt động thứ hai (PlayerActivity) để phát. Bản minh hoạ này có các nút điều khiển phát và chức năng chọn bản nhạc. Lớp này cũng sử dụng lớp tiện ích EventLogger của ExoPlayer để xuất thông tin gỡ lỗi hữu ích vào nhật ký hệ thống. Bạn có thể dùng lệnh để xem nhật ký này (cùng với nhật ký mức lỗi cho các thẻ khác) bằng lệnh:

adb logcat EventLogger:V *:E

Bật bộ giải mã đi kèm

ExoPlayer có một số tiện ích cho phép sử dụng bộ giải mã phần mềm đi kèm, bao gồm AV1, VP9, Opus, FLAC và FFmpeg (chỉ âm thanh). Bạn có thể tạo ứng dụng minh hoạ để đưa vào và sử dụng các tiện ích này như sau:

  1. Tạo từng tiện ích mà bạn muốn đưa vào. Xin lưu ý rằng đây là một quy trình thủ công. Tham khảo tệp README.md trong mỗi tiện ích để được hướng dẫn.

  2. Trong khung hiển thị Build Variants (Biến thể bản dựng) của Android Studio, hãy đặt biến thể bản dựng cho mô-đun minh hoạ thành withDecoderExtensionsDebug hoặc withDecoderExtensionsRelease như minh hoạ trong hình sau.

    Chọn biến thể bản dựng `withDecoderExtensionsDebug` của bản minh hoạ

  3. Biên dịch, cài đặt và chạy cấu hình demo như bình thường.

Theo mặc định, bộ giải mã tiện ích sẽ chỉ được sử dụng nếu không có bộ giải mã nền tảng phù hợp. Bạn có thể chỉ định rằng trình giải mã tiện ích sẽ được ưu tiên, như mô tả trong các phần sau.

Phát nội dung của chính bạn

Có nhiều cách để phát nội dung của riêng bạn trong ứng dụng minh hoạ.

1. Chỉnh sửa assets/media.exolist.json

Các mẫu được liệt kê trong ứng dụng minh hoạ được tải từ assets/media.exolist.json. Bằng cách chỉnh sửa tệp JSON này, bạn có thể thêm và xoá mẫu khỏi ứng dụng minh hoạ. Giản đồ như sau, trong đó [O] cho biết thuộc tính không bắt buộc.

[
  {
    "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
]

Bạn có thể chỉ định danh sách phát gồm các mẫu bằng cách sử dụng giản đồ:

[
  {
    "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
]

Nếu cần, tiêu đề yêu cầu chính được chỉ định dưới dạng một đối tượng chứa thuộc tính chuỗi cho mỗi tiêu đề:

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

Trong hoạt động bộ chọn mẫu, trình đơn mục bổ sung chứa các tuỳ chọn để chỉ định xem có ưu tiên bộ giải mã tiện ích hay không.

URI tệp cục bộ và các hạn chế về bộ nhớ có giới hạn

Khi chỉ định URI tệp cục bộ, ứng dụng minh hoạ sẽ yêu cầu các quyền truy cập bộ nhớ cần thiết để đọc các tệp này. Tuy nhiên, từ Android 13, bạn không thể tải các tệp tuỳ ý không có đuôi tệp nội dung nghe nhìn thông thường (chẳng hạn như .mp4). Nếu cần tải một tệp như vậy, bạn có thể đặt tệp đó vào thư mục bộ nhớ cụ thể của ứng dụng minh hoạ không có quy định hạn chế về quyền truy cập. Thư mục này thường nằm ở /sdcard/Android/data/androidx.media3.demo.main/files.

2. Tải tệp exolist.json bên ngoài

Ứng dụng minh hoạ có thể tải các tệp JSON bên ngoài bằng giản đồ ở trên và được đặt tên theo quy ước *.exolist.json. Ví dụ: nếu lưu trữ một tệp như vậy tại https://yourdomain.com/samples.exolist.json, bạn có thể mở tệp đó trong ứng dụng minh hoạ bằng cách sử dụng:

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

Thao tác nhấp vào một đường liên kết *.exolist.json (ví dụ: trong trình duyệt hoặc ứng dụng email) trên thiết bị đã cài đặt ứng dụng minh hoạ cũng sẽ mở đường liên kết đó trong ứng dụng minh hoạ. Do đó, việc lưu trữ tệp JSON *.exolist.json mang đến một cách đơn giản để phân phối nội dung để những người khác dùng thử trong ứng dụng minh hoạ.

3. Kích hoạt ý định

Bạn có thể sử dụng ý định để bỏ qua danh sách mẫu và trực tiếp phát. Để phát một mẫu, hãy đặt hành động của ý định thành androidx.media3.demo.main.action.VIEW và URI dữ liệu của ý định thành URI của mẫu cần phát. Bạn có thể kích hoạt ý định như vậy từ thiết bị đầu cuối bằng cách sử dụng:

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

Dưới đây là các thành phần bổ sung không bắt buộc được hỗ trợ cho một ý định mẫu:

  • Thông tin bổ sung về cấu hình mẫu:
    • mime_type [Chuỗi] Gợi ý về loại MIME mẫu. Ví dụ: application/dash+xml cho nội dung DASH.
    • clip_start_position_ms [Long] Điểm bắt đầu mà mẫu sẽ được cắt, tính bằng mili giây.
    • clip_end_position_ms [Dài] Điểm cuối mà mẫu sẽ được cắt, tính bằng mili giây.
    • drm_scheme [Chuỗi] Lược đồ DRM nếu được bảo vệ. Các giá trị hợp lệ là widevine, playready và clearkey. UUID của giao thức DRM cũng được chấp nhận.
    • drm_license_uri [Chuỗi] URI của máy chủ cấp phép nếu được bảo vệ.
    • drm_force_default_license_uri [Boolean] Liệu có buộc sử dụng drm_license_uri cho các yêu cầu khoá có chứa URI giấy phép của riêng chúng hay không.
    • drm_key_request_properties [Mảng chuỗi] Các tiêu đề yêu cầu khoá được đóng gói dưới dạng tên1, giá trị1, tên2, giá trị2, v.v. nếu được bảo vệ.
    • drm_session_for_clear_content [Boolean] Liệu có đính kèm phiên DRM để xoá các bản âm thanh và video hay không.
    • drm_multi_session [Boolean] Bật tính năng xoay vòng khoá nếu được bảo vệ.
    • subtitle_uri [Chuỗi] URI của tệp phụ đề đi kèm.
    • subtitle_mime_type [Chuỗi] Loại MIME của subtitle_uri (bắt buộc nếu bạn đã đặt Subtitles_uri).
    • subtitle_language [Chuỗi] Mã ngôn ngữ BCP47 của tệp phụ đề (bị bỏ qua nếu không đặt subtitle_uri).
    • ad_tag_uri [Chuỗi] URI của thẻ quảng cáo cần tải bằng [phần mở rộng IMA][].
    • prefer_extension_decoders [Boolean] Liệu trình giải mã tiện ích có được ưu tiên hơn trình giải mã nền tảng hay không.

Khi sử dụng adb shell am start để kích hoạt một ý định, bạn có thể đặt một chuỗi bổ sung không bắt buộc bằng --es (ví dụ: --es extension mpd). Bạn có thể đặt một boolean bổ sung không bắt buộc bằng --ez (ví dụ: --ez prefer_extension_decoders TRUE). Bạn có thể đặt một giá trị bổ sung dài không bắt buộc bằng --el (ví dụ: --el clip_start_position_ms 5000). Bạn có thể đặt thêm một mảng chuỗi không bắt buộc bằng --esa (ví dụ: --esa drm_key_request_properties name1,value1).

Để phát danh sách phát gồm các đoạn nhạc mẫu, hãy đặt hành động của ý định thành androidx.media3.demo.main.action.VIEW_LIST. Các tuỳ chọn cấu hình mẫu vẫn giống như đối với androidx.media3.demo.main.action.VIEW, ngoại trừ hai điểm khác biệt:

  • Khoá của phần bổ sung phải có dấu gạch dưới và chỉ mục dựa trên 0 của mẫu làm hậu tố. Ví dụ: extension_0 sẽ gợi ý loại mẫu cho mẫu đầu tiên. drm_scheme_1 sẽ đặt lược đồ DRM cho mẫu thứ hai.
  • URI của mẫu được truyền dưới dạng dữ liệu bổ sung có khoá uri_<sample-index>.

Các thành phần bổ sung khác không phụ thuộc vào mẫu sẽ không thay đổi. Ví dụ: bạn có thể chạy lệnh sau trong dòng lệnh để phát một danh sách phát có hai mục, ghi đè phần mở rộng của mục thứ hai:

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