Dùng phiên đa phương tiện

Phiên phát nội dung đa phương tiện là một cách thức tương tác phổ biến với trình phát âm thanh hoặc video. Bằng cách thông báo cho Android rằng nội dung nghe nhìn đang phát trong một ứng dụng, bạn có thể uỷ quyền điều khiển chế độ phát cho ứng dụng. Việc tích hợp với phiên phát nội dung nghe nhìn cho phép một ứng dụng quảng cáo nội dung nghe nhìn phát ra bên ngoài và nhận lệnh phát từ các nguồn bên ngoài. Các nguồn này có thể là các nút vật lý (chẳng hạn như nút phát trên tai nghe hoặc điều khiển từ xa của TV) hoặc các lệnh gián tiếp (chẳng hạn như hướng dẫn "tạm dừng" đối với Trợ lý Google). Sau đó, phiên phát nội dung đa phương tiện sẽ uỷ quyền các lệnh này cho ứng dụng. Ứng dụng sẽ áp dụng các lệnh đó cho trình phát nội dung đa phương tiện mà trình phát này đang minh bạch nơi phát sinh lệnh.

Một phiên phát nội dung đa phương tiện sẽ hiển thị cùng với trình phát mà ứng dụng quản lý. Bạn nên tạo và khởi chạy một phiên phát nội dung đa phương tiện trong phương thức onCreate() của hoạt động hoặc dịch vụ sở hữu phiên phát nội dung đa phương tiện và trình phát liên kết.

Khởi động phiên phát nội dung đa phương tiện

Một phiên nội dung nghe nhìn mới tạo không có tính năng nào. Bạn phải khởi chạy phiên bằng cách thực hiện các bước sau:

  • Đặt cờ để phiên phát nội dung đa phương tiện có thể nhận lệnh gọi lại từ trình điều khiển nội dung đa phương tiện và các nút nội dung đa phương tiện.
  • Tạo và khởi chạy một thực thể của PlaybackStateCompat rồi gán thực thể đó cho phiên. Trạng thái phát thay đổi trong suốt phiên, vì vậy bạn nên lưu PlaybackStateCompat.Builder vào bộ nhớ đệm để sử dụng lại.
  • Tạo một thực thể của MediaSessionCompat.Callback rồi chỉ định thực thể đó cho phiên (xem thêm thông tin về các lệnh gọi lại ở bên dưới).

Bạn nên tạo và khởi chạy một phiên phát nội dung đa phương tiện trong phương thức onCreate() của hoạt động hoặc dịch vụ sở hữu phiên đó.

Để các nút nội dung đa phương tiện hoạt động khi ứng dụng của bạn mới được khởi chạy (hoặc bị dừng), PlaybackState của ứng dụng đó phải chứa một hành động phát phù hợp với ý định mà nút nội dung đa phương tiện gửi đi. Đây là lý do ACTION_PLAY được gán cho trạng thái phiên trong quá trình khởi chạy. Để biết thêm thông tin, hãy xem phần Phản hồi các nút nội dung đa phương tiện.

Duy trì trạng thái phát và siêu dữ liệu

Có 2 lớp đại diện cho trạng thái của một phiên phát nội dung đa phương tiện.

Lớp PlaybackStateCompat mô tả trạng thái hoạt động hiện tại của trình phát. Trong đó có:

  • Trạng thái truyền tải (cho dù người chơi đang phát/tạm dừng/đang lưu vào bộ đệm, v.v. Vui lòng xem getState())
  • Mã lỗi và thông báo lỗi không bắt buộc, nếu có. (Xem getErrorCode() và đọc Trạng thái và lỗi ở bên dưới.)
  • Vị trí trình phát
  • Thao tác hợp lệ của tay điều khiển có thể xử lý được ở trạng thái hiện tại

Lớp MediaMetadataCompat mô tả tài liệu đang phát:

  • Tên của nghệ sĩ, đĩa nhạc và bản nhạc
  • Thời lượng bản nhạc
  • Ảnh bìa album để hiển thị trên màn hình khoá. Hình ảnh là một bitmap có kích thước tối đa là 320x320dp (nếu lớn hơn thì hình ảnh sẽ được thu nhỏ).
  • Một thực thể của ContentUris trỏ đến phiên bản lớn hơn của hình minh hoạ

Trạng thái và siêu dữ liệu của trình phát có thể thay đổi trong suốt thời gian diễn ra phiên phát nội dung đa phương tiện. Mỗi khi trạng thái hoặc siêu dữ liệu thay đổi, bạn phải sử dụng trình tạo tương ứng cho từng lớp, PlaybackStateCompat.Builder() hoặc MediaMetadataCompat.Builder(), sau đó truyền thực thể mới đến phiên phát nội dung đa phương tiện bằng cách gọi setPlaybackState() hoặc setMetaData(). Để giảm mức tiêu thụ bộ nhớ tổng thể từ các thao tác thường xuyên này, bạn nên tạo các trình tạo một lần và sử dụng lại chúng trong suốt thời gian hoạt động.

Trạng thái và lỗi

Xin lưu ý rằng PlaybackState là một đối tượng chứa các giá trị riêng biệt cho trạng thái phát của phiên (getState()) và mã lỗi liên kết (getErrorCode()) khi cần. Lỗi có thể nghiêm trọng hoặc không nghiêm trọng:

Bất cứ khi nào quá trình phát bị gián đoạn, bạn nên tạo một lỗi nghiêm trọng: Đặt trạng thái truyền tải thành STATE_ERROR và chỉ định lỗi liên quan bằng setErrorMessage(int, CharSequence). Miễn là việc phát bị lỗi, PlaybackState sẽ tiếp tục báo cáo STATE_ERROR và lỗi.

Lỗi không nghiêm trọng xảy ra khi ứng dụng của bạn không thể xử lý yêu cầu nhưng có thể tiếp tục phát: Quá trình truyền tải vẫn ở trạng thái "bình thường" (chẳng hạn như STATE_PLAYING) nhưng PlaybackState sẽ chứa một mã lỗi. Ví dụ: nếu bài hát gần đây nhất đang phát và người dùng yêu cầu chuyển sang bài hát tiếp theo, thì quá trình phát có thể tiếp tục nhưng bạn nên tạo một PlaybackState mới với mã lỗi ERROR_CODE_END_OF_QUEUE rồi gọi setPlaybackState(). Bộ điều khiển nội dung đa phương tiện được đính kèm vào phiên này sẽ nhận lệnh gọi lại onPlaybackStateChanged() và giải thích cho người dùng về điều đã xảy ra. Lỗi không nghiêm trọng chỉ nên được báo cáo một lần vào thời điểm xảy ra lỗi. Trong lần tiếp theo cập nhật phiên, PlaybackState sẽ không đặt lại cùng một lỗi không nghiêm trọng (trừ phi lỗi đó xảy ra trong phản hồi một yêu cầu mới).

Màn hình khoá phiên phát nội dung đa phương tiện

Kể từ Android 4.0 (API cấp 14), hệ thống có thể truy cập trạng thái phát và siêu dữ liệu của phiên phát nội dung đa phương tiện. Đây là cách màn hình khoá có thể hiển thị các nút điều khiển nội dung nghe nhìn và hình minh hoạ. Hành vi này thay đổi tuỳ thuộc vào phiên bản Android.

Hình minh họa album

Trong Android 4.0 (API cấp 14) đến Android 10 (API cấp 29), nền của màn hình khoá sẽ hiển thị hình minh hoạ của album, nhưng chỉ khi siêu dữ liệu phiên phát nội dung đa phương tiện bao gồm bitmap trong nền.

Điều khiển phương tiện giao thông

Trong Android 4.0 (API cấp 14) đến Android 4.4 (API cấp 19), khi một phiên phát nội dung đa phương tiện đang hoạt động và siêu dữ liệu của phiên phát nội dung đa phương tiện bao gồm bitmap nền, màn hình khoá sẽ tự động hiển thị các chế độ điều khiển truyền tải.

Trong Android 5.0 (API cấp 21) trở lên, hệ thống không cung cấp các chế độ điều khiển truyền tải trên màn hình khoá. Thay vào đó, bạn nên sử dụng thông báo MediaStyle để hiển thị các nút điều khiển truyền tải.

Thêm thao tác tuỳ chỉnh

Các ứng dụng đa phương tiện có thể xác định các thao tác tuỳ chỉnh; ví dụ: thích, thích hoặc tua lại 30 giây. Hành động tuỳ chỉnh sẽ triển khai hành vi hoàn toàn mới. Không sử dụng thao tác tuỳ chỉnh để thay thế một trong các thao tác điều khiển truyền tải tiêu chuẩn được xác định trong PlaybackStateCompat.

Thêm hành động tuỳ chỉnh bằng addCustomAction(). Ví dụ sau đây cho biết cách thêm chế độ kiểm soát cho một hành động thích:

Kotlin

stateBuilder.addCustomAction(
        PlaybackStateCompat.CustomAction.Builder(
                CUSTOM_ACTION_THUMBS_UP,
                resources.getString(R.string.thumbs_up),
                thumbsUpIcon
        ).run {
            setExtras(customActionExtras)
            build()
        }
)

Java

stateBuilder.addCustomAction(new PlaybackStateCompat.CustomAction.Builder(
    CUSTOM_ACTION_THUMBS_UP, resources.getString(R.string.thumbs_up), thumbsUpIcon)
    .setExtras(customActionExtras)
    .build());

Xem Trình phát nhạc Universal để biết ví dụ đầy đủ.

Bạn phản hồi thao tác này bằng onCustomAction().

Kotlin

override fun onCustomAction(action: String, extras: Bundle?) {
    when(action) {
        CUSTOM_ACTION_THUMBS_UP -> {
            ...
        }
    }
}

Java

@Override
public void onCustomAction(@NonNull String action, Bundle extras) {
    if (CUSTOM_ACTION_THUMBS_UP.equals(action)) {
        ...
    }
}

Đồng thời, xem Trình phát nhạc Universal.

Lệnh gọi lại phiên đa phương tiện

Các phương thức gọi lại phiên phát nội dung đa phương tiện chính là onPlay(), onPause() và onStop(). Đây là nơi bạn thêm mã điều khiển trình phát của mình.

Vì bạn tạo thực thể và đặt lệnh gọi lại của phiên trong thời gian chạy (trong onCreate()), nên ứng dụng của bạn có thể xác định các lệnh gọi lại thay thế sử dụng nhiều trình phát và chọn tổ hợp lệnh gọi lại/trình phát phù hợp tuỳ thuộc vào cấp độ thiết bị và/hoặc hệ thống. Bạn có thể thay đổi trình phát mà không thay đổi phần còn lại của ứng dụng. Ví dụ: bạn có thể sử dụng ExoPlayer khi chạy trên Android 4.1 (API cấp 16) trở lên và sử dụng MediaPlayer trên các hệ thống cũ.

Bên cạnh việc điều khiển trình phát và quản lý quá trình chuyển đổi trạng thái phiên phát nội dung đa phương tiện, lệnh gọi lại còn bật và tắt các tính năng của ứng dụng, cũng như kiểm soát cách ứng dụng tương tác với các ứng dụng khác và phần cứng của thiết bị. (Xem phần Điều khiển đầu ra âm thanh).

Việc triển khai phương thức gọi lại phiên phát nội dung đa phương tiện phụ thuộc vào cấu trúc ứng dụng của bạn. Hãy xem các trang riêng mô tả cách dùng lệnh gọi lại trong ứng dụng âm thanh và ứng dụng video, mô tả cách triển khai lệnh gọi lại cho từng loại ứng dụng.