ArchiveTune Desktop

Port no oficial de ArchiveTune (app Android de YouTube Music) a Qt/QML para Linux de escritorio. Reproduce música de YouTube Music y archivos locales, con verificaciones en niri y KDE Plasma sobre Wayland.

Proyecto local/personal, no afiliado al original. No se envían contribuciones a los repositorios de rukamori. Es una obra derivada y se distribuye bajo GPL-3.0-or-later, la misma licencia del proyecto original.

Estado

Versión candidata 0.4.0rc1, todavía no estable. Hay verificaciones manuales parciales en niri y KDE Wayland; no cubren automáticamente los cambios posteriores. Consultá docs/TESTING.md para ejecutarlas y TODO.Md para ver el estado del trabajo pendiente. Los hallazgos técnicos están en docs/NOTES.md.

Funciones disponibles:

• Inicio con recomendaciones, novedades, favoritos olvidados, estaciones y pistas para seguir escuchando; búsqueda y una sección independiente para explorar géneros y estados de ánimo.
• Páginas de artistas, álbumes y listas; reproducción en streaming y de archivos locales; cola con shuffle, repetición y reproducción automática.
• Biblioteca local persistente con favoritos, listas, historial, descargas y estadísticas de escucha. Scrobbling opcional a Maloja.
• Playlists locales y de cuenta, intercambio JSON/CSV, cola reordenable por arrastre y selección múltiple.
• Álbumes en Descargas y Local reconocidos por metadatos, agrupados por álbum y artista del álbum, con orden por número de pista. Las canciones sin álbum siguen disponibles por separado.
• Letras de varios proveedores con fallback, sincronización cuando el proveedor ofrece tiempos, romanización automática del japonés, traducción opcional y letras embebidas en archivos locales.
• SponsorBlock, sesión opcional de Google, MPRIS, notificaciones de escritorio y ajustes persistentes.

Pendiente o fuera del alcance actual: ecualizador, normalización de volumen, controles de velocidad/tono, crossfade, paquetes de distribución (AppImage/Flatpak/AUR), Discord RPC, podcasts, canvas, Shazam, widgets y Android Auto/TV. El detalle del roadmap está en TODO.Md.

Requisitos del sistema

• Linux con Wayland o X11; comprobaciones visuales parciales en niri y KDE Plasma Wayland
• Python 3.11+
• libmpv (libmpv.so) — motor de audio
• ffmpeg — descargas y conversión a opus
• deno o node — solver de desafíos JS de yt-dlp
• node + npm — provider local de PO tokens (bgutil)
• Sesión de escritorio con D-Bus para MPRIS y notificaciones
• Opcional: playerctl para controlar el reproductor o verificar MPRIS

# Arch / CachyOS
sudo pacman -S --needed python mpv ffmpeg deno nodejs npm playerctl

# Debian / Ubuntu
sudo apt install python3 python3-venv libmpv2 ffmpeg nodejs npm playerctl

Instalación

Desde el código fuente; esta candidata no incluye AppImage, Flatpak ni paquete AUR.

git clone https://git.matias7235.com.ar/matias/ArchiveTuneDesktop.git
cd ArchiveTuneDesktop
python3 -m venv .venv
.venv/bin/python -m pip install -e .

Python debe ser 3.11 o superior. Si preferís uv, podés reemplazar los dos últimos comandos por uv venv y uv pip install -e ..

Provider de PO tokens (necesario para reproducir)

YouTube exige un proof-of-origin token para entregar los formatos de audio. El plugin de yt-dlp ya se instala con las dependencias; falta el provider local, que se usa en modo script (no requiere ningún servicio corriendo):

git clone https://github.com/Brainicism/bgutil-ytdlp-pot-provider ~/bgutil-ytdlp-pot-provider
cd ~/bgutil-ytdlp-pot-provider/server
npm ci
npx tsc

La app lo busca sola en ~/bgutil-ytdlp-pot-provider/server y en $XDG_DATA_HOME/bgutil-ytdlp-pot-provider/server. Si lo instalás en otro lado, cambialo en Ajustes → Provider de PO tokens o con la variable ARCHIVETUNE_POT_SERVER.

Sin el provider no funciona el streaming de YouTube; los archivos locales no lo necesitan.

Ejecución

.venv/bin/archivetune-desktop --doctor
.venv/bin/archivetune-desktop

--doctor comprueba las dependencias Python básicas y muestra las rutas XDG; no prueba el streaming ni valida por completo ffmpeg, el runtime JavaScript o el provider.

Para forzar Wayland:

QT_QPA_PLATFORM=wayland .venv/bin/archivetune-desktop

Flags útiles

Flag	Efecto
--temporary-profile	inicia con cuenta, biblioteca, ajustes, caché y descargas aislados; elimina el perfil temporal al salir normalmente
--search "consulta"	abre la app con esa búsqueda ya hecha
--play-first	reproduce el primer resultado de la búsqueda
--download-first	descarga el primer resultado de la búsqueda
--local-folder RUTA	escanea esa carpeta de música al arrancar
--play-local	reproduce la primera pista local
--overlay player|settings	abre el reproductor o los ajustes al iniciar
--doctor	verifica dependencias y muestra las rutas XDG
--version	muestra la versión

Uso básico

Para probar el login sin cerrar tu sesión habitual:

.venv/bin/archivetune-desktop --temporary-profile --overlay settings

El perfil habitual no se modifica. Firefox y el provider de PO tokens siguen disponibles. Los datos del perfil temporal, incluidas sus descargas, se eliminan al salir normalmente; una terminación forzada puede dejar la carpeta temporal en disco. Los archivos locales externos y las acciones sobre la cuenta de YouTube no quedan aislados.

• Tarjetas: el clic abre el detalle; ⋮ ofrece descarga, cola, agregado a playlist y navegación según los datos disponibles.
• Playlists: «Listas» reúne las del equipo y las de la cuenta. Son independientes, sin sincronización automática. Las listas remotas solo se editan cuando tenés permisos.
• Agregar canciones: abrí una lista editable y pulsá «Agregar canciones». Buscá o navegá a tus pistas y usá +, «Agregar a la lista» de la selección o la acción del álbum. El destino se conserva hasta pulsar «Listo» o Esc. Las canciones repetidas se omiten.
• Cola: reproducir una playlist reemplaza la cola; «Agregar a la cola» conserva lo que suena. Arrastrá el tirador de una fila para cambiar el orden sin modificar la playlist original.
• Selección múltiple: pulsá «Seleccionar» y marcá casillas. En la cola podés quitar las entradas seleccionadas; seleccionar una casilla no inicia reproducción.
• Archivos locales: agregá carpetas desde Ajustes. Local y Descargas muestran álbumes reconocidos por etiquetas; no se busca ni corrige su metadata en Internet.
• Respaldo: exportá playlists a JSON o CSV. JSON conserva metadatos, orden y portada, no archivos de audio; la importación crea una lista local y muestra una vista previa.

Atajos: Espacio pausa/reanuda; ←/→ retrocede/avanza 10 segundos; N/P cambia de pista; F cambia favorito; / enfoca la búsqueda; Esc cierra el diálogo o modo activo.

Integración con el escritorio

Desde la carpeta del repositorio, instalá el acceso en el menú de aplicaciones:

mkdir -p ~/.local/share/applications
sed -e "s|^Exec=.*|Exec=\"$PWD/.venv/bin/archivetune-desktop\"|" \
    -e 's|^Icon=.*|Icon=audio-x-generic|' \
    data/archivetune-desktop.desktop > ~/.local/share/applications/archivetune-desktop.desktop

El acceso apunta a la instalación actual y usa un icono del tema. Si movés la carpeta, repetí el comando. MPRIS se registra como org.mpris.MediaPlayer2.archivetune; permite el control desde teclas multimedia, widgets del escritorio y playerctl, según la configuración del escritorio:

playerctl -p archivetune play-pause
playerctl -p archivetune metadata

Cuenta de Google (opcional)

El botón de la barra superior abre una ventana con la página real de Google (navegador integrado, QtWebEngine) donde se inicia sesión como en cualquier navegador. Al terminar, la app guarda la cookie y cierra la ventana sola.

Google a veces rechaza el login desde navegadores embebidos («este navegador o app no es seguro»). Si te pasa, en Ajustes → Otras formas de iniciar sesión tenés dos salidas:

• Leer la sesión de tu navegador (lo más simple): iniciá sesión en YouTube Music desde Brave/Chrome/Chromium y la app toma las cookies de ese perfil. No hace falta escribir la contraseña acá.
• Pegar la cookie a mano: copiá el header Cookie de las herramientas de desarrollo.

Con la sesión iniciada, Ajustes → Cuenta de Google abre Me gusta, Tu biblioteca, Playlists, Suscripciones e Historial de tu cuenta, y además bajan los avisos de «no soy un robot» al reproducir. Si tenés el historial de YouTube desactivado, esa página lo informa en lugar de fallar.

Podés guardar varias cuentas y cambiar entre ellas desde la aplicación.

Las cookies se guardan sin cifrar, con permisos 600, bajo ~/.config/archivetune-desktop/accounts/ (session_*.json y cookies_*.txt), salvo que cambies XDG_CONFIG_HOME. Son credenciales de Google: no las compartas ni las incluyas en un respaldo público. Cerrar sesión elimina los archivos de la cuenta activa, no los de todas las cuentas.

La sesión caduca cuando Google la invalida. Cuando pasa, la app lo detecta, avisa en Ajustes con un ⚠ en la barra y se puede volver a iniciar sesión sin perder nada más.

Solución de problemas

• Requested format is not available / Sign in to confirm you're not a bot: revisá que el provider de PO tokens esté detectado (Ajustes) y que deno esté instalado. Si YouTube marcó la IP por muchas peticiones seguidas (HTTP 429), hay que esperar a que se libere; como alternativa se puede usar cookies del navegador con yt-dlp (--cookies-from-browser firefox), todavía no expuesto en la app.
• No suena nada: revisá el mensaje de error, libmpv y la salida de audio. Para streaming, comprobá también el provider, el runtime JavaScript y la sesión si YouTube la exige.
• No hay letras: hay una cadena de proveedores con fallback y letras locales embebidas; no todas las canciones tienen letras. El orden y los proveedores se ajustan en Ajustes.
• SponsorBlock no saltea nada: los segmentos los carga la comunidad, así que no todas las canciones los tienen (en YouTube Music es frecuente en videos musicales y en subidas con intro o cierre). En Ajustes → SponsorBlock se eligen las categorías; si la API no responde, la reproducción sigue igual sin saltear nada.
• La ventana de login dice «este navegador o app no es seguro»: usá el campo de Ajustes para pegar el header Cookie de las herramientas de desarrollo; la cookie vale igual.
• La barra muestra ⚠ y Ajustes avisa que la sesión caducó: Google invalidó la cookie. Volvé a iniciar sesión; mientras tanto la reproducción y los archivos locales siguen funcionando.
• Idioma/acentos: libmpv exige LC_NUMERIC=C; la app lo fija sola antes de crear el motor.
• Actualizaste, pero los controles siguen igual: cerrá y volvé a abrir ArchiveTune; los cambios Python/QML no se recargan automáticamente en una ventana ya abierta.
• No se reconoce un álbum local: comprobá las etiquetas de álbum, artista del álbum y número de pista del archivo. Un nombre de carpeta no sustituye esas etiquetas.

Verificación

.venv/bin/python scripts/run_checks.py

Ejecuta checks offline y native con Qt offscreen; no necesita abrir la aplicación. La candidata tiene 42 checks verdes. No equivale a una verificación visual en niri ni a probar la cuenta real. Los checks de red solo se ejecutan explícitamente con --group live y pueden generar límites de peticiones en los servicios externos. Contrato: docs/TESTING.md.

Estructura

archivetune_desktop/
├── application/ # coordinación sin Qt: catálogo, reproducción, playlists, cuentas y biblioteca
├── backends/    # ytmusicapi (catálogo/letras), yt-dlp (streams/descargas), opciones comunes
├── player/      # motor python-mpv y cola de reproducción
├── library/     # SQLite versionado (favoritos, playlists, historial, local, descargas)
├── lyrics/      # parser LRC y proveedores de letras
├── localmedia/  # escaneo de audio local con mutagen
├── downloads/   # descargas offline con progreso y cancelación
├── mpris/       # servicio D-Bus org.mpris.MediaPlayer2
├── account/     # cookies de Google, sesión persistente y firma SAPISIDHASH
├── ui/          # puente QObject y QML
├── sponsorblock.py  # segmentos de la API pública de SponsorBlock
├── settings.py  # configuración persistente en JSON
└── paths.py     # rutas XDG

La lógica de negocio (backends, cola, biblioteca, letras) no depende de Qt: la UI solo la consume a través de ui/bridge.py.

Documentación

• docs/README.md — índice: para qué sirve cada documento
• docs/TESTING.md — contrato, grupos de checks y verificaciones manuales complementarias
• docs/RELEASE_NOTES.md — cambios y límites de la candidata
• docs/NOTES.md — gotchas técnicos de libmpv, yt-dlp, Qt, QML y YouTube
• docs/CONVENTIONS.md — convenciones de código y documentación

Licencia

GPL-3.0-or-later. Obra derivada de ArchiveTune (rukamori) y de sus dependencias.