시작하기

설치

AI 지원 설정으로 플러그인을 설치할 수 있습니다. 다음 명령어로 AI 도구에 Capgo 스킬을 추가하세요:

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.

Manual Setup을 선호한다면, 다음 명령어를 실행하여 플러그인을 설치하고 아래의 플랫폼별 지침을 따르세요:

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에서 생성되었습니다. public API가 업스트림에서 변경되면 동기화를 다시 실행하세요.

Getting Started에서 계속하기

사용 중인 경우 시작하기 대시보드와 API 운영을 계획하려면, 이를 다음 항목과 연결하세요: @capgo/capacitor-media-session 사용하기 @capgo/capacitor-media-session 사용하기의 네이티브 기능을 위해, API 개요 API Overview의 구현 상세 내용은 소개 Introduction의 구현 상세 내용은 API 키 API Keys의 구현 세부 사항은, 디바이스 Devices의 구현 세부 사항은.