Guida rapida

Installazione

Puoi usare il nostro Setup assistito dall'AI per installare il plugin. Aggiungi le skill Capgo al tuo tool AI con il comando seguente:

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

Poi usa questo prompt:

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

Se preferisci il Setup manuale, installa il plugin eseguendo i comandi seguenti e segui le istruzioni specifiche per piattaforma qui sotto:

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

Importa

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

Avvio rapido

Pubblica i metadati e lo stato di riproduzione all'avvio del player.

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,
});

Esempio: gestire i controlli della lock screen

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;
  }
});

Passa null come handler per annullare la registrazione di un'azione.

Esempio: stato di pausa durante il buffering

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

Errori comuni

• Mantieni la posizione aggiornata: chiama setPositionState man mano che la riproduzione avanza, altrimenti lo scrubbing su Android sembrerà rotto.
• URL delle immagini: usa asset HTTPS raggiungibili dal dispositivo; le immagini troppo grandi rallentano gli aggiornamenti della lock screen.
• Ciclo di vita dell'handler: registra gli handler una sola volta al setup del player, non a ogni cambio di traccia.

API Panoramica

setMetadata

Imposta i metadati del media in riproduzione.

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

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

setPlaybackState

Aggiorna lo stato di riproduzione della media session.

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

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

setActionHandler

Registra un handler per un'azione della media session.

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

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

setPositionState

Aggiorna lo stato della posizione per la media session attiva.

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

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

Riferimento ai tipi

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

Fonte di verità

Questa pagina è generata dal src/definitions.ts. Riesegui la sync quando il API pubblico cambia upstream.

Continua da Getting Started

Se stai usando Guida rapida per pianificare dashboard e operazioni API, collegalo a Utilizzo di @capgo/capacitor-media-session per la funzionalità nativa in Utilizzo di @capgo/capacitor-media-session, API Panoramica per i dettagli di implementazione in Panoramica API, Introduzione per i dettagli di implementazione in Introduzione, Chiavi API per i dettagli di implementazione in Chiavi API, e Dispositivi per i dettagli di implementazione in Dispositivi.