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

Phiên phát nội dung đa phương tiện cung cấp cách thức toàn cầu để tương tác với âm thanh hoặc video trình phát. 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, hãy phát nội dung các chế độ điều khiển có thể được uỷ quyền cho ứng dụng. Việc tích hợp với phiên đa phương tiện cho phép một ứng dụng để quảng cáo việc phát nội dung nghe nhìn ở 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" cho Trợ lý Google). Sau đó, phiên đa phương tiện uỷ quyền các lệnh cho ứng dụng áp dụng các lệnh đó cho trình phát nội dung đa phương tiện rõ ràng nơi bắt nguồn lệnh.

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

Lưu ý: Phương pháp hay nhất để viết một ứng dụng đa phương tiện là sử dụng thư viện media-compat. Có thuật ngữ "phiên phát nội dung đa phương tiện" trên trang này có nghĩa là thực thể của MediaSessionCompat, và "trình điều khiển nội dung đa phương tiện" có nghĩa là thực thể của MediaControllerCompat.

Khởi chạy phiên phát nội dung nghe nhìn

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 tạo phiên bằng cách thực hiện các bước sau:

• Thiết lập cờ để phiên phát nội dung đa phương tiện có thể nhận lệnh gọi lại từ bộ điều khiển nội dung nghe nhìn và các nút.
• Tạo và khởi tạo một thực thể của PlaybackStateCompat rồi gán thực thể đó cho phiên hoạt động. 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 và gán thực thể đó cho phiên (tìm hiểu thêm về 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 đ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 đa phương tiện hoạt động khi ứng dụng 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 khớp với ý định mà nút nội dung đa phương tiện gửi. Đây là tại sao ACTION_PLAY được chỉ định cho trạng thái phiên trong khoảng thời gian khởi tạo. Để biết thêm thông tin, hãy xem bài viết Phản hồi nội dung nghe nhìn Nút.

Lưu ý: Nếu bạn đang tích hợp với tiện ích ExoPlayer MediaSession, bạn không cần phải triển khai MediaSessionCompat.Callback của riêng mình. Chiến lược phát hành đĩa đơn MediaSessionConnector đảm nhận việc ánh xạ trạng thái của trình phát đến nội dung đa phương tiện các sự kiện trong phiên phát trực tiếp và uỷ quyền nhận được từ phiên phá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 thể hiện trạng thái của một phiên phát nội dung đa phương tiện.

Chiến lược phát hành đĩa đơn PlaybackStateCompat lớp 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ù trình phát đang phát/tạm dừng/đang lưu vào bộ đệm, v.v. Hãy 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í người chơi
• Các thao tác hợp lệ của bộ điều khiển có thể được xử lý ở trạng thái hiện tại

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

• Tên 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 của trình phát và siêu dữ liệu có thể thay đổi trong vòng đời của một 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 các trình tạo đó trong suốt thời gian hoạt động.

Trạng thái và lỗi

Lưu ý rằng PlaybackState là đối tượng chứa các giá trị riêng cho thuộc tính trạng thái phát của phiên (getState()) và khi cần thiết sẽ cung cấp mã lỗi (getErrorCode()) được liên kết. 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 phát hiện một lỗi nghiêm trọng: Hãy đặt trạng thái truyền tải đến STATE_ERROR và chỉ định một lỗi liên quan với setErrorMessage(int, CharSequence). Miễn là hoạt động phát bị chặn do 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 không thể xử lý một yêu cầu nhưng có thể tiếp tục chơi: Quá trình di chuyển vẫn ở trạng thái "bình thường" trạng thái (chẳng hạn như STATE_PLAYING) nhưng PlaybackState chứa mã lỗi. Ví dụ: nếu bài hát cuối cùng đang phát và người dùng yêu cầu chuyển đến bài hát tiếp theo, bạn có thể tiếp tục phát nhưng bạn nên tạo một PlaybackState mới kèm theo mã lỗi ERROR_CODE_END_OF_QUEUE và sau đó gọi setPlaybackState(). Những Bộ điều khiển nội dung nghe nhìn được gắn vào phiên sẽ nhận được lệnh gọi lại onPlaybackStateChanged() và giải thích cho người dùng điều gì đã xảy ra. Lỗi không nghiêm trọng chỉ được báo cáo một lần vào thời điểm xảy ra lỗi. Vào lần cập nhật phiên tiếp theo, 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 theo một yêu cầu mới).

Màn hình khoá của 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 vào trạng thái phát và siêu dữ liệu. Đây là cách màn hình khoá có thể hiển thị các chế độ điều khiển nội dung nghe nhìn và hình minh hoạ. Hành vi này sẽ 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ị ảnh bìa đĩa nhạc, nhưng chỉ khi phiên phát nội dung đa phương tiện siêu dữ liệu bao gồm một bitmap nền.

Phương thức đ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 đa phương tiện đang hoạt động và siêu dữ liệu phiên đa phương tiện bao gồm bitmap nền, màn hình khoá sẽ tự động hiển thị các nút đ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ông cụ truyền tải các điều khiển trên màn hình khoá. Thay vào đó, bạn nên sử dụng thẻ MediaStyle thông báo để hiển thị các nút điều khiển phương tiện giao thông.

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. Thao tác tuỳ chỉnh sẽ triển khai hành vi hoàn toàn mới. Hành động không được sử dụng một thao tác tuỳ chỉnh để thay thế một trong các thao tác kiểm soát phương tiện giao thông tiêu chuẩn được xác định trong PlaybackStateCompat.

Thêm các thao tác tuỳ chỉnh bằng addCustomAction(). Ví dụ sau đây trình bày cách thêm một chế độ điều khiển 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 Universal Music Player để biết ví dụ đầy đủ.

Bạn phản hồi hành động 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 Universal Music Player.

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

Các phương thức gọi lại chính của phiên phát nội dung đa phương tiện 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à thiết lập 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 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/người chơi thích hợp, tuỳ thuộc vào thiết bị và/hoặc cấp độ 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ũ hơn.

Ngoài việc kiểm soát trình phát và quản lý 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ũng 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 thiết bị. (Xem phần Kiểm soát đầ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 của ứng dụng. Hãy xem các trang riêng biệt 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.