|
| 1 | +# JukeBox 🎵 |
| 2 | + |
| 3 | +[](https://opensource.org/licenses/MIT) |
| 4 | +[]() |
| 5 | +[](https://nodejs.org/) |
| 6 | +[](https://lokijs.org/) |
| 7 | + |
| 8 | +A sleek, web-based music player designed to dynamically load and play your local MP3 collection, featuring audio visualization, play/download count tracking, and usage statistics. Built with Node.js, Express, and LokiJS. |
| 9 | + |
| 10 | + |
| 11 | +*(Screenshot of the running application)* |
| 12 | + |
| 13 | +--- |
| 14 | + |
| 15 | +## ✨ Features |
| 16 | + |
| 17 | +* **Dynamic Playlist:** Automatically scans a local `music` folder on the server for `.mp3` files on startup. |
| 18 | +* **Play/Download Count Tracking:** Records plays (past 50%) and downloads in a local LokiJS database (`jukebox.db.json`). |
| 19 | +* **Sorted Playlist:** Displays the playlist sorted by play count (most played first), with secondary alphabetical sorting. |
| 20 | +* **Usage Statistics:** In-app modal shows total visits, detailed track plays/downloads, and daily activity charts (visits/plays/downloads over last 14 days). |
| 21 | +* **Sleek UI:** Modern interface with controls for play/pause, previous/next, seek, volume, and play mode (repeat all/one, shuffle). |
| 22 | +* **Audio Visualization:** Real-time canvas-based visualization with multiple styles (Bars, Blocks, Waveform). |
| 23 | +* **Grid Playlist Display:** Visually appealing grid layout for the playlist with icons and play counts. |
| 24 | +* **Server-Side Logic:** Uses Node.js and Express to serve the application and handle API requests. |
| 25 | +* **Embedded DB:** Uses LokiJS (in-memory with file persistence) - no native dependencies required for the database. |
| 26 | + |
| 27 | +## 🎶 Music Credits & Licensing |
| 28 | + |
| 29 | +The music files used in the `music/` directory for demonstration are **license-free**. They were generated using the AI music creation platform [Suno.ai](https://www.suno.ai/). |
| 30 | + |
| 31 | +## 💻 Tech Stack |
| 32 | + |
| 33 | +* **Backend:** Node.js, Express.js |
| 34 | +* **Database:** LokiJS (`lokijs` npm package) |
| 35 | +* **Frontend:** HTML5, CSS3, JavaScript (ES6+), Chart.js |
| 36 | +* **Package Manager:** pnpm (Recommended, but npm/yarn work too) |
| 37 | +* **Icons:** Font Awesome |
| 38 | + |
| 39 | +## 🚀 Setup & Installation |
| 40 | + |
| 41 | +1. **Prerequisites:** |
| 42 | + * [Node.js](https://nodejs.org/) (LTS version recommended) installed. |
| 43 | + * [pnpm](https://pnpm.io/installation) installed globally (`npm install -g pnpm`). |
| 44 | + * `git` installed. |
| 45 | + |
| 46 | +2. **Clone the Repository (Optional):** |
| 47 | + ```bash |
| 48 | + git clone <your-repo-url> |
| 49 | + cd <project-folder-name> |
| 50 | + ``` |
| 51 | + |
| 52 | +3. **Install Dependencies:** Navigate to the project directory in your terminal and run: |
| 53 | + ```bash |
| 54 | + pnpm install |
| 55 | + ``` |
| 56 | + |
| 57 | +4. **Configure Environment:** |
| 58 | + * Copy or rename `.env.local.example` (if provided) or create a new file named `.env.local`. |
| 59 | + * Edit `.env.local` to set your desired `PORT`, `MUSIC_FOLDER` (relative path), `DB_FILENAME`, and `STATS_DAYS`. Example: |
| 60 | + ```dotenv |
| 61 | + PORT=4000 |
| 62 | + MUSIC_FOLDER=music |
| 63 | + DB_FILENAME=jukebox.db.json |
| 64 | + STATS_DAYS=7 |
| 65 | + ``` |
| 66 | + |
| 67 | +5. **Add Music:** |
| 68 | + * Create the folder specified by `MUSIC_FOLDER` in `.env.local` (e.g., `music`). |
| 69 | + * Place your `.mp3` files inside that folder. |
| 70 | + |
| 71 | +## ▶️ Running the App |
| 72 | + |
| 73 | +1. **Start the Server:** |
| 74 | + ```bash |
| 75 | + pnpm start |
| 76 | + ``` |
| 77 | + This reads `.env.local`, starts the Node.js server, and creates/updates the LokiJS database file specified by `DB_FILENAME`. |
| 78 | + |
| 79 | +2. **Access the Jukebox:** Open your web browser and navigate to: |
| 80 | + ``` |
| 81 | + http://localhost:4000 |
| 82 | + ``` |
| 83 | + *(Replace `4000` if you changed the `PORT` in `.env.local`. Use your server IP if not running locally)* |
| 84 | + |
| 85 | +The player should load, fetch the sorted playlist, track plays/downloads/visits, and display stats in the modal. |
| 86 | + |
| 87 | +## ⚙️ Configuration |
| 88 | + |
| 89 | +See the `.env.local` file for configurable options: |
| 90 | + |
| 91 | +* `PORT`: Network port the server listens on. |
| 92 | +* `MUSIC_FOLDER`: Path (relative to project root) containing `.mp3` files. |
| 93 | +* `DB_FILENAME`: Filename for the LokiJS database persistence. |
| 94 | +* `STATS_DAYS`: Number of past days to include in the stats graph (e.g., 7). |
| 95 | + |
| 96 | +## 📄 License |
| 97 | + |
| 98 | +This project is licensed under the **MIT License**. See the [LICENSE](https://opensource.org/licenses/MIT) file or badge link for details. |
| 99 | + |
| 100 | +--- |
| 101 | + |
| 102 | +## 🤖 Development Note |
| 103 | + |
| 104 | +All the code in this project was generated by **Google Gemini 2.5 Pro Experimental 03-25** based directly on iterative prompts provided by the user. The entire functional application, including setup, server logic, dynamic playlist loading, database integration (LokiJS), stats tracking and display (including charts), client-side controls, and visualization, was produced through interactive prompting over ~2 hours. |
0 commit comments