capacitor-media-session-control

Capacitor plugin for controlling media playback via Android MediaSession API. Provides advanced integration with lock screen controls, notification controls, and hardware media buttons.

✨ Features

• Play, pause, seek, stop, and skip tracks
• Show playback information (title, artist, album, cover, duration)
• Sync playback position with UI
• Integration with Android notifications (media style)
• Reacts to hardware media buttons (headphones, Bluetooth, etc.)

Demo

• Link to demo

Install

npm install capacitor-media-session-control
npx cap sync

Config for IOS

Add this code to: ios/App/App/Info.plist

<key>UIBackgroundModes</key>
<array>
    <string>audio</string>
</array>

API

• initMediaSession(...)
• play()
• pause()
• stop()
• next()
• previous()
• seekTo(...)
• updateMetadata(...)
• updatePlaybackState(...)
• addListener('mediaSessionEvent', ...)
• Interfaces
• Type Aliases

initMediaSession(...)

initMediaSession(options: InitOptions) => Promise<void>

Init Media Session API and notification

| Param | Type | | ------------- | --------------------------------------------------- | | options | InitOptions |

play()

play() => Promise<void>

Start playback

pause()

pause() => Promise<void>

Pause playback

stop()

stop() => Promise<void>

Stop playback and remove notification

next()

next() => Promise<void>

Next track

previous()

previous() => Promise<void>

Previous track

seekTo(...)

seekTo(options: SeekToOptions) => Promise<void>

Seek to position

| Param | Type | | ------------- | ------------------------------------------------------- | | options | SeekToOptions |

updateMetadata(...)

updateMetadata(options: UpdateMetadataOptions) => Promise<void>

Update metadata (title, artist, album, cover, duration)

| Param | Type | | ------------- | ----------------------------------------------------------------------- | | options | UpdateMetadataOptions |

updatePlaybackState(...)

updatePlaybackState(options: UpdatePlaybackStateOptions) => Promise<void>

Update playback state (state, position, playbackSpeed)

| Param | Type | | ------------- | --------------------------------------------------------------------------------- | | options | UpdatePlaybackStateOptions |

addListener('mediaSessionEvent', ...)

addListener(eventName: "mediaSessionEvent", listenerFunc: (event: MediaSessionEventPayload) => void) => Promise<{ remove: () => void; }>

Add listener for media session events

| Param | Type | | ------------------ | ------------------------------------------------------------------------------------------------- | | eventName | 'mediaSessionEvent' | | listenerFunc | (event: MediaSessionEventPayload) => void |

Returns: Promise<{ remove: () => void; }>

Interfaces

InitOptions

| Prop | Type | | ---------------- | -------------------- | | title | string | | artist | string | | album | string | | cover | string | | duration | number | | position | number | | isPlaying | boolean | | targetPage | string |

SeekToOptions

| Prop | Type | | -------------- | ------------------- | | position | number |

UpdateMetadataOptions

| Prop | Type | | -------------- | ------------------- | | title | string | | artist | string | | album | string | | cover | string | | duration | number |

UpdatePlaybackStateOptions

| Prop | Type | | ------------------- | ----------------------------------------------- | | state | 'playing' | 'paused' | 'stopped' | | position | number | | playbackSpeed | number |

MediaSessionEventPayload

| Prop | Type | | -------------- | --------------------------------------------------------------- | | event | MediaSessionEvent | | position | number | | data | { targetPage?: string; } |

Type Aliases

MediaSessionEvent

"play" | "pause" | "stop" | "next" | "previous" | "seekTo" | "openApp" | "notificationDismissed" | "appClosed"