スタートガイド

インストール

AIアシストによるセットアップでプラグインをインストールできます。以下のコマンドを使用して、お使いのAIツールに Capgo のスキルを追加してください：

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

次に、以下のプロンプトを使用します：

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';

Source of Truth

このページはプラグインの src/definitions.tsから生成されています。upstream で公開 API が変更されたら、再度 sync を実行してください。

Getting Startedの続きを進める

使用している場合 スタートガイド ダッシュボードと API の運用を計画するには、これを次と連携させます @capgo/capacitor-media-session の使い方 @capgo/capacitor-media-session を使用して Native Build の機能を利用する場合: API の概要 「API の概要」の実装の詳細については、 はじめに 「はじめに」における実装の詳細については、 API キー および「API Keys」の実装の詳細については、 デバイス 実装の詳細については Devices を参照してください。