CloudStream Desktop (Unofficial Client)

Important

Pre-Alpha / Closed Testing Phase
This project is in active pre-alpha development. We are not distributing pre-compiled setup executables or installers yet. All development, testing, and debugging are currently run directly from the source code.

Welcome to the CloudStream Desktop project. This is a native Compose for Desktop application designed to run CloudStream Android plugins natively in a desktop JVM environment.

---

🏗️ Multi-Module Architecture

The project is structured into modular layers to cleanly separate concerns and allow the Android-specific plugin code to execute on the desktop:

• :library (android-reference): A submodule copy of the core Android CloudStream library. It contains the primary data models, scrapers, and extension interfaces.
• :android-stubs: Compatibility mock stubs for Android platform APIs (e.g., Context, SharedPreferences, ActivityThread). This allows standard JVM compilation of Android-targeted plugin code.
• :common: The persistence and settings layer. It uses SQLDelight for local database management and Jackson-based file serialization, remaining completely decoupled from the UI.
• :player-abstraction: Abstracts media playback. It hosts native wrappers for MPV (JNA bindings) and VLC (process wrappers), and embeds a local Ktor Netty proxy (LocalStreamProxy) to rewrite HLS segment headers for CDN requests.
• :desktop-app: The main entry point. It hosts the Compose for Desktop UI, navigation, theme controls, and window chrome.
• :plugin-runtime / :plugin-sandbox: Handles isolated plugin loading and basic bytecode sandboxing to protect local files.

---

🛠️ Setup & Development Workflow

Prerequisites

• JDK 21 or higher.
• Git (needed for cloning submodules).

1. Clone the Repository

You must use Git clone with recursive submodules so the Android core library references are pulled correctly:

git clone --recursive https://github.com/errorcode26/cloudstream-desktop-unofficial.git
cd cloudstream-desktop-unofficial

Warning

Do not download this repository as a zip file from GitHub, as submodules will be missing.

2. Download Native Binaries

Before running, you need a local copy of the libmpv shared library for video decoding:

1. Download the latest mpv-dev Windows build (e.g., from SourceForge).
2. Extract and place libmpv-2.dll (or mpv-2.dll) directly inside the following folder: desktop-app/appResources/windows/mpv/

3. Run Locally

To compile the codebase and launch the application locally in developer mode:

./gradlew.bat :desktop-app:run

4. Build Installer (Optional)

If you need to generate a standalone Windows .exe setup installer for testing:

1. Run compile.bat to clean and compile the latest executable binaries.
2. Open Inno Setup Compiler and compile installer/setup.iss.

The compiled setup installer will be generated at desktop-app\build\outputs\CloudStream-Setup.exe.

---

🧪 Testing & Code Quality

This architecture is built for rapid iteration. We have a lightweight test harness, but our focus is on active developer validation:

• Use isolated experimental/feature branches for development to keep the dev branch clean.
• To test changes on the video player directly, use:

  .\run_test_player.bat

---

Disclaimer

This repository acts purely as a blank-slate media shell. The application does not ship with any plugins, media files, or pre-configured content sources. The developers hold no responsibility or liability for how users choose to utilize this software.