Informe Técnico y de Código:
DaemonX Music Platform
Documento técnico exhaustivo que detalla la arquitectura de software, stack tecnológico, estrategias de persistencia en la nube, optimizaciones de rendimiento y el mecanismo de alta capacidad con Exportify para la importación de listas de reproducción Spotify masivas.
Visita DaemonX Music en Vivo Online ⚡
Puedes explorar la interfaz de la aplicación en producción directamente en su dominio oficial:
Aviso Importante: Esta plataforma es un servicio privado y personal. No se pueden crear cuentas nuevas públicamente desde la web, ya que el sistema cuenta con un portal de acceso restringido (Auth Gate) administrado internamente.
1. Introducción y Objetivos del Sistema
DaemonX Music es un reproductor de música y plataforma de streaming privada en la web y aplicaciones móviles nativas (Android APK e iOS IPA), diseñada con una estética Cyberpunk / Neon Glassmorphism de alto impacto visual, optimizada tanto para monitores Ultra-Wide de escritorio como para pantallas OLED móviles.
Acceso Privado (Auth Gate)
Control de acceso estricto donde el administrador gestiona las cuentas de usuario directamente en Supabase con auto-confirmación.
Streaming sin Anuncios
Extracción continua de pistas de YouTube mediante backend serverless y motor de audio con auto-curación (Self-Healing).
Letras Sincronizadas LRCLIB
Scoring inteligente por duración, filtrado de falsos timestamps, micro-scroll centrado y calibrador interactivo en tiempo real (±1.0s).
2. Filosofía de Desarrollo y Tecnologías Clave
DaemonX Music fue diseñado deliberadamente con Vanilla JavaScript (ES6+ Modules), HTML5 semántico y CSS3 puro con Custom Properties, rechazando dependencias de frameworks SPA pesados (React, Angular o Vue):
Frontend Puro (Zero Overhead)
Sin sobrecarga de Virtual DOM ni reconciliación innecesaria. Control nativo directo sobre la Web Audio API, Canvas 2D, MediaSession y eventos táctiles a 60 FPS estables.
Vite 5 Bundler Ultra-Rápido
Entorno de desarrollo instantáneo con HMR nativo y generación de empaquetado de producción Rollup altamente optimizado menor a 130 KB en compresión Gzip.
Serverless en Netlify Functions
Micro-endpoints Node.js en AWS Lambda para búsqueda (/api/buscar), extracción de streams (/api/reproducir) y proxy fragmentado con CORS.
Capacitor 6 & CI/CD Automatizado
Puentes nativos para empaquetado Android (APK con aceleración por hardware) e iOS (IPA con UIBackgroundModes audio) compilados automáticamente en GitHub Actions sobre runners macOS-14.
3. Arquitectura del Sistema y Flujo de Datos
La plataforma sigue el patrón arquitectónico JAMstack reactivo con patrón Observer (Pub-Sub) en el cliente, desacoplado de los servicios cloud y conmutación entre fuentes de datos:
4. Análisis Detallado de Archivos y Módulos
Estructura modular dividida en responsabilidades aisladas para garantizar mantenibilidad y cero fugas de memoria:
src/main.js & src/state/store.js
Orquestador de arranque. Inicializa síncronamente los componentes, carga la caché local de LocalStorage de inmediato para un primer render sin pantalla en blanco y valida la sesión Supabase en segundo plano. El almacén reactivo (Pub-Sub) despacha eventos selectivos cuando cambia la cola o la pista activa.
src/services/playerEngine.js
Gestiona el ciclo de vida del sonido utilizando nodos de Web Audio API (GainNode para crossfade, AnalyserNode para visualización espectral) y un mecanismo de Auto-Curación (Self-Healing) que regenera URLs expiradas sin detener la reproducción.
src/services/lyricsService.js
Consume la API abierta LRCLIB. Normaliza títulos de YouTube eliminando etiquetas ("Official Music Video", "Remastered"), evalúa candidatos descartando aquellos con discrepancias mayores a 12s para evitar intros de videoclip, y provee calibración manual de desfase en vivo.
src/services/backgroundAudio.js
Previene la suspensión de reproducción cuando la pantalla se bloquea en navegadores móviles mediante un ancla de audio silencioso Keep-Alive (#bg-keepalive-audio) y la API Screen Wake Lock.
5. Módulo Especial: Solución para Listas Masivas con Exportify (Esportify)
Cuando los usuarios intentan importar listas de reproducción de Spotify extremadamente grandes (de 500, 1.000, 3.000 o más canciones), los métodos convencionales basados en la API directa de Spotify y funciones serverless fallan sistemáticamente. DaemonX Music implementó un flujo de ingesta revolucionario mediante archivos CSV de Exportify, resolviendo de raíz el problema de escala.
El Gran Desafío de las Listas Gigantes en la Web
Las aplicaciones web típicas intentan consumir el endpoint oficial GET /v1/playlists/{id}/tracks a través de una función serverless en Netlify o AWS Lambda. Esto desencadena tres barreras insalvables:
Timeouts Serverless
Netlify Functions limita la ejecución a un máximo de 10-26 segundos. Una lista de 2.000 canciones requiere múltiples peticiones paginadas que agotan el tiempo y abortan la conexión.
Rate Limiting (HTTP 429)
Spotify limita severamente las peticiones en ráfaga por segundo. Si se solicitan 50 pistas por llamada, recorrer 2.000 canciones provoca bloqueos inmediatos de cuota.
Caducidad de Tokens
Los Bearer Tokens OAuth expiran a la hora y pueden invalidarse en transferencias batch prolongadas, corrompiendo la playlist a medio importar.
La Solución de DaemonX: Integración con Exportify (Esportify) y Parser Client-Side
Para resolver esto de forma definitiva, DaemonX Music introdujo compatibilidad nativa de primer nivel con Exportify (la herramienta de código abierto líder en la comunidad para exportar bibliotecas de Spotify a CSV):
| Criterio Técnico | Importación Tradicional API Spotify | Solución DaemonX con Exportify (CSV) |
|---|---|---|
| Límite de canciones | Máximo ~100-200 | Ilimitado (5.000+ pistas) |
| Riesgo de Timeout Serverless | Alto (Corta la ejecución) | Cero (Ejecución local en navegador) |
| Tiempo de Procesamiento | 25 a 45 segundos (lento por peticiones HTTP) | < 15 milisegundos en memoria |
| Dependencia de Cuotas API | Depende de credenciales y límites de Spotify | Independiente (Sin cuota ni bloqueo) |
| Experiencia de Usuario | Espera prolongada y spinner bloqueante | Drag & Drop instantáneo con previsualización |
Código de Producción Implementado en src/components/Modals.js
Este algoritmo analiza cualquier formato de CSV emitido por Exportify, tolerando campos entrecomillados con comas internas (típico en colaboraciones como "The Weeknd, Daft Punk") y convirtiendo milisegundos a formato minutero:
function parseCsvContent(text, fileName = '') {
const lines = text.split(/\r?\n/).filter(l => l.trim().length > 0);
if (lines.length < 2) return null;
// Manejo de campos CSV con comillas escapadas y comas interiores
function splitCsvLine(line) {
const res = [];
let cur = '';
let inQuotes = false;
for (let i = 0; i < line.length; i++) {
const c = line[i];
if (c === '"') {
if (inQuotes && line[i + 1] === '"') { cur += '"'; i++; }
else { inQuotes = !inQuotes; }
} else if (c === ',' && !inQuotes) {
res.push(cur.trim());
cur = '';
} else { cur += c; }
}
res.push(cur.trim());
return res;
}
const headers = splitCsvLine(lines[0]).map(h => h.toLowerCase().trim());
const trackNameIdx = headers.findIndex(h => h.includes('track name') || h === 'title' || h === 'cancion');
const artistIdx = headers.findIndex(h => h.includes('artist') || h === 'artista' || h === 'artists');
const durationIdx = headers.findIndex(h => h.includes('duration'));
if (trackNameIdx === -1) return null;
const songs = [];
for (let i = 1; i < lines.length; i++) {
const cols = splitCsvLine(lines[i]);
if (!cols[trackNameIdx]) continue;
const title = cols[trackNameIdx].replace(/^"|"$/g, '');
const artist = artistIdx !== -1 && cols[artistIdx] ? cols[artistIdx].replace(/^"|"$/g, '') : 'Artista Desconocido';
// Conversión de Track Duration (ms) a mm:ss
let duration = '3:30';
if (durationIdx !== -1 && cols[durationIdx]) {
const ms = parseInt(cols[durationIdx], 10);
if (!isNaN(ms)) {
const sec = Math.floor(ms / 1000);
const m = Math.floor(sec / 60);
const s = sec % 60;
duration = `${m}:${s < 10 ? '0' : ''}${s}`;
}
}
songs.push({ id: `csv-${i}`, youtube_id: '', title, artist, duration, thumbnail: '/daemonx-logo.svg' });
}
return {
platform: 'spotify',
playlist: { name: fileName.replace(/\.[^/.]+$/, '') || 'Playlist Importada', song_count: songs.length },
songs
};
}
6. Motor de Audio Híbrido, Crossfade y Auto-Curación
El reproductor integra capacidades avanzadas de Web Audio API diseñadas para ofrecer reproducción continua sin pausas:
Mecanismo Self-Healing (Auto-Curación)
Los enlaces de streaming de YouTube expiran por tiempo o IP. Cuando el elemento <audio> detecta un error de red o timeout (MEDIA_ERR_SRC_NOT_SUPPORTED), el reproductor no interrumpe al usuario: automáticamente invoca de inmediato el endpoint /api/reproducir con forzado de bypass de caché, obtiene una nueva URL de stream y continúa la reproducción en el mismo segundo exacto.
Cadena de Nodos Web Audio
Estructura: MediaElementSourceNode ➔ GainNode (para crossfade suave configurable de 0 a 10s) ➔ AnalyserNode (con FFT de 64 bandas para alimentar el espectro Canvas 2D) ➔ AudioContext.destination.
7. Motor de Letras Sincronizadas LRCLIB y Calibrador
El módulo lyricsService.js ofrece sincronización de letras línea a línea al milisegundo mediante un riguroso pipeline de normalización:
1. Limpieza de Metadatos
Remueve patrones como [Official Music Video], HD, Remastered 2024 y sufijos de canales oficiales para enviar búsquedas limpias a la API abierta LRCLIB.
2. Algoritmo scoreCandidate
Compara la duración de la pista con los candidatos devueltos. Descarta automáticamente registros con discrepancia mayor a 12s para evitar desfases causados por intros teatrales de videos musicales.
3. Calibrador de Offset en Vivo
Permite al oyente ajustar el desfase con precisión de décimas de segundo (±1.0s) o pulsar el botón de alineación rápida para fijar la línea con el tiempo actual del reproductor.
8. Motor de Recomendación y Showcase Panorámico
Algoritmo heurístico local ponderado para generar el feed personalizado "Para ti ⚡":
Ponderación de Afinidades (getUserTopArtists)
- Cada canción guardada en Favoritos suma +3 puntos al artista.
- Cada reproducción registrada en el Historial suma +1 punto.
- Si la canción está entre las 5 más recientes del historial, suma un bono de +2 puntos adicionales.
- Limpieza automática de sufijos VEVO y canales temáticos (" - Topic").
Showcase Panorámico para Pantallas de PC
Para pantallas grandes, la interfaz reorganiza la vista de Artistas en un layout panorámico .artists-showcase-layout: Tarjeta Hero Spotlight en la columna izquierda (destacando al artista #1 con botón de reproducción directa de su discografía) y cuadrícula multi-columna de tarjetas .artist-wide-card a la derecha.
9. Esquema Cloud, Políticas RLS y Sincronización
Persistencia basada en PostgreSQL mediante Supabase JS Client v2 con aislamiento criptográfico total entre usuarios:
Tablas Relacionales
- public.playlists: Metadatos de listas del usuario.
- public.playlist_canciones: Pistas ordenadas por posición.
- public.favoritos: Canciones con "Me gusta".
- public.historial: Registro temporal cronológico de reproducciones.
- public.configuracion_usuario: Alias, avatar, color neón y audio quality.
Row Level Security (RLS) Obligatorio
Todas las tablas cuentan con RLS activado. Las políticas SQL comprueban inexorablemente auth.uid() = user_id. Un usuario jamás puede leer, modificar ni borrar canciones o listas pertenecientes a otro usuario, garantizando total privacidad.
Volcado por Lotes (Batch Flushing): Las modificaciones locales se sincronizan hacia Supabase cada 15 segundos en segundo plano, evitando saturar la conexión de red en móviles.
10. Auditoría de Seguridad: Garantía Zero-Leakage
El sistema fue auditado integralmente bajo estrictos estándares de ciberseguridad defensiva:
Inmunidad XSS
Todas las cadenas renderizadas pasan por escapeHtml() y las URLs externas se validan con sanitizeUrl() para bloquear inyecciones con javascript: o esquemas arbitrarios.
Cabeceras HTTP Netlify
X-Frame-Options: DENY anti-clickjacking, X-Content-Type-Options: nosniff y política estricta de referrers en la red de entrega de contenido.
Aislamiento de Secretos
El cliente web solo posee la clave anónima pública de Supabase. El secreto de Spotify (SPOTIFY_CLIENT_SECRET) reside exclusivamente en variables de servidor serverless.
11. Plataforma Móvil Nativa (Android & iOS) y CI/CD
DaemonX Music no es solo una PWA: cuenta con empaquetado nativo completo vía Capacitor 6 y un pipeline de compilación continua en GitHub Actions:
Optimizaciones Android (android/)
Aceleración por hardware forzada (android:hardwareAccelerated="true"), heap de memoria ampliado (android:largeHeap="true") y eliminación de tirones con OVER_SCROLL_NEVER en el WebView.
Persistencia en iOS (ios/)
Declaración de UIBackgroundModes: audio en el Info.plist, impidiendo que el motor WebKit del sistema operativo suspenda la música cuando el usuario bloquea el iPhone o cambia de app.
12. Atajos de Teclado Globales
Diseñados para una operación instantánea sin necesidad de recurrir al ratón o pantalla táctil:
13. Guía de Despliegue, Variables y Mantenimiento
Pasos técnicos para desplegar y mantener la plataforma en la nube:
Despliegue Web (Netlify)
- Directorio de publicación: dist
- Comando de compilación: npm run build
- Variables requeridas en panel Netlify:
- VITE_SUPABASE_URL
- VITE_SUPABASE_ANON_KEY
- SPOTIFY_CLIENT_ID (opcional)
- SPOTIFY_CLIENT_SECRET (opcional)
Comandos de Compilación Móvil
# Compilar APK de Android
npm run build:apk
# Compilar paquete estructurado de iOS
npm run build:ipa
# Sincronizar cambios de frontend en Capacitor
npx cap sync