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 trình phát âm thanh hoặc video. Trong Media3, trình phát mặc định là lớp ExoPlayer, lớp này triển khai giao diện Player. Việc kết nối phiên phát nội dung nghe nhìn với trình phát cho phép ứng dụng quảng cáo tính năng phát nội dung nghe nhìn ra bên ngoài và nhận lệnh phát từ các nguồn bên ngoài.
Các lệnh có thể bắt nguồn từ 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. Các quảng cáo này cũng có thể đến từ các ứng dụng khách có trình điều khiển nội dung nghe nhìn, chẳng hạn như hướng dẫn "tạm dừng" cho Trợ lý Google. Phiên phát nội dung đa phương tiện uỷ quyền các lệnh này cho trình phát của ứng dụng đa phương tiện.
Thời điểm chọn một phiên phát nội dung nghe nhìn
Khi triển khai MediaSession, bạn sẽ cho phép người dùng điều khiển chế độ phát:
- Thông qua tai nghe. Thường có các nút hoặc hoạt động tương tác chạm mà người dùng có thể thực hiện trên tai nghe để phát hoặc tạm dừng nội dung nghe nhìn hoặc chuyển đến bản nhạc tiếp theo hoặc trước đó.
- Bằng cách trò chuyện với Trợ lý Google. Một cách phổ biến là nói "Ok Google, tạm dừng" để tạm dừng mọi nội dung nghe nhìn đang phát trên thiết bị.
- Thông qua đồng hồ Wear OS của họ. Nhờ vậy, họ có thể dễ dàng truy cập vào các bộ điều khiển chế độ phát phổ biến nhất khi phát trên điện thoại.
- Thông qua mục Điều khiển nội dung nghe nhìn. Băng chuyền này hiển thị các chế độ điều khiển cho mỗi phiên phát nội dung nghe nhìn đang chạy.
- Trên TV. Cho phép các thao tác bằng nút phát vật lý, điều khiển chế độ phát trên nền tảng và quản lý nguồn điện (ví dụ: nếu TV, loa thanh hoặc bộ thu A/V tắt hoặc chuyển đổi đầu vào, thì chế độ phát sẽ dừng trong ứng dụng).
- Và bất kỳ quy trình bên ngoài nào khác cần ảnh hưởng đến quá trình phát.
Điều này rất hữu ích trong nhiều trường hợp sử dụng. Cụ thể, bạn nên cân nhắc sử dụng MediaSession khi:
- Bạn đang phát trực tuyến nội dung video dài, chẳng hạn như phim hoặc chương trình truyền hình trực tuyến.
- Bạn đang phát trực tuyến nội dung âm thanh dài, chẳng hạn như podcast hoặc danh sách phát nhạc.
- Bạn đang xây dựng một ứng dụng truyền hình.
Tuy nhiên, không phải trường hợp sử dụng nào cũng phù hợp với MediaSession. Bạn có thể chỉ muốn sử dụng Player trong các trường hợp sau:
- Bạn đang hiển thị nội dung dạng ngắn, trong đó mức độ tương tác và tương tác của người dùng là rất quan trọng.
- Không có một video nào đang hoạt động, chẳng hạn như người dùng đang cuộn qua một danh sách và nhiều video hiện trên màn hình cùng một lúc.
- Bạn đang phát video giới thiệu hoặc giải thích một lần mà bạn mong đợi người dùng sẽ chủ động xem.
- Nội dung của bạn nhạy cảm về quyền riêng tư và bạn không muốn các quy trình bên ngoài truy cập vào siêu dữ liệu của nội dung nghe nhìn (ví dụ: chế độ ẩn danh trong trình duyệt)
Nếu trường hợp sử dụng của bạn không phù hợp với bất kỳ trường hợp nào nêu trên, hãy cân nhắc xem bạn có đồng ý tiếp tục phát ứng dụng khi người dùng không chủ động tương tác với nội dung hay không. Nếu câu trả lời là có, bạn có thể muốn chọn
MediaSession. Nếu câu trả lời là không, bạn có thể muốn sử dụng Player.
Tạo một phiên nội dung nghe nhìn
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 có thể tạo một phiên phát nội dung đa phương tiện bằng đối tượng Context và Player. Bạn nên tạo và khởi động một phiên phát nội dung đa phương tiện khi cần thiết, chẳng hạn như phương thức vòng đời onStart() hoặc onResume() của Activity hoặc Fragment, hoặc phương thức onCreate() của Service sở hữu phiên phát nội dung đa phương tiện và trình phát liên kết với phiên đó.
Để tạo một phiên phát nội dung đa phương tiện, hãy khởi chạy Player và cung cấp phiên đó cho MediaSession.Builder như sau:
Kotlin
val player = ExoPlayer.Builder(context).build() val mediaSession = MediaSession.Builder(context, player).build()
Java
ExoPlayer player = new ExoPlayer.Builder(context).build(); MediaSession mediaSession = new MediaSession.Builder(context, player).build();
Tự động xử lý trạng thái
Thư viện Media3 tự động cập nhật phiên phát nội dung đa phương tiện bằng cách sử dụng trạng thái của trình phát. Do đó, bạn không cần phải xử lý thủ công quá trình ánh xạ từ người chơi này sang phiên khác.
Đây là một điểm thay đổi so với phương pháp cũ, trong đó bạn cần tạo và duy trì PlaybackStateCompat một cách độc lập với chính trình phát, chẳng hạn như để chỉ báo lỗi.
Mã phiên duy nhất
Theo mặc định, MediaSession.Builder sẽ tạo một phiên có chuỗi trống làm mã phiên. Điều này là đủ nếu một ứng dụng có ý định chỉ tạo một phiên bản duy nhất, đây là trường hợp phổ biến nhất.
Nếu muốn quản lý nhiều phiên bản của mỗi phiên cùng một lúc, thì ứng dụng phải đảm bảo rằng mã phiên của mỗi phiên là duy nhất. Bạn có thể đặt mã phiên khi tạo phiên bằng MediaSession.Builder.setId(String id).
Nếu bạn thấy ứng dụng IllegalStateException gặp sự cố kèm theo thông báo lỗi IllegalStateException: Session ID must be unique. ID=, thì có thể một phiên đã được tạo bất ngờ trước khi một thực thể đã tạo trước đó có cùng mã nhận dạng được phát hành. Để tránh các phiên bị rò rỉ do lỗi lập trình, những trường hợp như vậy sẽ được phát hiện và thông báo bằng cách gửi một ngoại lệ.
Cấp quyền kiểm soát cho các ứng dụng khách khác
Phiên phát nội dung đa phương tiện là chìa khoá để điều khiển quá trình phát. Thư viện này cho phép bạn định tuyến các lệnh từ nguồn bên ngoài đến trình phát thực hiện việc phát nội dung nghe nhìn. 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 như hướng dẫn "tạm dừng" cho Trợ lý Google. Tương tự như vậy, bạn nên cấp quyền truy cập vào hệ thống Android để hỗ trợ các chế độ điều khiển thông báo và màn hình khoá hoặc cho đồng hồ Wear OS để có thể điều khiển chế độ phát trên mặt đồng hồ. Các ứng dụng bên ngoài có thể sử dụng trình điều khiển nội dung đa phương tiện để đưa ra lệnh phát cho ứng dụng đa phương tiện của bạn. Phiên phát nội dung đa phương tiện sẽ nhận các lệnh này qua phiên phát nội dung đa phương tiện, cuối cùng sẽ uỷ quyền các lệnh cho trình phát nội dung đa phương tiện.
Khi tay điều khiển sắp kết nối với phiên phát nội dung đa phương tiện, phương thức onConnect() sẽ được gọi. Bạn có thể sử dụng ControllerInfo được cung cấp để quyết định xem nên chấp nhận hay từ chối yêu cầu. Xem ví dụ về cách chấp nhận yêu cầu kết nối trong phần Khai báo các lệnh có sẵn.
Sau khi kết nối, tay điều khiển có thể gửi lệnh phát cho phiên này. Sau đó, phiên hoạt động sẽ uỷ quyền các lệnh đó cho người chơi. Các lệnh phát và danh sách phát đã xác định trong giao diện Player sẽ được phiên xử lý tự động.
Các phương thức gọi lại khác cho phép bạn xử lý, chẳng hạn như yêu cầu lệnh phát tuỳ chỉnh và sửa đổi danh sách phát).
Các lệnh gọi lại này cũng bao gồm đối tượng ControllerInfo để bạn có thể sửa đổi cách phản hồi từng yêu cầu trên cơ sở từng tay điều khiển.
Sửa đổi danh sách phát
Một phiên phát nội dung đa phương tiện có thể trực tiếp sửa đổi danh sách phát của trình phát như đã giải thích trong hướng dẫn ExoPlayer về danh sách phát.
Các tay điều khiển cũng có thể sửa đổi danh sách phát nếu có COMMAND_SET_MEDIA_ITEM hoặc COMMAND_CHANGE_MEDIA_ITEMS.
Khi thêm các mục mới vào danh sách phát, trình phát thường yêu cầu các phiên bản MediaItem có URI đã xác định để có thể phát các mục đó. Theo mặc định, hệ thống sẽ tự động chuyển tiếp các mục mới thêm đến các phương thức của trình phát như player.addMediaItem nếu các mục đó có URI được xác định.
Nếu muốn tuỳ chỉnh các thực thể MediaItem được thêm vào trình phát, bạn có thể ghi đè onAddMediaItems().
Đây là bước cần thiết khi bạn muốn hỗ trợ các bộ điều khiển yêu cầu nội dung nghe nhìn mà không cần URI đã xác định. Thay vào đó, MediaItem thường có một hoặc nhiều trường sau đây được đặt để mô tả nội dung nghe nhìn được yêu cầu:
MediaItem.id: Mã nhận dạng chung cho nội dung nghe nhìn.MediaItem.RequestMetadata.mediaUri: URI yêu cầu có thể sử dụng giản đồ tuỳ chỉnh và không nhất thiết là người chơi có thể phát trực tiếp.MediaItem.RequestMetadata.searchQuery: Cụm từ tìm kiếm bằng văn bản, chẳng hạn như từ Trợ lý Google.MediaItem.MediaMetadata: Siêu dữ liệu có cấu trúc như "tiêu đề" hoặc "nghệ sĩ".
Để có thêm lựa chọn tuỳ chỉnh cho danh sách phát hoàn toàn mới, bạn có thể ghi đè thêm onSetMediaItems() để xác định mục và vị trí bắt đầu trong danh sách phát. Ví dụ: bạn có thể mở rộng một mục được yêu cầu cho toàn bộ danh sách phát và hướng dẫn người chơi bắt đầu tại chỉ mục của mục được yêu cầu ban đầu. Bạn có thể xem cách triển khai onSetMediaItems() bằng tính năng này trong ứng dụng minh hoạ phiên.
Quản lý bố cục tuỳ chỉnh và lệnh tuỳ chỉnh
Các phần sau đây mô tả cách quảng cáo bố cục tuỳ chỉnh của các nút lệnh tuỳ chỉnh đến ứng dụng khách và cho phép bộ điều khiển gửi lệnh tuỳ chỉnh.
Xác định bố cục tuỳ chỉnh của phiên
Để cho các ứng dụng khách biết bạn muốn hiển thị bộ điều khiển chế độ phát nào cho người dùng, hãy đặt bố cục tuỳ chỉnh của phiên khi tạo MediaSession trong phương thức onCreate() của dịch vụ.
Kotlin
override fun onCreate() {
super.onCreate()
val likeButton = CommandButton.Builder()
.setDisplayName("Like")
.setIconResId(R.drawable.like_icon)
.setSessionCommand(SessionCommand(SessionCommand.COMMAND_CODE_SESSION_SET_RATING))
.build()
val favoriteButton = CommandButton.Builder()
.setDisplayName("Save to favorites")
.setIconResId(R.drawable.favorite_icon)
.setSessionCommand(SessionCommand(SAVE_TO_FAVORITES, Bundle()))
.build()
session =
MediaSession.Builder(this, player)
.setCallback(CustomMediaSessionCallback())
.setCustomLayout(ImmutableList.of(likeButton, favoriteButton))
.build()
}
Java
@Override
public void onCreate() {
super.onCreate();
CommandButton likeButton = new CommandButton.Builder()
.setDisplayName("Like")
.setIconResId(R.drawable.like_icon)
.setSessionCommand(new SessionCommand(SessionCommand.COMMAND_CODE_SESSION_SET_RATING))
.build();
CommandButton favoriteButton = new CommandButton.Builder()
.setDisplayName("Save to favorites")
.setIconResId(R.drawable.favorite_icon)
.setSessionCommand(new SessionCommand(SAVE_TO_FAVORITES, new Bundle()))
.build();
Player player = new ExoPlayer.Builder(this).build();
mediaSession =
new MediaSession.Builder(this, player)
.setCallback(new CustomMediaSessionCallback())
.setCustomLayout(ImmutableList.of(likeButton, favoriteButton))
.build();
}
Khai báo trình phát có sẵn và lệnh tuỳ chỉnh
Các ứng dụng đa phương tiện có thể xác định các lệnh tuỳ chỉnh dùng được trong bố cục tuỳ chỉnh. Ví dụ: bạn có thể muốn triển khai các nút cho phép người dùng lưu một mục nội dung đa phương tiện vào danh sách các mục yêu thích. MediaController gửi lệnh tuỳ chỉnh và MediaSession.Callback nhận được các lệnh đó.
Bạn có thể xác định các lệnh trong phiên tuỳ chỉnh có sẵn cho MediaController khi thiết bị này kết nối với phiên phát nội dung nghe nhìn của bạn. Bạn thực hiện việc này bằng cách ghi đè MediaSession.Callback.onConnect(). Định cấu hình và trả về tập hợp các lệnh có sẵn khi chấp nhận yêu cầu kết nối từ MediaController trong phương thức gọi lại onConnect:
Kotlin
private inner class CustomMediaSessionCallback: MediaSession.Callback {
// Configure commands available to the controller in onConnect()
override fun onConnect(
session: MediaSession,
controller: MediaSession.ControllerInfo
): MediaSession.ConnectionResult {
val sessionCommands = ConnectionResult.DEFAULT_SESSION_COMMANDS.buildUpon()
.add(SessionCommand(SAVE_TO_FAVORITES, Bundle.EMPTY))
.build()
return AcceptedResultBuilder(session)
.setAvailableSessionCommands(sessionCommands)
.build()
}
}
Java
class CustomMediaSessionCallback implements MediaSession.Callback {
// Configure commands available to the controller in onConnect()
@Override
public ConnectionResult onConnect(
MediaSession session,
ControllerInfo controller) {
SessionCommands sessionCommands =
ConnectionResult.DEFAULT_SESSION_COMMANDS.buildUpon()
.add(new SessionCommand(SAVE_TO_FAVORITES, new Bundle()))
.build();
return new AcceptedResultBuilder(session)
.setAvailableSessionCommands(sessionCommands)
.build();
}
}
Để nhận các yêu cầu lệnh tuỳ chỉnh từ MediaController, hãy ghi đè phương thức onCustomCommand() trong Callback.
Kotlin
private inner class CustomMediaSessionCallback: MediaSession.Callback {
...
override fun onCustomCommand(
session: MediaSession,
controller: MediaSession.ControllerInfo,
customCommand: SessionCommand,
args: Bundle
): ListenableFuture<SessionResult> {
if (customCommand.customAction == SAVE_TO_FAVORITES) {
// Do custom logic here
saveToFavorites(session.player.currentMediaItem)
return Futures.immediateFuture(
SessionResult(SessionResult.RESULT_SUCCESS)
)
}
...
}
}
Java
class CustomMediaSessionCallback implements MediaSession.Callback {
...
@Override
public ListenableFuture<SessionResult> onCustomCommand(
MediaSession session,
ControllerInfo controller,
SessionCommand customCommand,
Bundle args
) {
if(customCommand.customAction.equals(SAVE_TO_FAVORITES)) {
// Do custom logic here
saveToFavorites(session.getPlayer().getCurrentMediaItem());
return Futures.immediateFuture(
new SessionResult(SessionResult.RESULT_SUCCESS)
);
}
...
}
}
Bạn có thể theo dõi bộ điều khiển nội dung nghe nhìn nào đang tạo yêu cầu bằng cách sử dụng thuộc tính packageName của đối tượng MediaSession.ControllerInfo được truyền vào các phương thức Callback. Nhờ vậy, bạn có thể điều chỉnh hành vi của ứng dụng theo một lệnh nhất định nếu lệnh đó bắt nguồn từ hệ thống, ứng dụng của bạn hoặc các ứng dụng khách khác.
Cập nhật bố cục tuỳ chỉnh sau khi người dùng tương tác
Sau khi xử lý một lệnh tuỳ chỉnh hoặc bất kỳ hoạt động tương tác nào khác với người chơi, bạn nên cập nhật bố cục hiển thị trong giao diện người dùng của bộ điều khiển. Một ví dụ điển hình là nút bật tắt thay đổi biểu tượng sau khi kích hoạt thao tác liên kết với nút này. Để cập nhật bố cục, bạn có thể dùng MediaSession.setCustomLayout:
Kotlin
val removeFromFavoritesButton = CommandButton.Builder()
.setDisplayName("Remove from favorites")
.setIconResId(R.drawable.favorite_remove_icon)
.setSessionCommand(SessionCommand(REMOVE_FROM_FAVORITES, Bundle()))
.build()
mediaSession.setCustomLayout(ImmutableList.of(likeButton, removeFromFavoritesButton))
Java
CommandButton removeFromFavoritesButton = new CommandButton.Builder()
.setDisplayName("Remove from favorites")
.setIconResId(R.drawable.favorite_remove_icon)
.setSessionCommand(new SessionCommand(REMOVE_FROM_FAVORITES, new Bundle()))
.build();
mediaSession.setCustomLayout(ImmutableList.of(likeButton, removeFromFavoritesButton));
Tuỳ chỉnh hành vi của lệnh phát
Để tuỳ chỉnh hành vi của một lệnh được xác định trong giao diện Player, chẳng hạn như play() hoặc seekToNext(), hãy gói Player trong một ForwardingPlayer.
Kotlin
val player = ExoPlayer.Builder(context).build()
val forwardingPlayer = object : ForwardingPlayer(player) {
override fun play() {
// Add custom logic
super.play()
}
override fun setPlayWhenReady(playWhenReady: Boolean) {
// Add custom logic
super.setPlayWhenReady(playWhenReady)
}
}
val mediaSession = MediaSession.Builder(context, forwardingPlayer).build()
Java
ExoPlayer player = new ExoPlayer.Builder(context).build();
ForwardingPlayer forwardingPlayer = new ForwardingPlayer(player) {
@Override
public void play() {
// Add custom logic
super.play();
}
@Override
public void setPlayWhenReady(boolean playWhenReady) {
// Add custom logic
super.setPlayWhenReady(playWhenReady);
}
};
MediaSession mediaSession =
new MediaSession.Builder(context, forwardingPlayer).build();
Để biết thêm thông tin về ForwardingPlayer, hãy xem hướng dẫn về ExoPlayer về Tuỳ chỉnh.
Xác định trình điều khiển yêu cầu của một lệnh người chơi
Khi lệnh gọi đến phương thức Player do MediaController bắt nguồn, bạn có thể xác định nguồn gốc bằng MediaSession.controllerForCurrentRequest và nhận ControllerInfo cho yêu cầu hiện tại:
Kotlin
class CallerAwareForwardingPlayer(player: Player) :
ForwardingPlayer(player) {
override fun seekToNext() {
Log.d(
"caller",
"seekToNext called from package ${session.controllerForCurrentRequest?.packageName}"
)
super.seekToNext()
}
}
Java
public class CallerAwareForwardingPlayer extends ForwardingPlayer {
public CallerAwareForwardingPlayer(Player player) {
super(player);
}
@Override
public void seekToNext() {
Log.d(
"caller",
"seekToNext called from package: "
+ session.getControllerForCurrentRequest().getPackageName());
super.seekToNext();
}
}
Nút phản hồi với nội dung nghe nhìn
Nút nội dung đa phương tiện là các nút phần cứng có trên thiết bị Android và các thiết bị ngoại vi khác, chẳng hạn như nút phát/tạm dừng trên tai nghe Bluetooth. Media3 xử lý các sự kiện nút nội dung đa phương tiện cho bạn khi chúng đến phiên và gọi phương thức Player thích hợp trên trình phát trong phiên.
Một ứng dụng có thể ghi đè hành vi mặc định bằng cách ghi đè MediaSession.Callback.onMediaButtonEvent(Intent). Trong trường hợp như vậy, ứng dụng có thể/cần tự xử lý tất cả các thông tin cụ thể về API.