Ứ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ụ đầy đủ về cách sử dụng ExoPlayer. Bạn có thể 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. Để cho phép bạn 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 bạn, 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ạ, đồng thời 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.

Lấy mã

Bạn có thể tìm thấy mã nguồn của ứng dụng minh hoạ chính trong thư mục demos/main của dự án GitHub. Nếu bạn chưa thực hiện, hãy sao chép 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 liên quan của ứng dụng minh hoạ đã được mở rộng):

Dự án trong Android Studio
Hình 1. 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 đã kết nối. Bạn nên sử dụng thiết bị thực nếu có thể. Nếu bạn muốn sử dụng trình mô phỏng, hãy đọc phần trình mô phỏng trong 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 trong ứng dụng minh hoạ ExoPlayer
Hình 2. SampleChooserActivity và PlayerActivity.

Ứng dụng minh hoạ trình bày danh sách các mẫu (SampleChooserActivity). Khi chọn một mẫu, bạn sẽ mở ra hoạt động thứ hai (PlayerActivity) để phát. Bản minh hoạ có bộ điều khiển chế độ 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ể xem nhật ký này (cùng với nhật ký cấp 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ạ để thêm 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. Hãy tham khảo tệp README.md trong mỗi tiện ích để biết hướng dẫn.
  2. Trong chế độ xem 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ư trong hình sau.

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

  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 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 nên ưu tiên bộ giải mã tiện ích, 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. Đang 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. 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
]

Bạn có thể chỉ định danh sách phát của đoạn nhạc bằ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. 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
]

Nếu cần, các tiêu đề của yêu cầu chính sẽ đượ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 của 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 quy định 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 cần thiết vào bộ nhớ để đọc các tệp này. Tuy nhiên, kể từ Android 13, bạn không thể tải các tệp tuỳ ý không kết thúc bằng đuôi tệp nội dung nghe nhìn thông thường (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 lưu trữ cụ thể của ứng dụng minh hoạ không có quy định hạn chế về quyền truy cập. Tệp 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ước đó 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:

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

Khi bạn 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 một thiết bị đã cài đặt ứng dụng minh hoạ, đường liên kết đó cũng sẽ mở trong ứng dụng minh hoạ. Việc lưu trữ tệp JSON *.exolist.json cung cấp một cách để phân phối nội dung cho người khác dùng thử trong ứng dụng minh hoạ.

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

Bạn có thể dùng ý định để bỏ qua danh sách mẫu và phát trực tiếp. Để phát một mẫu, hãy đặt hành động của ý định thành androidx.media3.demo.main.action.VIEW và đặt 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

Các dữ liệu bổ sung không bắt buộc được hỗ trợ cho một ý định mẫu là:

  • Cấu hình mẫu bổ sung:
    • mime_type [Chuỗi] Gợi ý về loại MIME của 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 bớt, tính bằng mili giây.
    • clip_end_position_ms [Long] Điểm cuối mà đoạn nhạc sẽ được cắt, tính bằng mili giây.
    • drm_scheme [Chuỗi] Cơ chế DRM nếu được bảo vệ. Các giá trị hợp lệ là widevine, playready và clearkey. Chúng tôi cũng chấp nhận UUID của lược đồ DRM.
    • 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] 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 riêng hay không.
    • drm_key_request_properties [Mảng chuỗi] Tiêu đề của yêu cầu chính được đóng gói dưới dạng name1, value1, name2, value2, v.v. nếu được bảo vệ.
    • drm_session_for_clear_content [Boolean] 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ệ.
    • drm_force_software_crypto [Boolean] Có buộc DRM sử dụng thư viện mã hoá phần mềm hay không, bất kể khả năng mã hoá phần cứng của thiết bị nếu được lược đồ DRM hỗ trợ.
    • subtitle_uri [Chuỗi] URI của tệp phụ đề trợ giúp.
    • subtitle_mime_type [Chuỗi] Loại MIME của subtitle_uri (bắt buộc nếu bạn đặt subtitle_uri).
    • subtitle_language [Chuỗi] Mã ngôn ngữ BCP47 của tệp phụ đề (bị bỏ qua nếu bạn không đặt subtitle_uri).
    • ad_tag_uri [Chuỗi] URI của thẻ quảng cáo cần tải bằng tiện ích IMA.
    • prefer_extension_decoders [Boolean] Liệu bộ giải mã tiện ích có được ưu tiên hơn bộ 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 long bổ sung không bắt buộc bằng --el (ví dụ: --el clip_start_position_ms 5000). Bạn có thể đặt một mảng chuỗi bổ sung 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 mẫu, hãy đặt hành động của ý định thành androidx.media3.demo.main.action.VIEW_LIST. Các thành phần bổ sung của cấu hình mẫu vẫn giữ nguyên như đối với androidx.media3.demo.main.action.VIEW, ngoại trừ hai điểm khác biệt:

  • Khoá của các giá trị 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 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 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