Scripting
开始
文档
更新日志
开始
文档
更新日志
简体中文

媒体播放器

MediaPlayer API 允许与 Now Playing Center 交互，管理 Now Playing Info，并响应远程控制事件。以下是使用指南、最佳实践及示例。

入门指南

MediaPlayer API 提供对媒体播放信息的控制及远程命令处理。入门步骤如下：

  1. 设置 nowPlayingInfo，用于显示当前媒体信息。
  2. 使用 setAvailableCommands() 配置可用的命令。
  3. 注册 commandHandler，以响应远程事件。
1MediaPlayer.nowPlayingInfo = {
2  title: "歌曲标题",
3  artist: "艺术家",
4  playbackRate: 1.0,
5  elapsedPlaybackTime: 30,
6  playbackDuration: 240
7}
8
9MediaPlayer.setAvailableCommands(["play", "pause", "nextTrack", "previousTrack"])
10
11MediaPlayer.commandHandler = (command, event) => {
12  console.log(`收到命令: ${command}`)
13}

API 参考

nowPlayingInfo

nowPlayingInfo 对象显示当前播放媒体的元数据。将其设置为 null 可清除 Now Playing Info Center。

属性：

  • title: string （必需）
    媒体标题。
  • artist: string （可选）
    媒体艺术家或表演者。
  • albumTitle: string （可选）
    专辑标题。
  • artwork: UIImage （可选）
    媒体封面图片。
  • mediaType: MediaType （可选）
    默认值为 audio。
  • playbackRate: number （可选）
    当前播放速度，默认为 0。
  • elapsedPlaybackTime: DurationInSeconds （可选）
    当前播放时间，默认为 0。
  • playbackDuration: DurationInSeconds （可选）
    媒体总时长，默认为 0。

播放状态

playbackState 属性指示应用的当前播放状态：

  • unknown: 默认状态，播放状态未定义。
  • playing: 正在播放。
  • paused: 播放已暂停。
  • stopped: 播放已停止。
  • interrupted: 播放被外部事件中断。
1if (MediaPlayer.playbackState === MediaPlayerPlaybackState.playing) {
2    console.log("媒体正在播放")
3}

命令与事件处理

setAvailableCommands(commands: MediaPlayerRemoteCommand[])

指定用户可交互的远程命令。

示例：

1MediaPlayer.setAvailableCommands(["play", "pause", "stop", "nextTrack"])

commandHandler

回调函数，用于处理远程命令。注册此函数以处理命令（如 play、pause 或 seekBackward）。

示例：

1MediaPlayer.commandHandler = (command, event) => {
2  switch (command) {
3    case "play":
4      console.log("收到播放命令")
5      break
6    case "pause":
7      console.log("收到暂停命令")
8      break
9    default:
10      console.log(`未处理的命令: ${command}`)
11  }
12}

支持的命令：

  • play、pause、stop、nextTrack、previousTrack
  • seekBackward、seekForward、skipBackward、skipForward
  • rating、like、dislike、bookmark
  • changeRepeatMode、changeShuffleMode
  • enableLanguageOption、disableLanguageOption

常见用例

显示 Now Playing 信息

1MediaPlayer.nowPlayingInfo = {
2  title: "播客集数",
3  artist: "主持人",
4  elapsedPlaybackTime: 120,
5  playbackDuration: 1800,
6  playbackRate: 1.0
7}

响应播放命令

1MediaPlayer.setAvailableCommands(["play", "pause", "stop"])
2
3MediaPlayer.commandHandler = (command, event) => {
4  if (command === "play") {
5    console.log("开始播放")
6  } else if (command === "pause") {
7    console.log("暂停播放")
8  }
9}

处理自定义事件

1MediaPlayer.commandHandler = (command, event) => {
2  if (command === "seekForward") {
3    const seekEvent = event as MediaPlayerSeekCommandEvent
4    console.log(`Seek 事件类型: ${seekEvent.type}`)
5  }
6}

最佳实践

  1. 保持元数据最新：在播放状态变化时更新 nowPlayingInfo。
  2. 处理所有相关命令：确保支持用户交互（如跳转或快进）。
  3. 资源管理：播放停止时清除 nowPlayingInfo，避免显示过期信息。
  4. 使用外部设备测试：通过耳机或车载系统验证命令处理。
  5. 提供用户反馈：在命令响应中提示成功或失败。

完整示例

以下是 MediaPlayer 的完整实现：

1// 设置 Now Playing 信息
2MediaPlayer.nowPlayingInfo = {
3  title: "歌曲标题",
4  artist: "艺术家",
5  albumTitle: "专辑名称",
6  playbackRate: 1.0,
7  elapsedPlaybackTime: 0,
8  playbackDuration: 300
9}
10
11// 启用命令
12MediaPlayer.setAvailableCommands(["play", "pause", "nextTrack", "previousTrack", "seekForward", "seekBackward"])
13
14// 处理命令
15MediaPlayer.commandHandler = (command, event) => {
16  switch (command) {
17    case "play":
18      console.log("开始播放")
19      break
20    case "pause":
21      console.log("暂停播放")
22      break
23    case "nextTrack":
24      console.log("跳到下一曲")
25      break
26    case "seekForward":
27      const seekEvent = event as MediaPlayerSeekCommandEvent
28      console.log(`Seek 事件: ${seekEvent.type}`)
29      break
30    default:
31      console.log(`未处理的命令: ${command}`)
32  }
33}
大纲