# ๐ต Music Player
A lightweight, browser-based music player built with **vanilla JavaScript, HTML and CSS** โ no frameworks, no build step. Play your own songs, edit track details, manage cover art, sort and search your playlist, and keep everything saved to a real folder on your disk via the **File System Access API**.
> The cover art above is the app's default placeholder logo. Your own songs and covers stay on your machine.
### ๐ฌ Demo
โถ๏ธ A ~1-minute walkthrough (with sound) of every control plus the drag-and-drop file actions โ adding an MP3, changing the cover, and connecting a folder. **[Watch / download the demo video](music-player-demo.mp4)** if the player above doesn't load.
## โจ Features
- ๐ง **Playback** โ play/pause, next/previous, a seekable progress bar and live time display
- ๐ **Autoplay** โ toggle automatically playing the next track
- ๐ **Volume** โ slider with mute toggle; the level is remembered between sessions
- ๐ผ๏ธ **Cover art** โ set a per-song cover by **dragging an image** onto the album art
- โ๏ธ **Editable details** โ click the title/artist to rename them inline
- ๐ **Save to disk** โ connect a real folder and your songs, covers and `musicList.json` are written there
- โฌ๏ธ **Add songs** โ drag audio files onto the card, or use the upload button
- ๐ **Search** โ filter the playlist as you type
- โ๏ธ **Sort** โ order the playlist AโZ / ZโA (Turkish-aware collation)
- ๐๏ธ **Manage** โ delete a single song, or clear the whole playlist
- โจ๏ธ **Keyboard shortcuts** โ control everything without the mouse
- ๐งน **Self-healing list** โ songs whose files were deleted from disk are pruned automatically
## ๐ Getting Started
Because the app uses the File System Access API and `fetch`, serve it over HTTP (not by opening the file directly):
```bash
# from the project folder
npx serve
```
Then open the shown `http://localhost:โฆ` URL. Use a **Chromium-based browser (Chrome / Edge)** for the folder-saving features.
## ๐ Connecting a Folder
To permanently save uploaded songs/cover images to disk and keep
`musicList.json` updated, you first need to connect to a folder.
1. Click the folder icon (๐ `#connect-folder-btn`) in the controls
**or** drag an actual folder from your file explorer and drop it
anywhere on the player card.
2. If you used the icon, a picker opens โ select **any folder**. If
you dragged a folder instead, the browser will ask for
read/write permission for it. Either way, it does not have to be
this project's own folder or the folder the dev server is
serving, and if it doesn't already contain `music/` and `img/`
subfolders, they're created automatically.
3. Once the icon turns purple, the connection is established; you
only need to do this once, the browser remembers the permission.
Connecting to a folder clears the current playlist, so you start
fresh with whatever you add from the newly connected folder.
Songs and cover images you upload or drag-and-drop are written into
the connected folder's `music/`/`img/` subfolders and are played back
by reading the files directly from disk (via the File System Access
API), not over HTTP. This means playback works regardless of which
folder the dev server happens to be serving.
**Notes**
- This feature relies on the File System Access API, so it only
works in Chromium-based browsers such as Chrome/Edge.
- If you upload or drag-and-drop a song while not connected to a
folder, the file only plays for that session (until the page
closes), is not saved to disk or `musicList.json`, and a warning
is shown.
- To add a song, **drag and drop** the file anywhere on the player
card or click the upload icon. To change a **cover image**, drag
and drop the image onto the album art.
- Click the trash icon (๐๏ธ `#clear-playlist-btn`) to clear the
current playlist (asks for confirmation first). If connected to a
folder, this **permanently deletes every file** in that folder's
`music/` and `img/` subfolders and saves the now-empty list to
`musicList.json`. This cannot be undone โ there is no recycle bin
involved, the files are gone.
## โจ๏ธ Keyboard Shortcuts
Shortcuts are always active unless you're focused on an editable
field, such as the title/artist fields.
| Key | Action |
| ----- | ------------------------- |
| Space | Play / Pause |
| โ | Next song |
| โ | Previous song |
| โ | Increase volume (10%) |
| โ | Decrease volume (10%) |
| M | Mute / Unmute |
| R | Toggle autoplay next song |
## ๐ ๏ธ Built With
- Vanilla JavaScript (ES classes, `async`/`await`)
- [File System Access API](https://developer.mozilla.org/docs/Web/API/File_System_API) + IndexedDB (for remembering the connected folder)
- [Font Awesome](https://fontawesome.com/) icons