SpotifyWebPlayer

Widget web de reproductor musical construido con React y Vite. El proyecto recrea una experiencia tipo player con carrusel de álbumes, cola de reproducción, favoritos, controles de volumen, shuffle y transiciones animadas.

Las canciones se configuran por título y artista en src/data/spotifyTracks.json. La app consulta Spotify Web API desde un proxy local en Node, completa automáticamente portada, artistas, título, álbum y duración, y calcula colores dinámicos desde la portada de cada canción.

Características

• Reproductor interactivo con controles de play, pausa, siguiente y anterior.
• Carrusel de portadas con cambios visuales por canción.
• Cola de reproducción con vista expandible y mini player.
• Favoritos con notificación visual.
• Controles de volumen, mute y shuffle.
• Integración visual con estrellas del repositorio de GitHub.
• Portadas, artistas, títulos, álbumes y duraciones cargados desde Spotify.
• Colores dinámicos calculados desde la portada de cada canción.
• Lista editable en JSON sin tocar el código del reproductor.
• Proxy local para no exponer el Client Secret en el frontend.
• Caché local para reducir llamadas a Spotify y evitar recargas innecesarias.
• Reintentos automáticos cuando Spotify responde con rate limit.

Tecnologías

• React
• Vite
• Tailwind CSS
• Lucide React

Requisitos

• Node.js 18 o superior
• npm

Instalación

npm install

Configuración de Spotify

1. En Spotify for Developers crea una app.
2. Llena el formulario con estos valores sugeridos:

App name: SpotifyWebPlayer
App description: Widget web personal que busca canciones por título y artista, y muestra metadatos públicos de canciones usando Spotify Web API.
Website: http://127.0.0.1:5173
Redirect URI: http://127.0.0.1:5173/callback
API/SDKs: Web API

No uses localhost en Redirect URI: Spotify lo rechaza. Este proyecto usa Client Credentials para consultar metadatos públicos; el redirect no se usa en la app, pero Spotify lo pide al crear la aplicación.

3. Copia el Client ID y Client Secret de tu app de Spotify.
4. Crea un archivo .env a partir de .env.example:

cp .env.example .env

5. Pega tus credenciales:

SPOTIFY_CLIENT_ID=tu_client_id
SPOTIFY_CLIENT_SECRET=tu_client_secret
SPOTIFY_MARKET=MX

Nunca subas .env al repositorio. Ya está ignorado por Git.

El archivo .env.example queda como plantilla pública. El archivo .env es solo local y debe contener tus credenciales reales.

Uso

Inicia el servidor de desarrollo:

npm run dev

Durante el desarrollo, Vite expone estos endpoints locales:

/api/tracks    Resuelve canciones en Spotify y devuelve metadatos normalizados
/api/artwork   Carga portadas de Spotify para calcular colores sin problemas de CORS

Integración con Spotify

El frontend nunca llama directamente a Spotify ni recibe el Client Secret. En su lugar, consulta /api/tracks, un proxy local definido en api/spotify.js.

Ese proxy hace lo siguiente:

• Lee SPOTIFY_CLIENT_ID, SPOTIFY_CLIENT_SECRET y SPOTIFY_MARKET desde .env.
• Pide un access token con Client Credentials.
• Resuelve las 6 canciones por defecto usando sus IDs de Spotify para evitar búsquedas repetidas.
• Usa búsqueda por título y artista solo para canciones nuevas agregadas en src/data/spotifyTracks.json.
• Guarda la respuesta normalizada en .cache/spotify-tracks.json durante unos minutos.
• Reutiliza caché vencido si Spotify responde temporalmente con rate limit.
• Devuelve 429 con datos de reintento cuando Spotify limita las búsquedas y no hay caché disponible.
• Expone /api/artwork para cargar portadas de Spotify desde el mismo origen y calcular colores dinámicos con canvas.

En el navegador, la app espera a que /api/tracks responda antes de montar el reproductor. Si Spotify responde con 429, el frontend mantiene el estado de carga y reintenta automáticamente.

Genera una versión de producción:

npm run build

Previsualiza el build:

npm run preview

Sirve el build con el endpoint seguro de Spotify:

npm run build
npm start

Estructura

src/
  components/   Componentes visuales del reproductor
  data/         Lista editable de canciones y datos de GitHub
  hooks/        Lógica de reproducción, favoritos, cola y animaciones
  styles/       Estilos globales y del player
  utils/        Utilidades compartidas y cálculo de colores
api/
  spotify.js    Proxy seguro para Spotify Web API y portadas
assets/
  svg/          Íconos
.cache/
  spotify-tracks.json  Caché local generado automáticamente

Personalización

Edita las canciones desde src/data/spotifyTracks.json.

[
  {
    "title": "Starboy",
    "artist": "The Weeknd, Daft Punk"
  }
]

Para agregar una canción, agrega otro objeto con title y artist. Para quitarla, elimina el objeto. El servidor consulta Spotify y completa automáticamente:

• Portada
• Artistas
• Título oficial
• Álbum
• Duración
• Enlace y URI de Spotify
• Colores visuales basados en la portada

Ejemplo con varias canciones:

[
  {
    "title": "Starboy",
    "artist": "The Weeknd, Daft Punk"
  },
  {
    "title": "COLOGNE",
    "artist": "Junior H, Ovi"
  }
]

Si las credenciales de Spotify faltan o son inválidas, la app muestra un estado de configuración. Si están correctas, primero consulta la API y después monta el reproductor con los datos reales.

Licencia

Este proyecto está bajo la licencia MIT. Consulta el archivo LICENSE para más detalles.