🎵 TypeScript Music Player

A responsive audio player built from scratch. This project demonstrates how to build complex interactive applications using Object-Oriented Programming (OOP) principles and TypeScript, while maintaining a focus on simplicity and performance.

🏛️ Audio Source (Royalty-Free)

Note: To ensure this project is compliant with copyright laws, the music tracks included in this demonstration are royalty-free recordings sourced from the Library of Congress.

This allows the repository to feature a fully functional audio demo without infringing on commercial artist copyrights. If you wish to use the player for commercial tracks (e.g., Spotify top hits), simply replace the files in the assets/audio folder and update playlist.json accordingly.

---

✨ Features

Core Functionality

• Playback Controls: Play, pause, skip, and seek functionality.
• Playlist Management: Drag and drop interface to reorder songs.
• Smart Modes: Shuffle and Repeat (Repeat All, Repeat One, None).
• Live Lyrics: Reads .lrc files and highlights lyrics in sync with the audio.

User Interface

• Responsive UI: Features a "Mini Player" that expands into a full-screen view with a sliding panel.
• SEO Optimized: Structured content for better visibility.

Technical

• Type Safety: Built with TypeScript for reliable and maintainable code.
• OOP Architecture: Structured using distinct classes for Data, UI, and Logic.

---

🏗️ Architecture & OOP Design

This project avoids "spaghetti code" by splitting the logic into distinct Classes. Each class has a specific responsibility.

1. Data Layer (The Brains)

• Song Class: Represents a single music track object. It guarantees that every song has an ID, title, creator, and necessary file paths.
• PlaylistData Class: Manages the logical state of the playlist. It handles fetching data, shuffling algorithms, and repeat logic.

2. UI Layer (The Looks)

• PlaylistUI Class: Renders the visual list of songs. It manages DOM updates, highlights the active track, and handles click events.
• LyricsUI Class: Parses timestamps from standard .lrc files and synchronizes the scrolling text with the audio.
• MiniPlayerController Class: Controls the player interface states, handling the transition animations between the compact mini-player and the expanded view.

3. Logic & Helpers (The Tools)

• AudioController Class: A wrapper facade around the HTML5 <audio> element. It abstracts complex event listeners into clean class methods.
• DragAndDropHandler Class: A specialized utility class that manages drag-and-drop logic for both Desktop (Mouse) and Mobile (Touch).

---

📘 Why TypeScript?

Using TypeScript in this project ensures the code is robust:

1. Interfaces (SongData): We define strictly what a "Song" looks like. If the JSON data structure changes, TypeScript catches the error at compile time.
2. Enums (RepeatMode): Instead of using fragile strings like "one" or "all", we use strict Enums, preventing typos.
3. Type Safety: Variables like currentTime are always numbers and ids are always strings, preventing runtime crashes.

---

📂 Project Folder Structure

/typescript-media-player/
│
├── index.html          # The main HTML structure
├── main.ts             # The source TypeScript code
├── js/
│   └── main.js         # Compiled JavaScript (generated from typescript)
├── styles/
│   └── main.css        # Custom styling
├── assets/
│   ├── playlist/       # JSON configuration
│   ├── audio/          # Royalty-free MP3 files (LOC)
│   ├── image/          # Album art thumbnails
│   └── lyrics/         # LRC lyric files
│
├── dev-log.md          # Development logs and notes
├── scope.md            # Project scope and planning
└── README.md           # Project documentation

---

🚀 How to Run

1. Prerequisites: Ensure you have Node.js installed to use the TypeScript compiler.

2. Install TypeScript: Open your terminal or command prompt and run:

   npm install -g typescript

3. Compile the Code: Run the TypeScript compiler to generate the browser-readable JavaScript file from your TypeScript source:

   tsc main.ts --target es6 --outDir js

4. Start a Local Server: Because this app uses the fetch() API to load the playlist JSON and Lyrics files, you cannot open index.html directly from your file explorer due to browser security policies (CORS). You must use a local server:

   • VS Code Users (Recommended): Install the "Live Server" extension, right-click index.html, and select "Open with Live Server".

   • Python Users: Open your terminal in the project folder and run:

     python -m http.server

     Then open http://localhost:8000 in your browser.