@capgo/capacitor-mux-player

Documentation

The most complete doc is available here: https://capgo.app/docs/plugins/mux-player/

Compatibility

| Plugin version | Capacitor compatibility | Maintained | | -------------- | ----------------------- | ---------- | | v8.*.* | v8.*.* | ✅ | | v7.*.* | v7.*.* | On demand | | v6.*.* | v6.*.* | ❌ | | v5.*.* | v5.*.* | ❌ |

Note: The major version of this plugin follows the major version of Capacitor. Use the version that matches your Capacitor installation (e.g., plugin v8 for Capacitor 8). Only the latest major version is actively maintained.

Install

You can use our AI-Assisted Setup to install the plugin. Add the Capgo skills to your AI tool using the following command:

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

Then use the following prompt:

Use the `capacitor-plugins` skill from `cap-go/capacitor-skills` to install the `@capgo/capacitor-mux-player` plugin in my project.

If you prefer Manual Setup, install the plugin by running the following commands and follow the platform-specific instructions below:

npm install @capgo/capacitor-mux-player
npx cap sync

iOS setup

• Requires iOS 15 or newer.
• Add the Swift package https://github.com/muxinc/mux-player-swift to your Xcode workspace so that the MuxPlayerSwift module is available at build time.
• If you manage native dependencies through CocoaPods, prefer integrating this plugin via Swift Package Manager or add the Mux package manually to your app target.

Android setup

• Gradle pulls the player from the Mux artifactory (https://muxinc.jfrog.io/artifactory/default-maven-release-local). Ensure your corporate proxy allows downloads from that host.
• npx cap sync android adds the Mux Maven repository to android/build.gradle automatically. If Capacitor lifecycle hooks are disabled in your project, add that repository manually to the root Gradle configuration (android/build.gradle).
• The plugin uses Kotlin 2.2.20 and resolves Media3 transitively through the Mux artifact.
• Android apps targeting SDK 33 or newer will also see android.permission.POST_NOTIFICATIONS merged from this library. The plugin does not request notifications at runtime; the manifest entry prevents Android lint failures caused by Mux's Glide NotificationTarget dependency. If your app does not need that permission, remove it from your app manifest with:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools">
    <uses-permission
        android:name="android.permission.POST_NOTIFICATIONS"
        tools:node="remove" />
</manifest>

Web setup

• The plugin bundles @mux/mux-player and renders the video in a fullscreen overlay. The player automatically injects a close affordance for desktop and mobile browsers.

API

• play(...)
• dismiss()
• isActive()
• removeAllListeners()
• addListener(E, ...)
• Interfaces

play(...)

play(options: MuxPlayOptions) => Promise<void>

Launch the native Mux Player in fullscreen and begin playback.

| Param | Type | | ------------- | --------------------------------------------------------- | | options | MuxPlayOptions |

dismiss()

dismiss() => Promise<void>

Dismiss the player if it is visible.

isActive()

isActive() => Promise<{ active: boolean; }>

Returns whether the player is currently being displayed.

Returns: Promise<{ active: boolean; }>

removeAllListeners()

removeAllListeners() => Promise<void>

Remove all event listeners registered on the plugin instance.

addListener(E, ...)

addListener<E extends keyof MuxPlayerEvents>(eventName: E, listenerFunc: (event: MuxPlayerEvents[E]) => void) => Promise<PluginListenerHandle>

Listen to player lifecycle or playback events emitted by the plugin.

| Param | Type | | ------------------ | --------------------------------------------------- | | eventName | E | | listenerFunc | (event: MuxPlayerEvents[E]) => void |

Returns: Promise<PluginListenerHandle>

Interfaces

MuxPlayOptions

| Prop | Type | Description | | ---------------------- | -------------------- | ------------------------------------------------------------------------------------ | | playbackId | string | The playback ID of the asset you want to stream. | | playbackToken | string | Provide a JSON web token generated for signed playback policies. | | drmToken | string | Provide a JSON web token generated for DRM playback policies. | | customDomain | string | Override the default Mux playback domain (e.g. stream.example.com). | | autoPlay | boolean | Auto-play when the player becomes visible. Defaults to true. | | startTime | number | Start playback from the provided time (in seconds). | | poster | string | Provide a poster image URL to display before playback begins. | | title | string | Provide a custom title to surface in native player chrome when available. | | subtitle | string | Provide a subtitle or description to surface in native player chrome when available. | | muted | boolean | Set to true to keep the video muted when playback starts. | | environmentKey | string | Mux Data environment key used for analytics. If omitted, the SDK default is used. | | playerName | string | Provide an explicit player name for analytics. Defaults to a generated name. | | enableSmartCache | boolean | Enable smart caching when the underlying SDK supports it. | | debug | boolean | Enable verbose logging in native SDKs where available. |

PluginListenerHandle

| Prop | Type | | ------------ | ----------------------------------------- | | remove | () => Promise<void> |

MuxPlayerEvents

| Prop | Type | Description | | --------------------- | ------------------------------------- | ------------------------------------------------------------ | | ready | { playerName?: string; } | Fired when the underlying player is ready to begin playback. | | play | void | Fired when playback starts or resumes. | | pause | void | Fired when playback pauses. | | ended | void | Fired when playback ends. | | error | { message: string; } | Fired when an unrecoverable error occurs. | | playerDismissed | void | Fired when the fullscreen player is closed. |

| Method | Signature | Description | | -------------------- | -------------------------------------------- | --------------------------------------- | | getPluginVersion | () => Promise<{ version: string; }> | Get the native Capacitor plugin version |