快速入门

安装

你可以使用我们的 AI 辅助设置来安装插件。使用以下命令将 Capgo skills 添加到你的 AI 工具中：

npx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins

然后使用以下 prompt：

Use the `capacitor-plugins` skill from `Cap-go/capgo-skills` to install the `@capgo/capacitor-media-session` plugin in my project.

如果你更想手动设置，请运行以下命令安装插件，并按照下方各平台的说明操作：

bun add @capgo/capacitor-media-session
bunx cap sync

导入

import { MediaSession } from '@capgo/capacitor-media-session';

快速入门

播放器启动时，发布元数据和播放状态。

import { MediaSession } from '@capgo/capacitor-media-session';

await MediaSession.setMetadata({
  title: 'Episode 12',
  artist: 'Capgo Podcast',
  album: 'Ship faster',
  artwork: [{ src: 'https://cdn.example.com/artwork.png', sizes: '512x512', type: 'image/png' }],
});

await MediaSession.setPlaybackState({ playbackState: 'playing' });

await MediaSession.setPositionState({
  duration: 3600,
  position: 120,
  playbackRate: 1,
});

示例：处理锁屏控制

await MediaSession.setActionHandler({ action: 'play' }, () => {
  audio.play();
});

await MediaSession.setActionHandler({ action: 'pause' }, () => {
  audio.pause();
});

await MediaSession.setActionHandler({ action: 'seekto' }, (details) => {
  if (details.seekTime != null) {
    audio.currentTime = details.seekTime;
  }
});

传入 null 作为取消注册操作的处理函数。

示例：缓冲时的暂停状态

await MediaSession.setPlaybackState({ playbackState: 'paused' });
// resume with 'playing' when your buffer is ready

常见坑点

• 保持位置实时更新: 调用 setPositionState 否则在 Android 上，随着播放推进或拖动进度条时，体验会显得异常。
• 封面图 URL：请使用设备可访问的 HTTPS 资源，大尺寸图片会拖慢锁屏界面的更新速度。
• 处理器生命周期：请在播放器初始化时注册一次处理器，而不是在每次切换曲目时都注册。

API 概览

setMetadata

设置当前正在播放的媒体元数据。

import { MediaSession } from '@capgo/capacitor-media-session';

await MediaSession.setMetadata({ album: 'album' });

setPlaybackState

更新媒体会话的播放状态。

import { MediaSession } from '@capgo/capacitor-media-session';

await MediaSession.setPlaybackState({ playbackState: 'none' });

setActionHandler

为媒体会话操作注册处理器。

import { MediaSession } from '@capgo/capacitor-media-session';

await MediaSession.setActionHandler({ action: 'play' }, (details) => {
  console.log(details);
});

setPositionState

更新当前活动媒体会话的位置状态。

import { MediaSession } from '@capgo/capacitor-media-session';

await MediaSession.setPositionState({
  duration: 1000,
  playbackRate: 1,
  position: 10,
});

类型参考

MetadataOptions

export interface MetadataOptions {
  album?: string;
  artist?: string;
  artwork?: MediaImage[];
  title?: string;
}

PlaybackStateOptions

export interface PlaybackStateOptions {
  playbackState: MediaSessionPlaybackState;
}

ActionHandlerOptions

export interface ActionHandlerOptions {
  action: MediaSessionAction;
}

ActionHandler

export type ActionHandler = (details: ActionDetails) => void;

PositionStateOptions

export interface PositionStateOptions {
  duration?: number;
  playbackRate?: number;
  position?: number;
}

MediaImage

export interface MediaImage {
  src: string;
  sizes?: string;
  type?: string;
}

MediaSessionPlaybackState

export type MediaSessionPlaybackState = 'none' | 'paused' | 'playing';

MediaSessionAction

export type MediaSessionAction =
  | 'play'
  | 'pause'
  | 'seekbackward'
  | 'seekforward'
  | 'previoustrack'
  | 'nexttrack'
  | 'seekto'
  | 'stop';

单一事实来源

本页面由插件的 src/definitions.ts生成。当上游的公共 API 发生变化时，请重新运行 sync。

从入门指南继续

如果你正在使用 快速入门 要规划 dashboard 和 API 操作，请将其连接到 使用 @capgo/capacitor-media-session 关于“使用 @capgo/capacitor-media-session”中的原生功能， API 概览 关于 API Overview 中的实现细节， 简介 关于 Introduction 中的实现细节， API 密钥 有关 API Keys 的实现细节，以及 设备 有关 Devices 的实现细节。