https://github.com/kdroidfilter/composemediaplayer
Compose Media Player is a video player library designed for Compose Multiplatform, supporting multiple platforms including Android, macOS, Windows, Linux, iOS and Compose Web (Wasm)
https://github.com/kdroidfilter/composemediaplayer
android audio-visualization compose-desktop compose-ios compose-multiplatform customizable-ui ios jetpack-compose kotlin linux macos media-controls multiplatform open-source video-player windows
Last synced: 29 days ago
JSON representation
Compose Media Player is a video player library designed for Compose Multiplatform, supporting multiple platforms including Android, macOS, Windows, Linux, iOS and Compose Web (Wasm)
- Host: GitHub
- URL: https://github.com/kdroidfilter/composemediaplayer
- Owner: kdroidFilter
- License: mit
- Created: 2025-01-17T06:29:26.000Z (4 months ago)
- Default Branch: master
- Last Pushed: 2025-04-06T04:52:07.000Z (about 1 month ago)
- Last Synced: 2025-04-06T05:24:28.892Z (about 1 month ago)
- Topics: android, audio-visualization, compose-desktop, compose-ios, compose-multiplatform, customizable-ui, ios, jetpack-compose, kotlin, linux, macos, media-controls, multiplatform, open-source, video-player, windows
- Language: Kotlin
- Homepage: https://kdroidfilter.github.io/ComposeMediaPlayer/
- Size: 12 MB
- Stars: 121
- Watchers: 1
- Forks: 8
- Open Issues: 7
-
Metadata Files:
- Readme: README.MD
- License: LICENSE
Awesome Lists containing this project
README
# 🎥 Compose Media Player
**Compose Media Player** is a video player library designed for Compose Multiplatform, supporting multiple platforms including Android, macOS, Windows, and Linux. It is the first fully functional multiplatform video player for Compose for Desktop that requires no additional software installations. The library leverages:
- **GStreamer** for Linux
- **Media Foundation** for Windows
- **AVPlayer** for macOS and iOS
- **Media3** for Android
- **HTML5 Player** for WASMJS
## 🚀 Live Demo
Try the online demo here : [🎥 Live Demo](https://kdroidfilter.github.io/ComposeMediaPlayer/sample/)
## ✨ Features
- **Multiplatform Support**: Works seamlessly on Android, macOS, Windows, Linux and Compose Web (Wasm).
- **File and URL Support**: Play videos from local files or directly from URLs.
- **Media Controls**: Includes play, pause, loop toggle, volume control, loop playback and timeline slider.
- **Custom Video Player UI**: Fully customizable using Compose Multiplatform.
- **Audio Levels**: Displays left and right audio levels in real time.
- **Error handling** Simple error handling for network or playback issues.
## ✨ Supported Video Formats
| Format | Windows | Linux | macOS & iOS | Android | WasmJS |
|--------|-------------------------------------------------------------------------------------------------------------------|-------------------|-----------------------------------------------------------------------------|-----------------|-------------------|
| **Player** | [MediaFoundation](https://learn.microsoft.com/en-us/windows/win32/medfound/microsoft-media-foundation-sdk) | [GStreamer](https://gstreamer.freedesktop.org/) | [AVPlayer](https://developer.apple.com/documentation/avfoundation/avplayer) | [Media 3](https://developer.android.com/media/media3) | [HTML5 Video](https://www.w3schools.com/html/html5_video.asp) |
| MP4 (H.264) | ✅ | ✅ | ✅ | ✅ | ✅ |
| AVI | ❌ | ✅ | ❌ | ❌ | ❌ |
| MKV | ❌ | ✅ | ❌ | ✅ | ❌ |
| MOV | ✅ | ✅ | ✅ | ❌ | ✅ |
| FLV | ❌ | ✅ | ❌ | ❌ | ❌ |
| WEBM | ❌ | ✅ | ❌ | ✅ | ✅ |
| WMV | ✅ | ✅ | ❌ | ❌ | ❌ |
| 3GP | ✅ | ✅ | ✅ | ✅ | ❌ |
## 🔧 Installation
To add Compose Media Player to your project, include the following dependency in your `build.gradle.kts` file:
```kotlin
dependencies {
implementation("io.github.kdroidfilter:composemediaplayer:0.6.0")
}
```
## 🚀 Getting Started
### Initialization
Before using Compose Media Player, you need to create a state for the video player using the `rememberVideoPlayerState` function:
```kotlin
val playerState = rememberVideoPlayerState()
```
### Displaying the Video Surface
After initializing the player state, you can display the surface of the video using `VideoPlayerSurface`:
```kotlin
// Video Surface
Box(
modifier = Modifier.weight(1f).fillMaxWidth(),
contentAlignment = Alignment.Center
) {
VideoPlayerSurface(
playerState = playerState,
modifier = Modifier.fillMaxSize()
)
}
```
### Video Playback via URL or Local Files
You can play a video by providing a direct URL:
```kotlin
playerState.openUri("http://example.com/video.mp4")
```
To play a local video file you can use [PlatformFile](https://filekit.mintlify.app/core/platform-file) from [FileKit](https://github.com/vinceglb/FileKit).
```kotlin
val file = FileKit.openFilePicker(type = FileKitType.Video)
file?.let { playerState.openFile(file) }
```
Check the [sample project](sample/composeApp/src/commonMain/kotlin/sample/app/App.kt) for a complete example.
### Full Controls
- **Play and Pause**:
You can detect the current playback state via `playerState.isPlaying` and configure a Play/Pause button as follows:
```kotlin
Button(onClick = {
if (playerState.isPlaying) {
playerState.pause()
println("Playback paused")
} else {
playerState.play()
println("Playback started")
}
}) {
Text(if (playerState.isPlaying) "Pause" else "Play")
}
```
- **Stop**:
```kotlin
playerState.stop()
println("Playback stopped")
```
- **Volume**:
```kotlin
playerState.volume = 0.5f // Set volume to 50%
println("Volume set to 50%")
```
- **Loop Playback**:
```kotlin
playerState.loop = true // Enable loop playback
println("Loop playback enabled")
```
### Progress Indicators
To display and control playback progress:
```kotlin
Slider(
value = playerState.sliderPos,
onValueChange = {
playerState.sliderPos = it
playerState.userDragging = true
println("Position changed: $it")
},
onValueChangeFinished = {
playerState.userDragging = false
playerState.seekTo(playerState.sliderPos)
println("Position finalized: ${playerState.sliderPos}")
},
valueRange = 0f..1000f
)
```
### Display Left and Right Volume Levels
To display audio levels:
```kotlin
println("Left level: ${playerState.leftLevel.toInt()}%, Right level: ${playerState.rightLevel.toInt()}%")
```
> [!IMPORTANT]
> This feature is not working on iOS.
### Error Handling
In case of an error, you can display it using `println`:
```kotlin
playerState.error?.let { error ->
println("Error detected: ${error.message}")
playerState.clearError()
}
```
### Loading Indicator
To detect if the video is buffering:
```kotlin
if (playerState.isLoading) {
CircularProgressIndicator()
}
````
### Using Subtitles
Compose Media Player supports adding subtitles from both URLs and local files.
> [!IMPORTANT]
> This feature is actually not supported on Windows, Mac and iOS.
#### 🎯 Adding Subtitles from url or local file
You can add subtitles by specifying a URL:
```kotlin
val track = SubtitleTrack(
label = "English Subtitles",
language = "en",
src = "https://example.com/subtitles.vtt"
)
playerState.selectSubtitleTrack(track)
```
#### ❌ Disabling Subtitles
To disable subtitles:
```kotlin
playerState.disableSubtitles()
```
### 📋 Basic Example
Here is a minimal example of how to integrate the Compose Media Player into your Compose application with a hardcoded URL:
```kotlin
@Composable
fun App() {
val playerState = rememberVideoPlayerState()
MaterialTheme {
Column(modifier = Modifier.fillMaxSize().padding(8.dp)) {
// Video Surface
Box(
modifier = Modifier.weight(1f).fillMaxWidth(),
contentAlignment = Alignment.Center
) {
VideoPlayerSurface(
playerState = playerState,
modifier = Modifier.fillMaxSize()
)
}
Spacer(modifier = Modifier.height(8.dp))
// Playback Controls
Row(horizontalArrangement = Arrangement.SpaceBetween, modifier = Modifier.fillMaxWidth()) {
Button(onClick = { playerState.play() }) { Text("Play") }
Button(onClick = { playerState.pause() }) { Text("Pause") }
}
Spacer(modifier = Modifier.height(8.dp))
// Open Video URL
Button(
onClick = {
val url = "http://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4"
playerState.openUri(url)
}
) {
Text("Open Video")
}
Spacer(modifier = Modifier.height(8.dp))
// Volume Control
Text("Volume: ${(playerState.volume * 100).toInt()}%")
Slider(
value = playerState.volume,
onValueChange = { playerState.volume = it },
valueRange = 0f..1f
)
}
}
}
```
## 📄 License
Compose Media Player is licensed under the MIT License. See [LICENSE](LICENSE) for details.
## 📊 Roadmap
- **Audio Player**: Introduce a standalone audio player for handling audio-only content.
- **Player with Separate Audio and Video Streams**: Add functionality to support different audio and video streams for advanced playback scenarios.
- **Metadata Support**: Add support for extracting the following metadata:
- Title
- Artist
- Duration (in milliseconds)
- Video resolution (width and height)
- Bitrate (in bits per second)
- Frame rate
- MIME type
- Audio channels
- Audio sample rate
## 🟎️ Screenshots of the [Demo App](sample/composeApp/src/commonMain/kotlin/sample/app/App.kt)
### Windows
### Linux
### Android
