bnair/MusicAnalyser
1
0
Fork 0
mirror of https://github.com/bnair123/MusicAnalyser.git synced 2026-02-25 11:46:07 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
26b4895695de294f81f3eb6222c3e9a5f35518d6
MusicAnalyser/docs/FRONTEND.md
bnair123 887e78bf47 Add skip tracking, compressed heatmap, listening log, docs, tests, and OpenAI support 
Major changes:
- Add skip tracking: poll currently-playing every 15s, detect skips (<30s listened)
- Add listening-log and sessions API endpoints
- Fix ReccoBeats client to extract spotify_id from href response
- Compress heatmap from 24 hours to 6 x 4-hour blocks
- Add OpenAI support in narrative service (use max_completion_tokens for new models)
- Add ListeningLog component with timeline and list views
- Update all frontend components to use real data (album art, play counts)
- Add docker-compose external network (dockernet) support
- Add comprehensive documentation (API, DATA_MODEL, ARCHITECTURE, FRONTEND)
- Add unit tests for ingest and API endpoints
2025-12-30 00:15:01 +04:00

2.5 KiB
Raw Blame History

Frontend Documentation

The frontend is a React application built with Vite and Tailwind CSS. It uses Ant Design for some UI components and Recharts for data visualization.

Main Components

Dashboard.jsx

The primary layout component that manages data fetching and state.

  • Features:
    • Handles API calls to /snapshots and /trigger-analysis.
    • Implements local storage caching to reduce API load.
    • Displays a global loading state during analysis.
    • Contains the main header with a refresh trigger.

NarrativeSection.jsx

Displays the AI-generated qualitative analysis.

  • Props:
    • narrative: Object containing persona, vibe_check_short, and roast.
    • vibe: Object containing audio features used to generate dynamic tags.
  • Purpose: Gives the user a "identity" based on their music taste (e.g., "THE MELANCHOLIC ARCHITECT").

StatsGrid.jsx

A grid of high-level metric cards.

  • Props:
    • metrics: The metrics_payload from a snapshot.
  • Displays:
    • Minutes Listened: Total listening time converted to days.
    • Obsession: The #1 most played track with album art background.
    • Unique Artists: Count of different artists encountered.
    • Hipster Score: A percentage indicating how obscure the user's taste is.

VibeRadar.jsx

Visualizes the "Sonic DNA" of the user.

  • Props:
    • vibe: Audio feature averages (acousticness, danceability, energy, etc.).
  • Visuals:
    • Radar Chart: Shows the balance of audio features.
    • Mood Clusters: Floating bubbles representing "Party", "Focus", and "Chill" percentages.
    • Whiplash Meter: Shows volatility in tempo, energy, and valence between consecutive tracks.

TopRotation.jsx

A horizontal scrolling list of the most played tracks.

  • Props:
    • volume: Object containing top_tracks array.
  • Purpose: Quick view of recent favorites.

HeatMap.jsx

Visualizes when the user listens to music.

  • Props:
    • timeHabits: Compressed heatmap data (7x6 grid for days/time blocks).
    • sessions: List of recent listening sessions.
  • Visuals:
    • Grid: Days of the week vs. Time blocks (12am, 4am, etc.).
    • Session Timeline: Vertical list of recent listening bouts with session type (Marathon vs. Micro).

ListeningLog.jsx

A detailed view of individual plays.

  • Features:
    • Timeline View: Visualizes listening sessions across the day for the last 7 days.
    • List View: A table of individual plays with skip status detection.
    • Timeframe Filter: Toggle between 24h, 7d, 14d, and 30d views.
Reference in New Issue View Git Blame Copy Permalink