Compose Media Player

Compose Media Player is a video player library designed for Compose Multiplatform. It provides a unified API to play video across Android, macOS, Windows, Linux, and Compose Web (Wasm).

Key architectural details:

• Desktop Platforms: Communicates with native backends via pure JNI (no JNA or external runtime dependencies like GStreamer Java bindings required).
• Platform Backends:
  • Linux: GStreamer (via JNI)
  • Windows: Media Foundation (via JNI)
  • macOS & iOS: AVPlayer (via JNI)
  • Android: Media3
  • WasmJS: HTML5 Player

Compose Media Player provides two specialized modules for Compose Multiplatform applications:

• composemediaplayer (Video): A comprehensive video playback solution. It handles the video surface, subtitles, and metadata, utilizing platform-native backends for high performance. It is designed for full media integration within Compose UI.
• composemediaplayer-audio (Audio): A lightweight alternative focused strictly on audio. It provides essential playback controls such as play, pause, stop, seek, and volume without the overhead of video rendering.

While HLS is supported natively on most platforms, Android requires an additional ExoPlayer HLS module dependency to enable HLS (M3U8) playback.

implementation("androidx.media3:media3-exoplayer-hls:<version>")

Compose Media Player is split into two distinct modules depending on your requirements. Choose the module that matches your use case:

1. Video player (composemediaplayer): Use this for full video playback including Compose UI integration, subtitles, and metadata support.
2. Audio player (composemediaplayer-audio): Use this for lightweight, audio-only playback (play, pause, stop, seek, volume).

// For Video playback
dependencies {
    implementation("io.github.kdroidfilter:composemediaplayer:<version>")
}

// For Audio-only playback
dependencies {
    implementation("io.github.kdroidfilter:composemediaplayer-audio:<version>")
}

To use Compose Media Player, you must first create a player state using the rememberVideoPlayerState function. This state object manages playback, configuration, and lifecycle.

val playerState = rememberVideoPlayerState()

Add the audio module dependency to your build.gradle.kts file. Replace <version> with the latest available version.

dependencies {
    implementation("io.github.kdroidfilter:composemediaplayer-audio:<version>")
}

To use the Compose Media Player in your project, add the following dependency to your build.gradle.kts file. Replace <version> with the latest available version.

dependencies {
    implementation("io.github.kdroidfilter:composemediaplayer:<version>")
}

PiP is supported on Android (8.0+) and iOS. It is a no-op on Desktop and Web.

Implementation

1. Check support via playerState.isPipSupported.
2. Enable automatic PiP on backgrounding via playerState.isPipEnabled = true (Android).
3. On Android, use the AutoPipEffect(playerState) composable and forward changes in your Activity's onPictureInPictureModeChanged method.

// Android Activity requirement
override fun onPictureInPictureModeChanged(isInPipMode: Boolean, newConfig: Configuration) {
    super.onPictureInPictureModeChanged(isInPipMode, newConfig)
    DefaultVideoPlayerState.onPictureInPictureModeChanged(isInPipMode)
}

// Composable usage
AutoPipEffect(playerState)

You can enable disk-based caching for videos opened via openUri(). This is useful for scroll-based UIs like TikTok/Reels. The cache uses an LRU (Least Recently Used) eviction policy.

Note: Caching only applies to URIs; local files and assets are not cached. The cache is shared across all player instances.

val playerState = rememberVideoPlayerState(
    cacheConfig = CacheConfig(
        enabled = true,
        maxCacheSizeBytes = 200L * 1024L * 1024L // 200 MB
    )
)

// Clear cache
playerState.clearCache()

Control how the player interacts with other apps' audio. This is only effective on Android and iOS.

// Mix with other apps' audio
val playerState = rememberVideoPlayerState(
    audioMode = AudioMode(interruptionMode = InterruptionMode.MixWithOthers)
)

// Duck other apps' audio (lower their volume)
val playerState = rememberVideoPlayerState(
    audioMode = AudioMode(interruptionMode = InterruptionMode.DuckOthers)
)

The MacVideoPlayerState class is the macOS-specific implementation of the VideoPlayerState interface. It manages media playback using a native AVFoundation player via a native bridge. It handles frame production, playback synchronization, and metadata extraction.

Key features include:

• Automatic Aspect Ratio Correction: Unlike the Windows implementation, macOS uses AVFoundation's display aspect ratio to ensure anamorphic content renders correctly.
• Triple-Buffered Rendering: Uses Skia bitmaps with triple-buffering to prevent screen tearing during high-resolution playback.
• Smooth Timeline: Uses a dedicated polling loop for the AVPlayer clock to ensure the playback slider moves smoothly even if frame delivery is irregular.

val playerState: VideoPlayerState = MacVideoPlayerState()