cmp-videoplayer is an OSS Compose Multiplatform video player component that focuses on one responsibility: playing video files across targets.

Supported targets:

• Android (Media3 ExoPlayer)
• iOS (AVPlayer)
• Desktop/JVM (mediamp + VLC)
• Web (wasmJs; HTML5 <video>)

Non-goals:

• Embedded providers (YouTube/Vimeo/iframes)
• Poster/image loading (use the placeholder slot)

Wasm Demo:

API Docs:

Add the dependency to your commonMain:

kotlin {
  sourceSets {
    commonMain.dependencies {
      implementation("io.github.aryapreetam:cmp-videoplayer:<version>")
    }
  }
}

@Composable
fun MyScreen() {
  VideoPlayer(
    source = VideoSource.Url("https://example.com/video.mp4"),
    config = VideoPlayerConfig(
      autoplay = false,
      showControls = true,
    )
  )
}

• VideoSource.Url(url) supports http(s)://, file://, and on Android also content:// and android.resource://.
• VideoSource.Path(path) is a raw filesystem path (Android/iOS/JVM). On wasm, use Url.

On wasmJs, the HTML <video> element needs a URL. If your video is only available via Compose resources (Res.raw.*), use rememberBlobVideoUrl:

@Composable
fun ResourceVideo(bytes: ByteArray) {
  // `mimeType` is explicit by design.
  val url = rememberBlobVideoUrl(bytes, mimeType = "video/mp4")
  VideoPlayer(VideoSource.Url(url))
}

Notes:

• blob: URLs are revoked on disposal.
• For large videos, serving them as a static file URL is more memory-efficient.

The library uses platform interop for real playback. For UI tests, you can force a pure-Compose render path:

CompositionLocalProvider(
  LocalVideoPlayerConfig provides VideoPlayerConfig(renderMode = RenderMode.PlaceholderOnly)
) {
  VideoPlayer(
    source = VideoSource.Url("https://example.com/video.mp4"),
    placeholder = { /* render your test-friendly placeholder UI */ }
  )
}

The root node uses the test tag cmp-videoplayer:VideoPlayer.

If using snapshots from Maven Local, ensure:

repositories {
  mavenLocal()
  mavenCentral()
}

Download and try the sample app on your platform without building from source:

Platform	Download Link
🍏 macOS (Intel)
🍎 macOS (Apple Silicon)
🪟 Windows
🐧 Linux
🤖 Android
🌐 Web (Wasm)
 iOS Simulator

Option 1: Drag and Drop

• Download the APK file
• Open an Android emulator or connect a physical device
• Drag the APK onto the emulator window

Option 2: ADB Install

adb install sample-app-android-unsigned.apk

• Download and unzip sample-app-wasm.zip
• Open index.html in a web browser

Note: You can also try the live demo without downloading: Try Live Demo

• Download sample-app-ios-simulator.zip from the latest release
• Unzip to get sample-app-ios-simulator.app
• Open your iOS Simulator in Xcode
• Drag the .app onto the Simulator window OR run:

  xcrun simctl install booted /path/to/sample-app-ios-simulator.app

• The sample app will now appear and can be launched directly from the Simulator!

• Download the DMG for your Mac architecture (Intel or Apple Silicon)

• Open (mount) the DMG and drag the app to your Applications folder (or Desktop)

• When you try to open the app for the first time, macOS Gatekeeper will block it since it is an open-source build signed ad-hoc (not using a paid Apple Developer account). Follow these 6 sequential steps to allow running the app:

  1. Block Alert Dialog	2. Open System Settings	3. Privacy & Security Section
  4. Click "Open Anyway"	5. Authenticate Security Dialog	6. Click "Open" to Launch

• To allow running the app:

  1. Double-click the app. If blocked, open macOS System Settings (or System Preferences).
  2. Navigate to Privacy & Security and scroll down to the Security section.
  3. You will see a notice stating: "sample was blocked from use because it is not from an identified developer".
  4. Click "Open Anyway" and authenticate with your user password or Touch ID.
  5. Re-open the app and click "Open" on the confirmation dialog. The app will now launch safely!

This is a normal security step for all open-source and CI-generated Mac executables. Apps are signed ad-hoc for internal/dev use, not with a public Apple developer ID.

Tip: Unsure about your Mac's type? Click the Apple logo → "About This Mac". If it says Intel, download x64; if it says M1, M2, or M3, download arm64.

• Download and run the MSI installer
• Follow the installation wizard
• Launch the app from the Start menu

• Download the .deb file
• Double-click the file to open it in your software manager and click "Install", OR run:

  sudo dpkg -i sample-app-linux.deb

• Launch the application from your desktop launcher or run sample in the terminal!

This library automatically deploys three key resources:

Resource	Description	Preview
📚 Library Homepage	Your README becomes a beautiful landing page with Docsify
📖 API Documentation	Automatically generated Dokka docs with improved UI (2.2.0)
🌐 Live Wasm Demo	Interactive browser demo of your sample app

All three are automatically deployed to GitHub Pages:

• Homepage: https://<username>.github.io/<library-name>/
• API Docs: https://<username>.github.io/<library-name>/api/
• Demo: https://<username>.github.io/<library-name>/demo/

You can also run Gradle tasks in the terminal:

• ./gradlew run to run application
• ./gradlew package to store native distribution into build/compose/binaries

• Desktop JVM: ./gradlew :sample:composeApp:run
• Android: Open project in Android Studio and run the sample app
• iOS: Open sample/iosApp/iosApp.xcodeproj in Xcode and run the sample app
• Wasm: ./gradlew :sample:composeApp:wasmJsBrowserRun

This repo ships with an opinionated CI/CD that builds, tests, packages, releases, and deploys docs & demo automatically on tags.

flowchart TD
    A["Lint"] --> B["Build & Test - Library + Sample (all targets)"]
    B --> C["Android UI tests (emulator) & Maestro E2E tests(iOS & Android)"]
    C --> D["Build artifacts - APK • DMG (Intel/Apple Silicon) • MSI • DEB • iOS Simulator zip • wasm bundle"]
    D --> E["Create GitHub Release and upload artifacts"]
    E --> F["Publish to Maven Central"]
    E --> G["Deploy GitHub Pages README site (Docsify) + wasm demo + API docs"]

Key points:

• Triggered on version tags (v*) and manual runs.
• Lint first, then build/test library targets followed by sample targets.
• Android UI tests on emulator before packaging.
• GitHub Release includes platform artifacts for quick validation.
• GitHub Pages hosts the README homepage (Docsify), wasm demo, and Dokka API docs.

1. Run ./gradlew :cmp-videoplayer:publishToMavenLocal
2. Open ~/.m2/repository/cmp-videoplayer/

Follow https://www.jetbrains.com/help/kotlin-multiplatform-dev/multiplatform-publish-libraries.html & complete all necessary steps.

The above article focuses on publishing to MavenCentral. But if you want to verify publishing from your local machine, you can follow below steps:

1. Add these lines to ~/.gradle/gradle.properties(not to be confused with gradle.properties in project root):

   signing.keyId=XXXXXXXX
   signing.password=[key password]
   signing.secretKeyRingFile=../XXXXXXXX.gpg
   mavenCentralUsername=[generated username]
   mavenCentralPassword=[generated password]
   

   For GPG_KEY_CONTENTS secret(signing.secretKeyRingFile above), can get plain text version of gpg key using below commands.

   # This will print the private GPG key in plain text.
   gpg --export-secret-keys --armor <key id>
   
   # this will copy it for pasting in github actions secrets.
   gpg --export-secret-keys --armor <key id> | pbcopy
   

2. Run ./gradlew :cmp-videoplayer:publishAndReleaseToMavenCentral --no-configuration-cache

Now check the deployments here https://central.sonatype.com/publishing/deployments

MIT License © 2025 aryapreetam and contributors. See LICENSE for details.

This template was built with inspiration and learnings from the excellent work of the Kotlin multiplatform community:

• Project Setup: Initial project structure was created using Kotlin Multiplatform Web Wizard by terrakok

• Inspirations:

  • Reorderable by Calvin-LL - For a library that seamlessly works across all platforms, and most importantly, providing demo app APK in releases to test before integrating
  • compose-multiplatform-library-template by KevinnZou
  • compose-multiplatform-library-template by meticha

Special thanks to:

• GitHub for hosting this project and providing free compute resources for CI/CD through GitHub Actions
• JetBrains for building the incredible Kotlin Multiplatform and Compose Multiplatform frameworks that enable us to build truly cross-platform applications with shared code
• The entire Kotlin Multiplatform and Compose Multiplatform communities for making cross-platform development better every day!

This section lists planned improvements and features for the template. Contributions are welcome!

• [ ] Add Detekt - Static code analysis for Kotlin

  • Configure rules for library code
  • Integrate into CI pipeline

• [ ] Add ktlint - Kotlin code formatter

  • Consistent code style across project
  • Auto-formatting in CI

• [ ] Add Kover - Code coverage reporting

  • Track test coverage across platforms
  • Publish coverage reports to Codecov

• [ ] Add Dependabot - Automated dependency updates

  • Weekly checks for Gradle dependencies
  • Weekly checks for GitHub Actions versions

• [ ] Screenshot Testing - Visual regression testing

  • Add Paparazzi for Android
  • iOS screenshot tests using XCTest

• [ ] Performance Benchmarking - Track performance metrics

  • Integrate androidx.benchmark for Android
  • Baseline profiles for library code

• [ ] Multi-Module Support Guide

  • Document how to structure multi-module libraries
  • Example with feature modules

• [ ] Compose Resources Guide

  • How to bundle images, strings, fonts
  • Localization examples
  • Resource packaging best practices

• [ ] Video Tutorial

  • 10-minute walkthrough of using the template
  • Publishing to Maven Central demo
  • Deploying demo and docs

• [ ] Blog Post / Article

  • Write comprehensive guide on Dev.to or Medium
  • Share on Reddit r/Kotlin and r/Kotlinmobile

• [ ] Automated Changelog Generation

  • Use conventional commits
  • Auto-generate release notes from commits/PRs
  • Integrate github-changelog-generator

• [ ] Version Bump Automation

  • Script to update version in cmp-videoplayer/build.gradle.kts
  • Semantic versioning support
  • Consider semantic-release integration

• [ ] Automated Screenshots

  • Generate sample app screenshots during CI
  • Attach to releases or README

• [ ] Linux Desktop Packaging

  • Add DEB/RPM package generation
  • AppImage support

• [ ] Additional Apple Platforms

  • watchOS support
  • tvOS support
  • macCatalyst support

• [ ] Desktop Linux Native Build

  • Build on Linux runners for native Linux apps
  • Better Linux desktop integration

• [ ] Custom Domain Support

  • Document setup for custom domains
  • DNS configuration guide

• [ ] Improved Docsify Theme

  • Custom theme matching library branding
  • Dark mode support
  • Better mobile responsive design

• [ ] Search Functionality

  • Add search to documentation site
  • Full-text search across API docs

• [ ] Vulnerability Scanning

  • Integrate Snyk or similar
  • Automated security updates

• [ ] SBOM Generation

  • Generate Software Bill of Materials
  • Dependency transparency

• [ ] Signed Releases

  • Sign release artifacts with GPG
  • Provide checksums (SHA256)

• [ ] JitPack Support

  • Alternative to Maven Central
  • Easier for snapshot builds

• [ ] NPM Package for Wasm

  • Publish wasm builds to NPM
  • Better integration with web projects

• [ ] CocoaPods Support

  • Publish iOS framework to CocoaPods
  • Easier iOS integration

• [ ] Template Initialization Script
  • Interactive CLI to customize template
  • Automated find/replace for package names
  • Git history cleanup

If you have suggestions for improvements or want to contribute:

1. Check if the feature is already listed above
2. Open an issue to discuss your idea
3. Submit a PR with your implementation

Priority: Items marked with 🔥 are high priority and would have the most impact.

See CONTRIBUTING.md for detailed contribution guidelines.