CloudStream Proof of Concept

"I'm going to be completely honest with you: this entire repository is purely vibecoded. I don't know how this shit works at all so don't ask me. I just prompted an AI and prayed for this to work... and somehow it did."

Welcome to CloudStream Proof of Concept.

This is a native Compose for Desktop application designed to run CloudStream Android plugins natively on your PC, without requiring an emulator.

⚠️ Disclaimer

This is an independent, unofficial experiment. This project is not endorsed by, associated with, or maintained by the original CloudStream developers. It was built as a fun experiment to see if Android plugins could be forced to run natively on a desktop JVM environment.

I do not guarantee ongoing maintenance or updates for this repository. You are highly encouraged to fork, modify, and improve the codebase.

📁 Repository Structure

To keep the repository clean and avoid tracking compiled binaries, we only push the source code. Here is the exact breakdown of how the architecture is laid out:

cloudstream-windows-workspace/
├── android-reference/           # Git Submodule pointing directly to the official CloudStream Android repository
├── desktop-app/                 # The main Kotlin/Compose desktop module
│   ├── build.gradle.kts         # Gradle build script for the desktop app
│   └── src/main/
│       ├── java/android/        # "The Stubs": Fake Android APIs (Context, Log, Uri)
│       └── kotlin/com/lagradost/cloudstream3/desktop/
│           ├── loader/          # Dynamic JAR/CS3 Plugin ClassLoader
│           ├── player/          # MPV/VLC Video Player bridges (IPC, CLI wrappers)
│           ├── repo/            # Repository Manager for downloading plugin JSONs
│           ├── storage/         # DesktopDataStore for cross-platform JSON saving
│           └── ui/              # Jetpack Compose for Desktop UI Screens
├── plugin-sandbox/              # Standalone module to test plugins without booting UI
├── build.gradle.kts             # Root Gradle build script
└── settings.gradle.kts          # Root settings

🛠 Architecture Overview

Bringing an Android plugin ecosystem to Windows required some creative engineering.

1. The Android Stubs

CloudStream plugins (.cs3 or .jar files) are explicitly compiled for Android. Running them natively on a Windows JVM normally results in an immediate crash due to missing Android dependencies. To resolve this, we implemented a custom android package inside the desktop app. By providing barebones implementations of core Android classes, the plugins execute seamlessly. However, if a plugin utilizes an un-stubbed Android API, the application will crash. It is an ongoing game of whack-a-mole, but highly effective.

2. External Video Playback

Instead of wrestling with native video rendering inside Compose Desktop, we opted for a far more robust solution. When playback is initiated, the application extracts the raw video URL and launches a separate instance of mpv.exe (or VLC). Watch progress is tracked by reading the player's terminal output via Inter-Process Communication (IPC). It is held together by string and hope, but results in perfectly smooth, hardware-accelerated playback.

3. Core Library Isolation

We treat the original CloudStream parsing library (android-reference) as a black box. This folder is a direct pipeline to the official, unmodified CloudStream Android APK source code. When you clone this project, Git reaches out to their official GitHub repository and downloads their exact code. We feed it URLs and it returns media. This modularity ensures our desktop UI remains decoupled from the scraping logic, though it means significant upstream refactoring could break this port.

🚀 Setup & Installation

If you would like to run or build the project yourself:

1. Prerequisites:

• JDK 17 or higher installed on your system.
• Git (to clone the repository and its submodules).

To clone the repository properly (including the Android submodule):

git clone --recursive https://github.com/YourUsername/cloudstream-windows.git
cd cloudstream-windows

Warning

DO NOT DOWNLOAD THIS REPOSITORY AS A ZIP FILE. GitHub ZIP downloads do not include Git Submodules. If you download the ZIP, the android-reference folder will be completely empty and the app will instantly crash when you try to build it. You must use the git clone command above.

2. The Video Player (Critical): Due to the playback architecture detailed above, a native media player is required.

• Download MPV Player (highly recommended) or VLC.
• Add mpv.exe to your Windows System PATH, OR place mpv.exe directly inside the desktop-app/mpv/ directory of this project.

3. Build and Run: Open your terminal in the root folder of the repository and execute:

./gradlew desktop-app:run

(Initial launch will take time as Gradle resolves dependencies).

4. Loading Extensions: Out of the box, the application contains no media. To populate it:

1. Launch the app.
2. Navigate to the Extensions tab on the sidebar.
3. Paste a valid CloudStream repository URL (e.g., a .json plugin list from the community).
4. Click Download on the desired providers.
5. Return to the Home tab and select your newly installed provider from the dropdown menu.

🙏 Credits

Massive thanks to the original CloudStream developers and contributors. We utilized their core scraping engine and extension architecture to make this port possible. Without their incredible foundational code, this project would not exist.

📜 Legal Notice

This repository contains NO DMCA-violating content or illegal repository URLs. It serves purely as a blank-slate media player and scraper engine.

---

P.S. Yes, parts of this README were generated by AI. It confirmed the codebase is slightly terrifying, but noted it was "actually shockingly smart." I'll take the win.