capacitor-media-session

Capacitor plugin for Media Sessions on Web, Android and iOS. Just like the Media Session Web API this enables

• customizable media playback notifications (including controls) on iOS, Android and some browsers
• media control using hardware media keys (e.g. on headsets, remote controls, etc.)
• setting media metadata that can be used by the platform UI

This plugin is necessary for Capacitor apps because the Android WebView does not support the Media Session Web API (if you don't need Android support you could just use the Web API directly on Web and iOS). On Web and iOS this plugin is actually just a very thin wrapper around the Web API and uses it directly, only Android needs a native implementation.

Another problem with audio playback (using web standards, e.g. an <audio> element) in Capacitor apps on Android is that it does not work reliably in the background. If your app is in the background Android will force your app to go to sleep even if audio is currently playing in the WebView. This plugin also tries to solve this problem by starting a foreground service for active Media Sessions enabling background playback.

Install

If you are using Capacitor 5 just install the latest 3.x version of this plugin using

npm install @jofr/capacitor-media-session
npx cap sync

For Capacitor 4 you can install the 2.x version of this plugin instead (npm install @jofr/capacitor-media-session@2) and for Capacitor 3 the 1.x version of this plugin (npm install @jofr/capacitor-media-session@1).

Usage

The API of this plugin is modeled after the already widely supported Media Session Web API. That way most available documentation for this web standard should be easily adaptable to this Capacitor plugin and it should be easy to use if you are already familiar with it. If your are not yet familiar with the concepts you can read more about that on MDN or on web.dev.

There is one notable difference compared to the Web API: You have to explicitly set the playback state to "playing" (using setPlaybackState()) for the notification to start showing. You also have to explicitly set action handlers for play/pause (using setActionHandler()) for the controls in the notification to show up and work. For simple cases on the Web platform (e.g. playing audio using an <audio> element) the browser detects playback and wires simple actions like play/pause automatically up. Using this plugin you have to wire up the <audio> element manually because the plugin cannot detect audio playback in the WebView on Android automatically. There is an example app included in the repository that shows how to do that.

API

• setMetadata(...)
• setPlaybackState(...)
• setActionHandler(...)
• setPositionState(...)
• Interfaces
• Type Aliases

setMetadata(...)

setMetadata(options: MetadataOptions) => Promise<void>

Sets metadata of the currently playing media. Analogue to setting the metadata property of the MediaSession interface when using the Media Session API directly.

| Param | Type | | ------------- | ----------------------------------------------------------- | | options | MetadataOptions |

setPlaybackState(...)

setPlaybackState(options: PlaybackStateOptions) => Promise<void>

Indicate whether media is playing or not. Analogue to setting the playbackState property of the MediaSession interface when using the Media Session API directly.

| Param | Type | | ------------- | --------------------------------------------------------------------- | | options | PlaybackStateOptions |

setActionHandler(...)

setActionHandler(options: ActionHandlerOptions, handler: ActionHandler | null) => Promise<void>

Sets handler for media session actions (e.g. initiated via onscreen media controls or physical buttons). Analogue to calling setActionHandler() of the MediaSession interface when using the Media Session API directly.

| Param | Type | | ------------- | --------------------------------------------------------------------- | | options | ActionHandlerOptions | | handler | ActionHandler | null |

setPositionState(...)

setPositionState(options: PositionStateOptions) => Promise<void>

Update current media playback position, duration and speed. Analogue to calling setPositionState() of the MediaSession interface when using the Media Session API directly.

| Param | Type | | ------------- | --------------------------------------------------------------------- | | options | PositionStateOptions |

Interfaces

MetadataOptions

| Prop | Type | | ------------- | ------------------- | | album | string | | artist | string | | artwork | any[] | | title | string |

PlaybackStateOptions

| Prop | Type | | ------------------- | -------------------------------------- | | playbackState | MediaSessionPlaybackState |

ActionHandlerOptions

| Prop | Type | | ------------ | ------------------------------- | | action | MediaSessionAction |

ActionDetails

| Prop | Type | | -------------- | ------------------------------- | | action | MediaSessionAction | | seekTime | number | null |

PositionStateOptions

| Prop | Type | | ------------------ | ------------------- | | duration | number | | playbackRate | number | | position | number |

Type Aliases

ActionHandler

(details: ActionDetails): void