Primeros pasos

Instalar

Puedes usar nuestro setup asistido por IA para instalar el plugin. Añade las skills de Capgo a tu herramienta de IA con el siguiente comando:

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

Luego usa el siguiente prompt:

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

Si prefieres la configuración manual, instala el plugin ejecutando los siguientes comandos y sigue las instrucciones específicas para cada plataforma a continuación:

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

Importar

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

Inicio rápido

Publica metadatos y el estado de reproducción al iniciar el reproductor.

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

Ejemplo: gestionar controles de la pantalla de bloqueo

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

Pasa null como handler para desregistrar una acción.

Ejemplo: estado de pausa al cargar (buffering)

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

Errores comunes

• Mantén la posición actualizada: llamar a setPositionState si la reproducción avanza o se hace scrubbing, se sentirá roto en Android.
• URLs de Artwork: usa assets HTTPS accesibles desde el dispositivo; las imágenes grandes ralentizan los updates de la pantalla de bloqueo.
• Ciclo de vida del handlerregistra los handlers una sola vez al configurar el player, no en cada cambio de track.

Resumen de API

setMetadata

Sets metadata of the currently playing media.

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

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

setPlaybackState

Actualiza el estado de reproducción de la sesión multimedia.

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

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

setActionHandler

Registra un handler para una acción de la sesión multimedia.

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

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

setPositionState

Actualiza el estado de posición de la sesión multimedia activa.

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

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

Referencia de tipos

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

Fuente de verdad

Esta página se genera a partir del src/definitions.tsVuelve a ejecutar la sincronización cuando cambie el API público en el upstream.

Continúa desde Primeros pasos

Si estás usando Primeros pasos para planificar el dashboard y las operaciones de API, conéctalo con Uso de @capgo/capacitor-media-session para la capacidad nativa en Uso de @capgo/capacitor-media-session, Resumen de API para el detalle de implementación en Resumen de API Overview, Introducción para el detalle de implementación en Introducción, Claves de API para el detalle de implementación en Claves de API, y Dispositivos para el detalle de implementación en Dispositivos.