Ứng dụng minh hoạ ExoPlayer

Ứng dụng minh hoạ chính của ExoPlayer phục vụ 2 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. Để giúp bạn dễ dàng dùng thử ExoPlayer. Bạn có thể dùng ứng dụng minh họa để 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ạ, cũng như 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 của ứng dụng minh họa chính trong thư mục demos/main của dự án GitHub của chúng tôi. Nếu bạn chưa làm việc này, 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 những 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 một 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 trong mục Thiết bị được hỗ trợ và đảm bảo rằng thiết bị ảo của bạn sử dụng một 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). Khi bạn chọn một mẫu, ứng dụng sẽ mở một hoạt động thứ hai (PlayerActivity) để phát. Bản minh hoạ có các nút điều khiển phát và chức năng chọn bản nhạc. Thư viện 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 các 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 thành phần mở rộng mà bạn muốn thêm. 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 để xem hướng dẫn.

  2. Trong chế độ xem 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 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 các bộ giải mã tiện ích, như mô tả trong các phần sau.

Phát nội dung của riêng 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 tệp 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á các mẫu khỏi ứng dụng minh hoạ. Giản đồ có dạng 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",
        "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ác đoạn nhạc mẫu 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",
            "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 đề 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 chọn mẫu, trình đơn mục bổ sung có các lựa chọn để chỉ định xem có nên ư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 cần thiết vào bộ nhớ để đọ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 là đ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ạ mà không có 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 một 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 cách sử dụ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

Khi 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ở ứng dụng minh hoạ. Do đó, việc lưu trữ tệp JSON *.exolist.json là một cách đơn giản để 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 một ý định

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

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

  • Các cấu hình mẫu bổ sung:
    • mime_type [String] 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 [Long] Điểm cuối mà từ đó mẫu sẽ được cắt, tính bằng mili giây.
    • drm_scheme [String] Lược đồ DRM nếu được bảo vệ. Các giá trị hợp lệ là widevine, playready và clearkey. UUID của lược đồ DRM cũng được chấp nhận.
    • drm_license_uri [String] URI của máy chủ cấp phép nếu được bảo vệ.
    • drm_force_default_license_uri [Boolean] Có bắt 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] Các tiêu đề yêu cầu khoá đượ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 một phiên DRM vào các bản âm thanh và video không được mã hoá 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 [String] URI của tệp phụ đề trợ giúp.
    • subtitle_mime_type [String] Loại MIME của subtitle_uri (bắt buộc nếu bạn đặt subtitle_uri).
    • subtitle_language [String] 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 [String] URI của thẻ quảng cáo cần tải bằng [tiện ích IMA][].
    • prefer_extension_decoders [Boolean] Có ưu tiên bộ giải mã tiện ích hơn bộ giải mã nền tảng hay không.

Khi 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 số nguyên dài 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 một danh sách phát gồm các đoạn mẫu, hãy đặt thao tác của ý định thành androidx.media3.demo.main.action.VIEW_LIST. Các phần bổ sung trong cấu hình mẫu vẫn giữ nguyên như đối với androidx.media3.demo.main.action.VIEW, ngoại trừ 2 đ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 giản đồ 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 thiết bị đầu cuối để phát một danh sách phát có 2 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