Ứ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. Đây là một ví dụ tương đối đơn giản nhưng có đầ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ể sử dụng ứng dụng minh hoạ để kiểm thử việc phát nội dung của chính mình ngoài các mẫu đi kèm.

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 đó để phát nội dung nghe nhìn của riêng bạn.

Lấy mã nguồn

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. Hãy sao chép dự án vào một thư mục cục bộ (nếu bạn chưa làm):

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ư sau trong khung hiển thị 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

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 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ác 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ạ sẽ đưa ra danh sách các mẫu (SampleChooserActivity). Khi bạn chọn một mẫu, hoạt động thứ hai (PlayerActivity) sẽ mở ra để phát. Bản minh hoạ có các bộ điều khiển chế độ phát và chức năng chọn bản nhạc. API 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ạ để bao gồm và sử dụng các tiện ích này như sau:

  1. Tạo từng phần mở rộng 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 từng tiện ích để biết 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" 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 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 bộ giải mã tiện ích nên được ưu tiên, 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 assets/media.exolist.json

Các mẫu 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 đồ như sau, trong đó [O] chỉ ra mộ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 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. 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, các tiêu đề của yêu cầu khoá sẽ được chỉ định dưới dạng một đối tượng chứa thuộc tính chuỗi cho từng tiêu đề:

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

Trong hoạt động của trình 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 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 kết thúc bằng một đuôi tệp đa phương tiệ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ó giới hạn truy cập. Trang 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

Việc nhấp vào đườ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 sẽ 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 ý định

Bạn có thể sử dụng ý định để bỏ qua danh sách mẫu và khởi chạy trực tiếp trong quá trình phát. Để 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 thao tác của mẫu để phát. Một ý định như vậy có thể được kích hoạt 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 duy nhất là:

  • Ví dụ về phần bổ sung cấu hình:
    • mime_type [Chuỗi] Gợi ý loại MIME mẫu. Ví dụ: application/dash+xml cho nội dung DASH.
    • clip_start_position_ms [Dài] Đ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à từ đó 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. Mã nhận dạng duy nhất (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 chính có URI giấy phép riêng hay không.
    • drm_key_request_properties [Mảng chuỗi] Các tiêu đề của 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] Liệu có đính kèm phiên DRM để xoá video và bản âm thanh hay không.
    • drm_multi_session [Boolean] Bật tính năng xoay khoá nếu được bảo vệ.
    • subtitle_uri [Chuỗi] URI của một tệp trợ giúp phụ đề.
    • subtitle_mime_type [Chuỗi] Loại MIME của subtitle_uri (bắt buộc nếu bạn đặt phụ đề phụ).
    • subtitle_language [Chuỗi] Mã ngôn ngữ BCP47 của tệp phụ đề (bỏ qua nếu chưa đặt phụ đề).
    • 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 bộ giải mã tiện ích có được ưu tiên hơn các bộ giải mã nền tảng hay không.

Khi sử dụng adb shell am start để kích hoạt ý định, bạn có thể đặ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 giá trị boolean phụ không bắt buộc bằng --ez (ví dụ: --ez prefer_extension_decoders TRUE). Bạn có thể đặt một phần 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 mẫu, hãy đặt thao tác của ý định thành androidx.media3.demo.main.action.VIEW_LIST. Thông tin bổ sung về cấu hình mẫu vẫn giữ nguyên như androidx.media3.demo.main.action.VIEW, ngoại trừ 2 điểm khác biệt:

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

Các thông số 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 cửa sổ 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