🎵 Musicy - Music Folder Browser

what's this?

A simple mp3 player for desktop; for those who browse their music by artist and cant be a DJ while working :)

Getting Started

Installation

# Install dependencies
npm install

# Start dev server
npm run dev

# Build for production
npm run build

The app runs on http://localhost:5173 by default.

roadmap

last.fm

JSON based scrobbly

saved to .profile

moods (self edit/add)

im feeling..... in home

home page

reccomendations based on scrobbly

key bindings space = toggle play/pause; enter letter = jump to artists begginning with letter; ctrl + scroll = avatar size

exstensive art retrevial methods

....this is part of scripty (tbd)

player component build

ꜛ todo! ꜛ

artist page build

artist banner ontop with shuffle FAB, side scroll albums, top scrobbled songs

edit roadmap :) / gain clearer path

.profile in working dir for multiple profiles

add profile switcher logic

screenshots

everything below has been written by ai....

Architecture & Extensibility

Core Concepts

The app uses React contexts for state management (Navigation, Preferences, Artist) and custom hooks for UI logic abstraction.

The useGridLayout hook is fully extensible - it accepts configurable parameters:

• gridWidth - number of columns (3-12)
• containerSelector - CSS selector for the grid container (defaults to .musicy-container)
• containerPadding - total padding in pixels (defaults to 48 for 24px each side)
• gapSize - gap between grid items in pixels (defaults to 24)

This allows new components to reuse the same layout logic with different parameters, and calculations can be modified without touching view components. Other custom hooks can follow the same pattern for extensibility.

Responsive Grid Behavior

Grid updates dynamically when grid width preference changes. Card widths are calculated to divide the available container width equally while maintaining consistent gaps. Avatar sizes scale proportionally using 140 * sqrt(7 / gridWidth) to preserve visual area.

Technologies

React 19, TypeScript, Vite 7, BeerCSS 4, Material Dynamic Colors, CSS 3

Browser Support

Chrome 90+, Firefox 88+, Safari 14+, Edge 90+

License

MIT