Wallwinxs

Descubre, previsualiza y aplica fondos de pantalla — en tu teléfono y en tu escritorio.

Jose Manuel Morales Ramirez ( @Disasterxz · usuario de GitHub Disasterxz ) Desarrollador independiente y creador de Wallwinxs — app de Android, CLI multiplataforma para Windows/Linux/macOS, infraestructura de CI/CD (GitHub Actions), firma de la app y todo lo que ves en este repositorio.

Tecnologías que maneja

Otros proyectos de @Disasterxz

IPTVMexico App de IPTV para Android TV y celular, con canales en vivo de México.

ControlDeGastos Control de gastos local-first para Android, con Jetpack Compose y Material 3.

---

Wallwinxs es un ecosistema de aplicaciones para descubrir, previsualizar y aplicar fondos de pantalla cargados desde los servidores de Wallheaven:

• 📱 App de Android — cliente nativo en Kotlin con búsqueda, álbumes locales, fondos de vídeo, rotación automática y bloqueo biométrico.
• 🖥️ Programa de Windows — CLI interactiva en Python con interfaz ANSI a color, arte ASCII personalizable y establecimiento directo del fondo de escritorio.
• 🐧 Programa de Linux — la misma CLI portada a Linux, empaquetada en .deb, .rpm y .pkg.tar.zst, probada en Linux Mint (XFCE, Cinnamon y MATE).
• 🍎 Programa de macOS — la misma CLI portada a macOS, empaquetada como instalador .pkg para Apple Silicon.

Repositorio público. Uso personal / educativo.

Los fondos de pantalla se obtienen en tiempo real de Wallhaven a través de su API pública oficial. Wallwinxs no aloja ni redistribuye imágenes propias: cada usuario puede usarlo en modo público (solo contenido SFW) o con su propia API Key de Wallhaven (gratuita, desde su cuenta) para desbloquear Sketchy/NSFW y sus favoritos.

📦 Los binarios ya compilados (APK de Android, .exe de Windows, paquetes de Linux y .pkg de macOS) se publican en la sección Releases del repositorio.

Compatibilidad, de un vistazo

Plataforma	Versiones soportadas
📱 Android	Android 5.0 Lollipop (minSdk 21) en adelante — compilado/apuntado a Android 16 (compileSdk/targetSdk 36)
🖥️ Windows	Windows Vista a Windows 11, 32 y 64 bits (detección automática de versión; fondo de pantalla de bloqueo requiere Windows 10 build 14393+)
🐧 Linux	Cualquier distro x86_64 basada en Debian/Ubuntu (Mint, Ubuntu, Pop!_OS...), Fedora/RHEL/openSUSE, o Arch/Manjaro/EndeavourOS — ver tabla de paquetes en la sección de Linux
🍎 macOS	.pkg publicado para Apple Silicon (arm64: M1/M2/M3/M4); Mac Intel no tiene runner hospedado disponible en GitHub Actions, pero puede compilarse desde código fuente

---

Índice

• Estructura del repositorio
• App de Android
  • Arquitectura y paquetes
  • Funcionalidades
  • Compatibilidad
  • Cómo compilar
• Programa de Windows
  • Funcionalidades
  • Compatibilidad
  • Cómo ejecutar
  • Cómo compilar el .exe
• Programa de Linux
  • Funcionalidades
  • Compatibilidad
  • Cómo ejecutar
  • Cómo compilar el binario
• Programa de macOS
  • Funcionalidades
  • Compatibilidad
  • Cómo ejecutar
  • Cómo compilar el .pkg
• Releases / descargas
• API y configuración
• Notas de seguridad
• Aviso legal y propósito del proyecto

---

Estructura del repositorio

Wallwinxs/
├── app/                        # App de Android (módulo Gradle)
│   └── src/main/java/com/android/wallwinxs/
│       ├── albums/              # Álbumes locales de fondos guardados
│       ├── data/model/          # Modelos de datos (Wallpaper, Meta, Tag, Thumbs...)
│       ├── data/remote/         # Cliente Retrofit hacia la API de Wallwinxs
│       ├── security/            # Preferencias cifradas, biometría, ajustes de descarga
│       ├── ui/home/              # Pantalla principal, lista de fondos, ViewModel
│       ├── ui/singleton/         # Estado compartido entre pantallas
│       ├── util/                 # Utilidades (idioma, bitmaps, traducción de tags...)
│       └── wallpaper/            # Rotación automática, alarmas, arranque, fondos de vídeo
├── wallwinxs.py                 # Programa CLI multiplataforma (un solo archivo: detecta Windows/Linux/macOS y usa la lógica correspondiente)
├── Wallwinxs.spec                # Configuración de PyInstaller para generar el .exe (Windows, x64 y x86)
├── dist/Wallwinxs.exe            # Ejecutable compilado del programa de Windows
├── Wallwinxs-linux.spec          # Configuración de PyInstaller para el binario de Linux
├── packaging/linux/              # Plantilla de control y .desktop para empaquetar el .deb
├── Wallwinxs-macos.spec          # Configuración de PyInstaller para el binario de macOS
├── .github/workflows/            # Workflows que compilan los binarios de Linux/macOS y suben los paquetes al Release
├── requirements.txt              # Dependencias Python (comunes a Windows, Linux y macOS)
├── build.gradle.kts              # Build script raíz de Gradle
├── settings.gradle.kts           # Módulos del proyecto Gradle
└── gradle/                       # Wrapper y catálogo de versiones de Gradle

---

📱 App de Android

Cliente nativo escrito en Kotlin, sin frameworks multiplataforma, siguiendo el patrón clásico Activity/Fragment + ViewModel de Android.

Arquitectura y paquetes

Paquete	Responsabilidad
data.remote	WallwinxsApiService (interfaz Retrofit) + RetrofitClient, que apunta a los servidores de Wallwinxs y añade la API key guardada en SharedPreferences.
data.model	DTOs de la respuesta de la API: Wallpaper, WallpaperResponse, WallpaperDetailResponse, Meta, Tag, Thumbs, UserSettings.
ui.home	Pantalla principal (HomeFragment), su HomeViewModel (LiveData) y el WallpaperAdapter del grid de resultados.
ui.singleton	Estado compartido en memoria entre pantallas: fondo seleccionado (WallpaperHolder), búsqueda pendiente (PendingSearch), refresco de color dinámico (DynamicColorRefresh).
albums	Sistema de álbumes locales: Album, AlbumStore (persistencia), AlbumsActivity, AlbumDetailActivity, adaptadores para fondos remotos y locales.
wallpaper	Rotación automática de fondos: AlarmScheduler (AlarmManager), AutoWallpaperReceiver, BootReceiver (reprograma tras reiniciar el dispositivo), WallpaperNotifier.
wallpaper.video	Fondos de pantalla animados/vídeo mediante WallpaperService (VideoWallpaperService, VideoWallpaperActivity, VideoWallpaperFiles, VideoWallpaperPrefs).
security	SecurityPrefs, BiometricAuthHelper (bloqueo por huella/PIN con androidx.biometric), DownloadPrefs, AutoWallpaperPrefs, DisplayPrefs.
util	AppLanguage (selector de idioma en runtime), BitmapUtils, SearchQueryTranslator/TagDisplayTranslator/TagSuggestionProvider (traducción y sugerencias de etiquetas de búsqueda), paleta de colores de la interfaz, ViewExt.
raíz (com.android.wallwinxs)	SplashActivity, MainActivity, SettingsActivity, ApiKeyActivity, SecuritySetupActivity, WallpaperPreviewActivity / LocalWallpaperPreviewActivity (con zoom vía PhotoView), WallpaperPagerAdapter (swipe entre fondos), WallwinxsApp (clase Application, expone el contexto global).

Funcionalidades

• 🔍 Búsqueda de fondos por categoría (General / Anime / Gente), pureza (SFW / Sketchy / NSFW) y orden (recientes, relevancia, aleatorio, más vistos, favoritos, top).
• 🖼️ Vista previa a pantalla completa con pinch-to-zoom y navegación por swipe entre resultados.
• ⬇️ Descarga y ajuste como fondo de pantalla (home, lock screen o ambos), con carpeta de descarga personalizable vía Storage Access Framework.
• 📂 Álbumes locales: guardar fondos favoritos en colecciones propias dentro del dispositivo.
• 🔁 Rotación automática: cambia el fondo periódicamente en segundo plano usando AlarmManager + WorkManager, sobreviviendo a reinicios del dispositivo.
• 🎬 Fondos de vídeo/animados mediante un WallpaperService dedicado.
• 🔒 Bloqueo biométrico de la app (huella, rostro o PIN/patrón del dispositivo) a través de androidx.biometric.
• 🌗 Tema claro/oscuro con Material You (colores dinámicos) y splash screen nativo (Android 12+).
• 🌍 Localización: values-ar, de, es, fr, it, ja, pt, ru, zh, además del inglés por defecto, con selector de idioma en la app.
• 🔑 Activación mediante licencia/API key introducida por el usuario (ApiKeyActivity), verificada contra los servidores de Wallwinxs.

Compatibilidad (Android)

Mínimo soportado	Android 5.0 Lollipop (minSdk 21)
Compilado / apuntado a	Android 16 (compileSdk / targetSdk 36)
Versión actual	1.0 (versionCode 1)
Lenguaje	Kotlin, sourceCompatibility Java 8

Stack técnico

• Retrofit 2 + Gson + OkHttp logging-interceptor — networking contra la API de Wallwinxs.
• Coil — carga y cacheo de imágenes.
• AndroidX Lifecycle (ViewModel + LiveData) — gestión de estado en HomeViewModel.
• Navigation Component — navegación entre fragments.
• WorkManager — tareas en segundo plano fiables para la rotación automática.
• DocumentFile (SAF) — selección de carpeta de descarga personalizada.
• Biometric — autenticación local.
• ViewPager2 — swipe entre fondos.
• PhotoView (chrisbanes/PhotoView) — zoom en la vista previa a pantalla completa.
• Core SplashScreen — splash screen nativo Android 12+.

Cómo compilar la app Android

Requiere Android Studio (o el JDK + Android SDK equivalentes) y conexión a internet para resolver dependencias Gradle.

# Desde la raíz del proyecto
./gradlew assembleDebug     # genera un APK de depuración
./gradlew assembleRelease   # genera un APK de release, firmado si defines
                            # las variables de entorno KEYSTORE_PATH,
                            # KEYSTORE_PASSWORD, KEY_ALIAS y KEY_PASSWORD

El APK resultante queda en app/build/outputs/apk/. El APK publicado en cada Release ya se compila y firma automáticamente vía GitHub Actions, usando un keystore propio guardado como Secrets del repositorio.

---

🖥️ Programa de Windows

wallwinxs.py es una CLI interactiva (sin GUI gráfica), escrita en Python puro para la librería estándar + colorama (colores ANSI base), pyfiglet (arte ASCII) y rich (renderizado de la interfaz y barras de progreso de descarga). Es un único archivo para Windows, Linux y macOS: al arrancar detecta automáticamente el sistema operativo (sys.platform) y activa la lógica correspondiente (fijar fondo de escritorio, atajos de teclado, rutas de configuración, etc.) sin que el usuario tenga que elegir nada ni instalar una versión distinta por plataforma. En Windows además ajusta el tamaño de su propia ventana de consola y bloquea el redimensionado manual.

Funcionalidades

• 🔍 Buscar fondos: por palabra clave con hasta 5 modificadores +etiqueta (incluir) / -etiqueta (excluir), filtrando por categoría, pureza y método de orden (recientes, relevancia, aleatorio, vistos, favoritos, top con rango de tiempo).
• 🎲 Fondo aleatorio: obtiene un fondo al azar según categoría/pureza y permite pedir otro sin salir del flujo.
• 🖼️ Por cada resultado: establecer como fondo de escritorio (vía la API de Windows SystemParametersInfoW), descargar sin aplicarlo, o ver la miniatura en el visor de imágenes predeterminado del sistema.
• 🏷️ Muestra las etiquetas (tags) de cada fondo, obtenidas y cacheadas en memoria por id.
• ⚙️ Ajustes: carpeta de descarga personalizable (por defecto Imágenes/Wallwinxs Wallpapers, respetando redirecciones como OneDrive) y 11 estilos visuales para el arte ASCII (fuentes de pyfiglet + color sólido, degradado o arcoíris animado, renderizados con rich).
• ❓ Ayuda integrada con ejemplos de sintaxis de búsqueda.
• 💾 Configuración persistente en ~/.wallwinxs/config.json (API key, estilo elegido, carpeta de descarga).
• 🌐 Detección automática de la versión de Windows instalada (Vista a 11) y de si es compatible con el fondo de pantalla de bloqueo (Windows 10 build 14393+ / 11).

Compatibilidad (Windows)

Sistema operativo	Windows únicamente (usa ctypes/msvcrt/winreg-style APIs de Win32)
Versiones soportadas	Windows Vista a Windows 11, arquitecturas x86 (32 bits) y x64 (64 bits) (detección de versión incluida); fondo de pantalla de bloqueo requiere Windows 10 build 14393+
Ejecutables standalone	Wallwinxs-x64.exe y Wallwinxs-x86.exe (ver tabla abajo), generados con PyInstaller, no requieren Python instalado
Desde código fuente	Python 3.8+
Versión del programa	1.0.8 (constante APP_VERSION en wallwinxs.py)

Se generan dos ejecutables, para cubrir tanto sistemas de 64 bits como de 32 bits (o 64 bits ejecutando el binario x86 vía WOW64):

Cómo ejecutar el programa de Windows

Opción A — instalación rápida por PowerShell (recomendada):

Abre PowerShell y ejecuta:

irm https://raw.githubusercontent.com/Disasterxz/Wallwinxs/main/install.ps1 | iex

Esto descarga automáticamente el .exe correcto según tu arquitectura (x64/x86) desde el último Release, lo instala en Archivos de programa (x86)\Wallwinxs y lo abre. irm (Invoke-RestMethod) descarga el script y iex (Invoke-Expression) lo ejecuta.

⚠️ Como con cualquier comando irm | iex, solo ejecútalo si confías en la fuente: revisa el contenido de install.ps1 antes si quieres verificar qué hace.

Opción B — ejecutable ya compilado, manual:

Wallwinxs-x64.exe   # Windows Vista/7/8/10/11 de 64 bits
Wallwinxs-x86.exe   # Windows Vista/7/8/10/11 de 32 bits (o 64 bits vía WOW64)

Opción C — desde código fuente:

pip install -r requirements.txt
python wallwinxs.py

(el propio script ofrece instalar automáticamente colorama/pyfiglet/rich si faltan)

Cómo compilar el .exe

El ejecutable "moderno" (Wallwinxs-x64.exe / Wallwinxs-x86.exe) se genera con PyInstaller usando el spec incluido (Wallwinxs.spec), que empaqueta los datos de pyfiglet y usa wall.ico como icono. La arquitectura del .exe resultante depende de la arquitectura del intérprete de Python usado para compilar (PyInstaller no hace compilación cruzada):

pip install pyinstaller

# Compilar un .exe de 64 bits: usa un Python 3.8 de 64 bits instalado
pyinstaller Wallwinxs.spec

# Compilar un .exe de 32 bits: instala un Python 3.8 de 32 bits (ej. desde
# python.org, marcando la opción "Windows x86") y ejecuta pyinstaller
# con ese intérprete, por ejemplo:
py -3.8-32 -m PyInstaller Wallwinxs.spec

El binario resultante se genera en dist/Wallwinxs.exe en ambos casos (renómbralo según la arquitectura si vas a distribuir los dos).

El repositorio incluye un workflow de GitHub Actions (.github/workflows/build-windows.yml) que automatiza el build con Python 3.8 en matriz x64/x86, adjuntando ambos ejecutables al Release cada vez que se publica uno (o disparándolo a mano con workflow_dispatch, indicando el tag del release destino).

---

🐧 Programa de Linux

wallwinxs.py es el mismo archivo único que el programa de Windows: en Linux detecta el sistema automáticamente y usa herramientas nativas (xfconf-query, gsettings, feh, nitrogen, xdg-open) en vez de las APIs de Win32.

Funcionalidades

Todas las del programa de Windows (búsqueda con modificadores +/-, fondo aleatorio, ajustes, ayuda, 11 estilos de arte ASCII), adaptadas así:

• 🖼️ Establecer como fondo de escritorio detectando automáticamente el entorno de escritorio (XDG_CURRENT_DESKTOP) y usando la herramienta nativa correspondiente:
  • XFCE (Linux Mint XFCE) → xfconf-query, aplicando el fondo en todos los monitores/espacios de trabajo detectados.
  • Cinnamon (Linux Mint por defecto) / GNOME → gsettings.
  • MATE → gsettings (esquema org.mate.background).
  • Alternativas de respaldo si no se reconoce el entorno: feh, nitrogen, o probar el resto de herramientas disponibles en el sistema.
• 👁️ Ver miniatura con el visor de imágenes predeterminado vía xdg-open.
• 📁 Carpeta de descarga por defecto en ~/Pictures/Wallwinxs Wallpapers, respetando el directorio de Imágenes configurado por el usuario (xdg-user-dir).
• 💾 Configuración persistente en ~/.config/wallwinxs/config.json, siguiendo la convención XDG de Linux.
• ⌨️ Lectura de teclado (flechas, números, espacio, Enter) implementada con termios/tty en modo raw, sin dependencias externas.

Compatibilidad (Linux)

Sistema operativo	Linux, en el formato de paquete nativo de cada familia de distro (ver tabla abajo)
Paquete	Binario ya compilado (PyInstaller onefile) empaquetado en .deb, .rpm y .pkg.tar.zst — no requiere Python ni dependencias, se instala con doble clic o con el gestor de paquetes del sistema
Desde código fuente	Python 3.8+
Versión del programa	1.0.8 (misma constante APP_VERSION, compartida con la edición de Windows)

Cada Release publica tres paquetes con el mismo binario, uno por familia de distro:

Paquete	Distros	Instalación (un clic o una línea)
wallwinxs_<versión>_amd64.deb	Debian, Ubuntu, Linux Mint, Pop!_OS, elementary OS, Zorin OS y demás derivadas de Ubuntu/Debian	Doble clic (abre el instalador de paquetes del sistema) o sudo apt install ./wallwinxs_<versión>_amd64.deb
wallwinxs_<versión>_x86_64.rpm	Fedora, openSUSE, RHEL/CentOS/AlmaLinux y derivadas	Doble clic o sudo dnf install ./wallwinxs_<versión>_x86_64.rpm (sudo zypper install ./... en openSUSE)
wallwinxs_<versión>_x86_64.pkg.tar.zst	Arch Linux, Manjaro, EndeavourOS y derivadas	sudo pacman -U wallwinxs_<versión>_x86_64.pkg.tar.zst (Manjaro con Pamac también permite doble clic)

Cómo ejecutar el programa de Linux

Opción A — paquete ya compilado (recomendado, sin dependencias):

Descarga el paquete de tu distro desde Releases e instálalo con tu gestor de paquetes habitual (doble clic en el explorador de archivos, o por terminal):

# Debian / Ubuntu / Mint / Pop!_OS
sudo apt install ./wallwinxs_1.0.1_amd64.deb

# Fedora / openSUSE / RHEL y derivadas
sudo dnf install ./wallwinxs_1.0.1_x86_64.rpm

# Arch / Manjaro / EndeavourOS
sudo pacman -U wallwinxs_1.0.1_x86_64.pkg.tar.zst

wallwinxs

Esto instala el binario en /usr/bin/wallwinxs y añade una entrada en el menú de aplicaciones (se abre en una terminal). Para desinstalar: sudo apt remove wallwinxs / sudo dnf remove wallwinxs / sudo pacman -R wallwinxs según corresponda.

Opción B — desde código fuente:

pip install -r requirements.txt
python3 wallwinxs.py

(el propio script ofrece instalar automáticamente colorama/pyfiglet/rich si faltan)

Cómo compilar los paquetes

El binario se genera con PyInstaller usando el spec incluido (Wallwinxs-linux.spec). Debe compilarse en Linux (PyInstaller no hace compilación cruzada):

pip install pyinstaller
pyinstaller Wallwinxs-linux.spec   # genera dist/wallwinxs

# .deb (ver plantillas en packaging/linux/)
mkdir -p pkgroot/DEBIAN pkgroot/usr/bin pkgroot/usr/share/applications pkgroot/usr/share/pixmaps
sed "s/__VERSION__/1.0.1/" packaging/linux/control.template > pkgroot/DEBIAN/control
install -m 755 dist/wallwinxs pkgroot/usr/bin/wallwinxs
install -m 644 packaging/linux/wallwinxs.desktop pkgroot/usr/share/applications/wallwinxs.desktop
install -m 644 icon.png pkgroot/usr/share/pixmaps/wallwinxs.png
dpkg-deb --root-owner-group --build pkgroot wallwinxs_1.0.1_amd64.deb

# .rpm y .pkg.tar.zst con fpm (https://fpm.readthedocs.io/), sin necesitar
# un runner de Fedora ni de Arch:
gem install fpm
fpm -s dir -t rpm    -n wallwinxs -v 1.0.1 -a x86_64 -p wallwinxs_1.0.1_x86_64.rpm \
    dist/wallwinxs=/usr/bin/wallwinxs \
    packaging/linux/wallwinxs.desktop=/usr/share/applications/wallwinxs.desktop \
    icon.png=/usr/share/pixmaps/wallwinxs.png
fpm -s dir -t pacman -n wallwinxs -v 1.0.1 -a x86_64 -p wallwinxs_1.0.1_x86_64.pkg.tar.zst \
    dist/wallwinxs=/usr/bin/wallwinxs \
    packaging/linux/wallwinxs.desktop=/usr/share/applications/wallwinxs.desktop \
    icon.png=/usr/share/pixmaps/wallwinxs.png

El repositorio incluye además un workflow de GitHub Actions (.github/workflows/build-linux.yml) que hace todo esto automáticamente en un runner Ubuntu cada vez que se publica un Release, tomando la versión del propio tag del release, y adjunta los tres paquetes.

---

🍎 Programa de macOS

wallwinxs.py es el mismo archivo único que las ediciones de Windows y Linux: en macOS detecta el sistema automáticamente y usa AppleScript (osascript/System Events) en vez de las APIs de Win32 o las herramientas de Linux.

Funcionalidades

Todas las del resto de ediciones (búsqueda con modificadores +/-, fondo aleatorio, ajustes, ayuda, 11 estilos de arte ASCII), adaptadas así:

• 🖼️ Establecer como fondo de escritorio mediante AppleScript (osascript + System Events), aplicando el fondo en todos los escritorios/pantallas conectadas a la vez.
• 👁️ Ver miniatura con Vista Previa (o el visor predeterminado) vía el comando open.
• 📁 Carpeta de descarga por defecto en ~/Pictures/Wallwinxs Wallpapers.
• 💾 Configuración persistente en ~/Library/Application Support/Wallwinxs/config.json, siguiendo la convención de macOS.
• 🖥️ Detección de la versión de macOS y la arquitectura del Mac para mostrarla en Ajustes.
• ⌨️ Lectura de teclado (flechas, números, espacio, Enter) implementada con termios/tty en modo raw, sin dependencias externas (mismo mecanismo que la edición de Linux).

Compatibilidad (macOS)

Sistema operativo	macOS con Apple Silicon (arm64: M1/M2/M3/M4)
Paquete	Instalador .pkg nativo con el binario ya compilado (PyInstaller onefile) — no requiere Python instalado
Mac Intel	GitHub Actions ya no ofrece runners hospedados con macOS Intel, así que no se publica un .pkg para x86_64; en un Mac Intel el programa puede compilarse desde código fuente (ver más abajo) o ejecutarse directamente con python3 wallwinxs.py
Desde código fuente	Python 3.8+
Versión del programa	1.0.8 (misma constante APP_VERSION, compartida con el resto de ediciones)

Cómo ejecutar el programa de macOS

Opción A — instalador .pkg ya compilado (recomendado, sin dependencias, Apple Silicon):

Descarga wallwinxs_<versión>_arm64.pkg desde Releases y ábrelo con doble clic para instalar con el asistente estándar de macOS.

⚠️ Al no estar firmado con un certificado de Apple Developer, Gatekeeper puede mostrar un aviso de "desarrollador no identificado" en la primera apertura. Para permitirlo: Ajustes del Sistema → Privacidad y Seguridad → Abrir de todos modos, o ejecuta el instalador desde terminal con sudo installer -pkg wallwinxs_<versión>_<arch>.pkg -target /.

wallwinxs

Esto instala el binario en /usr/local/bin/wallwinxs. Para desinstalar: sudo rm /usr/local/bin/wallwinxs.

Opción B — desde código fuente:

pip install -r requirements.txt
python3 wallwinxs.py

(el propio script ofrece instalar automáticamente colorama/pyfiglet/rich si faltan)

Cómo compilar el .pkg

El binario se genera con PyInstaller usando el spec incluido (Wallwinxs-macos.spec). Debe compilarse en macOS (PyInstaller no hace compilación cruzada), y genera un binario solo para la arquitectura del Mac donde se compila:

pip install pyinstaller
pyinstaller Wallwinxs-macos.spec   # genera dist/wallwinxs

mkdir -p pkgroot/usr/local/bin
install -m 755 dist/wallwinxs pkgroot/usr/local/bin/wallwinxs
pkgbuild --root pkgroot --identifier com.disasterxz.wallwinxs \
    --version 1.0.2 --install-location / \
    wallwinxs_1.0.3_arm64.pkg   # o el sufijo que corresponda a tu arquitectura

El repositorio incluye además un workflow de GitHub Actions (.github/workflows/build-macos.yml) que compila y empaqueta automáticamente el .pkg de Apple Silicon cada vez que se publica un Release (runner macos-14), y lo adjunta al release.

---

Releases / descargas

Cada Release de GitHub incluye los artefactos ya compilados, listos para instalar sin depender de Android Studio, Python ni herramientas de compilación:

Artefacto	Plataforma	Cómo se genera
Wallwinxs.apk	Android	Firmado con keystore propio, vía build-android.yml en GitHub Actions
Wallwinxs-x64.exe	Windows Vista/7/8/10/11, 64 bits	PyInstaller + Python 3.8 (Wallwinxs.spec) vía GitHub Actions
Wallwinxs-x86.exe	Windows Vista/7/8/10/11, 32 bits (también corre en 64 bits vía WOW64)	PyInstaller + Python 3.8 (Wallwinxs.spec) vía GitHub Actions
wallwinxs_<versión>_amd64.deb	Debian, Ubuntu, Linux Mint, Pop!_OS y derivadas	PyInstaller + dpkg-deb vía GitHub Actions
wallwinxs_<versión>_x86_64.rpm	Fedora, openSUSE, RHEL/CentOS y derivadas	PyInstaller + fpm vía GitHub Actions
wallwinxs_<versión>_x86_64.pkg.tar.zst	Arch Linux, Manjaro, EndeavourOS y derivadas	PyInstaller + fpm vía GitHub Actions
wallwinxs_<versión>_arm64.pkg	macOS con Apple Silicon (M1/M2/M3/M4)	PyInstaller + pkgbuild vía GitHub Actions (runner macos-14)

¿Qué archivo descargo según mi sistema?

Archivo	Sistema operativo	Notas
Wallwinxs-x64.exe	Windows de 64 bits (Vista, 7, 8, 8.1, 10, 11)	La opción recomendada si no sabes cuál elegir: casi todas las PC con Windows actuales son de 64 bits
Wallwinxs-x86.exe	Windows de 32 bits (Vista, 7, 8, 8.1, 10, 11)	También funciona en Windows de 64 bits (vía WOW64) si por algún motivo prefieres el binario de 32 bits
wallwinxs_<versión>_amd64.deb	Linux basado en Debian/Ubuntu (Ubuntu, Linux Mint, Pop!_OS, etc.), 64 bits	Instalar con doble clic o sudo dpkg -i archivo.deb
wallwinxs_<versión>_x86_64.rpm	Linux basado en Fedora/RHEL/openSUSE, 64 bits	Instalar con doble clic o sudo rpm -i archivo.rpm
wallwinxs_<versión>_x86_64.pkg.tar.zst	Linux basado en Arch (Arch Linux, Manjaro, EndeavourOS), 64 bits	Instalar con sudo pacman -U archivo.pkg.tar.zst
wallwinxs_<versión>_arm64.pkg	macOS con Apple Silicon (chips M1/M2/M3/M4)	Doble clic para instalar; Mac Intel debe compilar desde código fuente (ver más arriba)
Wallwinxs.apk	Android	Compilado, firmado con keystore propio y publicado automáticamente en cada Release

Imagen de contenedor (GitHub Packages)

Además de los binarios del Release, cada versión publica una imagen Docker en GitHub Packages (GHCR), útil para probar la CLI en Linux sin instalar Python:

docker pull ghcr.io/manueldxz/wallwinxs:latest
docker run -it --rm ghcr.io/manueldxz/wallwinxs:latest

Dentro de un contenedor no hay escritorio ni entorno gráfico del host, así que "establecer como fondo de pantalla" no aplica en este contexto; sirve sobre todo para explorar el buscador de Wallhaven desde la terminal.

---

API y configuración

Wallwinxs se apoya en la API pública de Wallhaven para buscar, previsualizar y descargar los fondos de pantalla. No hay ningún backend propio de Wallwinxs de por medio: cada búsqueda, descarga o marcado de favorito habla directamente con wallhaven.cc.

Wallhaven ofrece dos formas de usar su API:

• Modo público (sin API Key): funciona sin registrarse, pero solo devuelve contenido SFW. Es el modo por defecto la primera vez que abres Wallwinxs.
• Modo con tu propia API Key: al iniciar sesión en tu cuenta de Wallhaven y pegar tu API Key en Wallwinxs, se desbloquean las categorías Sketchy y NSFW (si tu cuenta las tiene habilitadas) y el acceso a tus favoritos y colecciones.

Cómo conseguir tu API Key de Wallhaven

1. Crea una cuenta gratuita en wallhaven.cc (o inicia sesión si ya tienes una).
2. Ve a wallhaven.cc/settings/account.
3. Copia el valor del campo API Key.
4. En Wallwinxs (Android, Windows, Linux o macOS), abre Ajustes → Configurar tu API Key de Wallhaven y pégala ahí.

La API Key es personal e intransferible: identifica tu cuenta de Wallhaven ante sus servidores, así que trátala como una contraseña y no la compartas ni la subas a repositorios públicos.

Dónde guarda cada app tu API Key

• La app de Android la pide en el primer arranque (ApiKeyActivity) y la guarda en SharedPreferences, en el propio dispositivo.
• El programa de escritorio (wallwinxs.py, el mismo archivo para Windows, Linux y macOS) la guarda localmente, junto al resto de tu configuración (estilo visual, carpeta de descarga):
  • Windows: ~/.wallwinxs/config.json
  • Linux: ~/.config/wallwinxs/config.json
  • macOS: ~/Library/Application Support/Wallwinxs/config.json

En ningún caso la API Key se envía a servidores de Wallwinxs ni se sube al repositorio: vive únicamente en tu equipo/dispositivo y viaja directamente hacia la API de Wallhaven en cada petición.

Notas de seguridad

• wallwinxs.py no trae ninguna API Key embebida por defecto. DEFAULT_CONFIG["api_key"] arranca vacío; sin configurar nada, el programa usa el modo público de Wallhaven (solo SFW).
• Si necesitas Sketchy/NSFW o tus favoritos, configura tu propia key desde Ajustes (ver sección anterior arriba). Nunca copies tu API Key dentro del código fuente ni la incluyas en un commit o issue público.
• Como el repositorio es público, evita también subir tu config.json local (ya está fuera del control de versiones): contiene tu API Key en texto plano.

Aviso legal y propósito del proyecto

Wallwinxs es un proyecto educativo, de desarrollo personal y de uso gratuito. No busca quitarle créditos, tráfico ni derechos a Wallhaven ni a los artistas/autores originales de los fondos de pantalla: la app solo actúa como cliente de la API pública de Wallhaven, no aloja ni redistribuye imágenes propias.

Detalles completos, incluyendo cómo se atribuye el contenido y cómo reportar cualquier inquietud, en DISCLAIMER.md.

---

_{Wallwinxs · Android · Windows · Linux · macOS}

_{Hecho por Jose Manuel Morales Ramirez (@Disasterxz) — proyecto educativo y gratuito}

_{Fondos de pantalla cortesía de Wallhaven y sus artistas · ver aviso legal}