Roadmap: Cross-platform packaging (Windows MSI, Linux Flatpak, macOS)

[TheZupZup]

Overview

This issue tracks the long-term goal of making Auryn available as a properly packaged, self-contained application on Windows, Linux (via Flatpak), and macOS. It is a planning and coordination issue — not an implementation task. No work should be merged under this umbrella until the groundwork described below is completed.

---

Current state

Auryn is a single-file Python/GTK3 desktop application (src/Qrip.py, currently mid-rebrand). It depends on:

• PyGObject / GTK 3 for the GUI
• Python standard library modules including fcntl, os.openpty, and subprocess for terminal emulation and process control
• xdg-open for opening URLs from the UI
• streamrip as an external CLI dependency (the actual download engine)

The .desktop file in desktop/ provides basic Linux desktop integration. The README references .deb, Docker, and Flatpak distribution methods, but none of these packaging artifacts currently exist in this repository. There is no setup.py, pyproject.toml, requirements.txt, Flatpak manifest, or any platform-specific build script in the codebase.

The application is currently only viable on Linux. Several parts of the code use Linux-specific APIs:

• fcntl (not available on Windows)
• os.openpty / PTY-based terminal emulation (not available on Windows)
• xdg-open (Linux/freedesktop only)

---

Sub-issues

The following checklist represents the concrete steps required before any packaging work can begin or be considered complete. These will be broken into individual tracking issues as work progresses.

Phase 1 — Audit & prerequisites

• Complete the rebrand from "Qrip" to "Auryn" across all runtime strings, filenames, and documentation before any packaging work starts (leftover Qrip references will cause confusion in packaged installers)
• Audit all Linux-specific stdlib usage (fcntl, os.openpty, xdg-open) and document which are blocking blockers for each target platform
• Audit GTK3 availability and maturity on Windows (MSYS2/mingw64) and macOS (Homebrew) — determine whether the GTK3 dependency is a dealbreaker or merely inconvenient
• Document the full runtime dependency graph: Python version, GTK version, streamrip version, and any implicit system libraries
• Add a requirements.txt or pyproject.toml so dependencies are explicit and reproducible

Phase 2 — Portability fixes

• Replace or abstract fcntl-based locking with a cross-platform alternative (e.g., msvcrt on Windows, conditional import)
• Replace or abstract PTY/os.openpty usage with a cross-platform terminal emulation approach (e.g., pexpect, a subprocess pipe fallback, or platform guards)
• Replace xdg-open with a cross-platform webbrowser.open() / os.startfile() approach

Phase 3 — Platform validation

• Validate that Auryn starts and runs correctly on macOS (with GTK3 via Homebrew) — document any visual or functional regressions
• Validate that Auryn starts and runs correctly on Windows (with GTK3 via MSYS2 or a bundled runtime) — document blockers
• Validate that streamrip itself is available and functional on each target platform (this is an upstream concern but affects our packaging story)

Phase 4 — Packaging

• Create a Flatpak manifest (com.github.thezupzup.Auryn.yml) and publish to Flathub or self-host — this is the most realistic near-term packaging target given the existing Linux focus
• Define a macOS packaging strategy (options: .app bundle via briefcase or py2app, DMG, or Homebrew formula)
• Define a Windows packaging strategy (options: NSIS, WiX MSI, or briefcase for a self-contained installer)
• Open individual tracking issues for each packaging target once the platform validation phase is complete

---

Goal

The realistic end goal is:

1. Linux (Flatpak): Auryn is installable from Flathub or a self-hosted repo with a single command, without requiring the user to install Python, GTK3, or other system dependencies manually.
2. macOS: Auryn is distributable as a signed .app bundle or via Homebrew, with acceptable (not perfect) GTK3 rendering.
3. Windows: Auryn is distributable as an MSI or similar installer that bundles all required dependencies, including the GTK3 runtime.

None of this implies a native look-and-feel on non-Linux platforms. GTK3 on Windows and macOS has well-known limitations. The goal is functional availability, not visual parity.

---

Notes

• This is a planning issue, not an implementation issue. Do not start packaging work until Phases 1 and 2 are substantially complete.
• Changes to support cross-platform portability should be incremental and should not break the existing Linux experience.
• The Flatpak target is the most natural next step given the current Linux-only state and should be prioritized.
• Windows support is the most technically challenging target (no native PTY, no fcntl, GTK3 runtime is non-trivial to bundle) and should be treated as a stretch goal.
• This issue will be updated as sub-issues are created and linked.

[snakefood3232]

I see the roadmap for cross-platform packaging needs an audit of Linux-specific dependencies like fcntl and os.openpty first. I'd handle this by systematically replacing those with platform-agnostic alternatives, starting with the terminal emulation layer. Can have an initial PR up in a couple days to address the core compatibility blockers. I've built similar GTK/Python apps with Windows/MSI packaging before.

[TheZupZup]

Hey, this is awesome really appreciate you jumping in on this 🙏
An audit of the Linux-specific parts (fcntl, openpty, etc.) is exactly what I had in mind before going further with cross-platform support.
Starting with the terminal/PTY layer makes a lot of sense. If you open a PR, I’ll happily review it and we can iterate together from there.
Thanks again for taking the time to help, it really means a lot 😊