Windows desktop app: browse, extensions, mpv playback, and downloads

[weaponlions]

Summary

This adds a working Windows desktop version of CloudStream, built on the existing Compose Multiplatform desktopApp / shared modules. It runs the same extensions as Android: it downloads them from the usual repositories, converts them for the JVM, and runs them. Video plays through libmpv.

63 commits; 190 files changed (+19,016 / −152). Almost all of it is new desktop-only code. Changes to shared code are small and listed under "Changes outside the desktop app".

Features

Browsing

• Home with a featured banner, Search with history, title pages with seasons and episodes.
• Library and Continue watching, which resumes from the last position and the last source used.

Extensions

• Add repositories by URL, short code or MegaRepo, then install, update and remove extensions.
• Android extensions are converted from dex to JVM bytecode. Android APIs that desktop doesn't have are stubbed, and the Installed page says when part of an extension couldn't be converted.
• Extension code runs with limits on time and memory, so one bad extension can't take down the app.

Player (libmpv embedded in the window)

• Seek bar with a buffering indicator, buttons to skip ±10 s, volume up to 130 %, and a brightness control.
• Pick the audio track, subtitles, playback speed and aspect ratio / zoom.
• Subtitle styling and automatic language selection, as on Android.
• Keyboard shortcuts, full screen, and the mouse wheel sets volume on the right half and brightness on the left, as on Android.
• When a source fails, the player moves on to the next one and carries on from the same position.
• A Skip button plays the best link found so far while extensions are still searching.
• A far seek that the server never answers is retried on a new connection.

Network

• Cloudflare checks and WebView lookups are solved with a headless Microsoft Edge. A browser window opens only when a site needs a human check and the user asks for it.
• One shared HTTP client for the whole app.

Downloads and torrents

• Download movies and episodes to watch offline, choosing the source as on Android.
• Torrents and magnet links stream through TorrServer, which is installed only after the user agrees.

Settings and appearance

• Settings are saved, the window remembers its size and position, and logs go to %APPDATA%\CloudStream\logs.
• Dark and light themes, with buttons, chips and dialogs styled after the Android app.

Changes outside the desktop app

• settings.gradle.kts: adds the :androidCompat module.
• androidCompat/ (new): JVM stand-ins for the Android classes that extensions use (Context, SharedPreferences, Activity, Log, …), plus the dex converter and stub generator.
• library/:
  • New DesktopWebView interface. WebViewResolver.jvm.kt uses it when the desktop app installs one; otherwise behaviour is unchanged.
  • MainAPI.kt: a bug fix in Episode.addDate. A date with a time but no time-zone offset was read as UTC; it now uses the device's time zone, as the code comment already said it should. This affects Android too.
• shared/: view models (home, search, detail, links), stores for the library and settings, icons and strings, and small theme changes.
• gradle/libs.versions.toml: new desktop dependencies.

Build and run

.\gradlew.bat :desktopApp:run                    # run from source
.\gradlew.bat :desktopApp:packageMsi             # build the Windows installer
.\gradlew.bat :shared:jvmTest                    # desktop unit tests

libmpv is built from source by .github/workflows/libmpv.yml (Clang, same setup as shinchiro's builds). The complete source of every bundled library is published with the release, to meet the LGPL.

CI and release

• desktop.yml: builds the MSI and runs the JVM tests.
• release.yml: publishes a beta of the Windows app on every merge into master. The app has a built-in updater that checks those releases.
• libmpv.yml: builds libmpv and its source archive.

To decide before merging

• Fork-specific URLs: the libmpv and 7zr downloads (desktopApp/build.gradle.kts) and the updater (AppUpdater.REPOSITORY) still point to harsh-pockt/cloudstream releases. They need to point to this repo's releases, which means running libmpv.yml here once.
• Release cadence: whether you want a beta published on every merge, or releases only on demand.
• Platforms: Windows only for now. The mpv embedding and Edge integration use Win32 APIs; macOS and Linux would need their own versions.

Known limitations

• Extensions that depend heavily on Android UI, or on parts that can't be converted, may only partly work. The app says so on the Installed page.
• Links protected by DRM can't play on desktop; they are skipped, and the player says how many were.

Testing

• Unit tests in shared/src/jvmTest cover plugin loading and conversion, downloads, the watch store, subtitle settings, preferences, the HTTP client, the system browser and TorrServer.
• The app has been used day to day on Windows 11, with a range of extensions from MegaRepo.

[fire-light42]

You have created a very cool project, but it is not something I can merge.

Claude is very good at creating demos, or something which works on your own machine. It is seemingly not good at creating maintainable or portable code. This is visible in two core issues of this code: Inherent Windows dependency and lots of duplicated code. The entire AndroidCompat will require duplicated effort when changing anything and invariably cause weird issues. The heavy Windows dependency removes all upsides of working with Compose. We are aiming to make CloudStream platform neutral using KMP and target many different platforms.

We are working on making CloudStream Windows-compatible, but taking shortcuts (such as Windows-only, or duplicated code) in the official project will slow down the project too much in the long run.

[weaponlions]

Thanks for taking the time to review my PR and explain your concerns. I understand your points regarding code duplication, Windows-specific dependencies, and the importance of keeping CloudStream platform-neutral and maintainable.

I’m still very interested in contributing to CloudStream, and I’d really appreciate an opportunity to work on the desktop version. I’m happy to start with any bugs, smaller features, or improvements that align with the project’s architecture and KMP goals.

I’m also willing to rework my approach and learn from the project’s existing patterns to ensure my contributions are maintainable and portable.

I understand if this PR isn’t suitable for merging in its current state, but I’d be grateful for a chance to contribute in a way that genuinely benefits the project. If there’s an issue you think would be a good starting point, I’d love to take it on.

[fire-light42]

That's great to hear!

CloudStream would really benefit from more help! Currently the desktop compose migration requires a lot of precision to get right, in an admittedly confusing code base. This makes it difficult for new contributors to help. However, this will only get easier in time as more of the difficult stuff is solved.

I would suggest looking into how smaller bugs or features can be implemented within the existing compose rework (currently only Settings). This makes it possible to learn the code base and the review process, while working with compose.

An example of just a feature like that would be a custom DNS: #3200 #1708
It is a long-requested feature, but to implement it you need to use compose and work within the existing code base.

If you want to work on something else, you have a wide selection to pick from in https://github.com/recloudstream/cloudstream/issues, but I would advise against implementing new features, since it is very easy to make mistakes when creating new features in a new code base.