Compose Multiplatform Media Player

Compose Multiplatform Media Player is a powerful media player library designed for Compose Multiplatform projects. It enables seamless video player, reels viewing, audio playing, YouTube video integration, video preview thumbnails and HLS m3u8 support on iOS, Android, wasmJs and Desktop platforms. The library offers extensive customization options for various controls, making it flexible for different types of media applications.

🎉 What's New in Version 1.0.53

Customization Option Added

• showControlsOverride: Overrides the internal control visibility state.

✨ Features

Cross-Platform Compatibility: Works seamlessly on iOS, Android, wasmJs and Desktop platforms within Compose Multiplatform projects.

Video Player: Effortlessly play videos in your app with high performance and reliability.

HLS m3u8 Playback: Seamlessly stream live and on-demand content with HLS (.m3u8), featuring quality, caption, and audio track selection for a customizable viewing experience.

YouTube Player: Integrate YouTube videos directly into your app, with full control over playback and video state management.

Reel Viewing: Enjoy reel viewing with support for horizontal and vertical scrolling.

Audio Player: Enjoy high-quality audio playback with customizable controls.

Video Preview: Display animated video previews for a more engaging experience.

Customizable Controls: Enable/disable pause/resume functionality and adjust the appearance and visibility of the seek bar, along with various control icons and colors.

Resume Video Playback: Automatically resume video playback from the last position.

Picture-in-Picture: Seamless PiP support on mobile, allowing video playback to continue in a floating window while users multitask.

📦 Installation

Add the following dependency to your build.gradle.kts file:

commonMain.dependencies {
    implementation("network.chaintech:compose-multiplatform-media-player:1.0.53")
}

💡 Note: For desktop video player, ensure VLC Player is installed, and for desktop YouTube support, Java must be installed on your system.

🌐 Setup for wasmJs (WebAssembly)

⚠️ Experimental Notice

The WebAssembly (wasmJs) target in JetBrains Compose Multiplatform is still in experimental status. While this library provides preliminary support using Shaka Player for media playback, stability, performance, and feature parity may vary between browsers.

Use this feature for testing, prototyping, or early adoption — not production-critical scenarios yet.

To enable wasmJs support with Shaka Player, you need to include the supporting files shipped with this library.

All required files are available here:

Add Scripts in index.html

Make sure to add these scripts before your Compose WASM app (composeApp.js).

⚠️ The order matters: Shaka → Global → Helpers → Compose app.

<!-- Shaka Player -->
<script src="shaka-player.compiled.js"></script>
<script src="shaka-global.js"></script>

<!-- WASM Helpers -->
<script src="shaka-wasm-helpers.js"></script>

<!-- Your Compose WASM app -->
<script src="composeApp.js"></script>

📦 Setup for Picture-in-Picture (PiP)

🤖 Android

Before using PiP mode in your media player, you need to enable it in your app’s AndroidManifest.xml.

Add the following flags inside your <activity> (usually MainActivity):

<activity
    android:name=".MainActivity"
    android:supportsPictureInPicture="true"
    android:resizeableActivity="true"
    android:configChanges="screenSize|smallestScreenSize|screenLayout|orientation|keyboardHidden"/>

📱 iOS

In Xcode, enable Background Modes capability.

Check ✅ Audio, AirPlay, and Picture in Picture.

📦 Setup for Resuming Video Playback in Android

If you want to enable the feature to resume video playback from the last saved position, you need to initialize PlaybackPreference in your Android app. Add the following setup in your AppActivity:

class AppActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        PlaybackPreference.initialize(this)
    }
}

This ensures that playback positions are properly saved and retrieved when needed. Without this initialization, the resume feature will not work on Android. 🚀

📋 Setup Guide for Fullscreen Support in Desktop

To enable fullscreen and window placement control from the library, you need to provide your app's WindowState using CompositionLocalProvider.

For example:

fun main() = application {
    val windowState = rememberWindowState(width = 900.dp, height = 700.dp)
    CompositionLocalProvider(LocalWindowState provides windowState) {
        Window(
            title = "MediaPlayer",
            state = windowState,
            onCloseRequest = ::exitApplication,
        ) {
            MainView()
        }
    }
}

🎬 Usage

MediaPlayerHost Class

Constructor Parameters

• mediaUrl (String): The URL of the media to be played.
• autoPlay (Boolean): Sets the initial playback state. Defaults to true (play on load).
• isMuted (Boolean): Indicates whether the video is muted initially. Defaults to false.
• initialSpeed (PlayerSpeed): Sets the initial playback speed. Defaults to PlayerSpeed.X1.
• initialVideoFitMode (ScreenResize): Specifies the video resizing mode. Defaults to ScreenResize.FILL.
• isLooping (Boolean): Enables or disables looping. Defaults to true.
• startTimeInSeconds (Float?): Optionally specifies the start time (in seconds) for the video. Defaults to null.
• isFullScreen (Boolean): Enables or disables full screen. Defaults to false.
• headers (Map<String, String>?): Optional HTTP headers to be sent with the media request. Defaults to null.
• drmConfig (DrmConfig?): Optional DRM configuration for protected content. Defaults to null. Supports ClearKey Encryption DRM for playing encrypted media.

Available Controls

• loadUrl(mediaUrl: String, headers: Map<String, String>? = null, drmConfig: DrmConfig? = null): Updates the media URL to load a new media. Optionally, you can pass HTTP headers and DRM configuration
• play(): Resumes media playback.
• pause(): Pauses media playback.
• togglePlayPause(): Toggles between play and pause states.
• mute(): Mutes the video.
• unmute(): Unmutes the video.
• toggleMuteUnmute(): Toggles between muted and unmuted states.
• setSpeed(speed: PlayerSpeed): Adjusts the playback speed.
• seekTo(seconds: Float?): Seeks to a specific time in the media.
• setVideoFitMode(mode: ScreenResize): Updates the video resizing mode.
• setLooping(isLooping: Boolean): Enables or disables looping.
• toggleLoop(): Toggles loop state.
• setVolume(level: Float): Adjusts the volume. Value must be between 0.0 and 1.0.
• setFullScreen(isFullScreen: Boolean): Enables or disables full screen.
• toggleFullScreen(): Toggles full screen enable/disable states.

Internal Updates and Events

The MediaPlayerHost class manages internal state changes and triggers events via the onEvent callback. These events allow developers to monitor and respond to changes in the media player state:

| Event | Description | |-----------------------------------------|---------------------------------------------------------------------------------| | PauseChange(isPaused: Boolean) | Triggered when the playback state changes (play or pause). | | MuteChange(isMuted: Boolean) | Triggered when the mute state changes (mute or unmute). | | BufferChange(isBuffering: Boolean) | Triggered when the buffering state changes (e.g., when buffering starts/stops). | | TotalTimeChange(totalTime: Float) | Triggered when the total duration of the video updates. | | CurrentTimeChange(currentTime: Float) | Triggered when the current playback position updates. | | FullScreenChange(isFullScreen: Boolean) | Triggered when the full screen state changes. | | MediaEnd | Triggered when the media playback completes. | | PIPChange(isPip: Boolean) | Triggered when the PIP Mode changes. |

Error Handling

The MediaPlayerHost class provides an onError callback to handle various errors that may occur during media playback.

| Error Type | Description | |-----------------------