PROJECT OVERVIEW:
The project aims to create a single-page application (SPA) called 'Müzik Kompozisyonu İçin Dijital Rehber' (Digital Guide for Music Composition). This platform addresses the need for accessible and interactive learning resources in computer music composition and production. It provides users with structured learning modules, practical tools like a basic synthesizer and a MIDI editor, and a curated library of resources. The core value proposition is to empower aspiring musicians and producers with the knowledge and tools to create music using digital technologies, offering a comprehensive yet beginner-friendly learning experience.
TECH STACK:
- Frontend Framework: React (using Vite for faster development)
- Styling: Tailwind CSS for utility-first styling and rapid UI development.
- State Management: Zustand for efficient global state management.
- Routing: React Router DOM for client-side navigation.
- Audio Synthesis: Web Audio API for the built-in synthesizer.
- MIDI Handling: `midi-player-js` or similar library for MIDI file playback and potentially editing.
- Local Storage: For persisting user progress and settings.
CORE FEATURES:
1. **Interactive Learning Modules:**
* **User Flow:** Users can navigate to the 'Learn' section, browse available modules (e.g., 'Introduction to Digital Audio', 'Basic Synthesis Techniques', 'MIDI Fundamentals'). Upon selecting a module, they are presented with a series of lessons. Each lesson includes text, embedded videos (placeholders or links), interactive examples (like sliders controlling synth parameters), and quizzes. Completing a lesson marks it as done in the user's progress.
* **Details:** Modules should be structured logically, starting with fundamental concepts and progressing to more advanced topics. Progress should be saved locally or via user authentication (for MVP, local storage is sufficient).
2. **Basic Web-Based Synthesizer:**
* **User Flow:** Users access the 'Tools' section and select 'Synthesizer'. They are presented with controls for oscillator type (sine, square, saw, triangle), ADSR envelope (Attack, Decay, Sustain, Release), filter (cutoff, resonance), and effects (e.g., delay, reverb - optional for MVP). Users can play notes using their keyboard (QWERTY mapping) or on-screen piano keys. They can save their current settings as presets.
* **Details:** Utilizes the Web Audio API to generate and manipulate audio waveforms. Controls should be intuitive sliders and dropdowns. Keyboard mapping should be clearly indicated.
3. **Simple Notation & MIDI Editor:**
* **User Flow:** In the 'Tools' section, users select 'MIDI Editor'. A piano roll interface is displayed. Users can click on the grid to add/remove notes, adjust note duration and velocity. They can play back the created sequence using the integrated synth or export it as a MIDI file.
* **Details:** A visual representation of a piano roll. Grid-based input. Basic playback functionality. MIDI export using a library like `Tone.js` or `midi-writer-js`.
4. **Resource Library:**
* **User Flow:** Users visit the 'Resources' section. They can see a categorized list of links to external PDFs, articles, and relevant websites. Each entry includes a title, brief description, and a link. A search or filter functionality can be added later.
* **Details:** Simple list view. Primarily links to external content as mentioned in the original Hacker News post.
5. **User Profiles & Progress Tracking (Local Storage based for MVP):**
* **User Flow:** A dedicated 'Profile' or 'Dashboard' area. Displays completed modules, saved synth presets, and created MIDI files (if stored locally).
* **Details:** Uses `localStorage` to store which modules are completed, and potentially settings for the synth and simple MIDI sequences. No actual user accounts in MVP.
UI/UX DESIGN:
- **Layout:** A clean, modern, single-page layout. A persistent sidebar navigation (collapsible on smaller screens) for accessing Learn, Tools, Resources, and Profile. Main content area displays the selected section.
- **Color Palette:** Primary: `#0f172a` (Dark background), Secondary: `#1e293b` (Slightly lighter background for cards/sections), Accent: `#3b82f6` (Vibrant blue for interactive elements, buttons, links), Text: `#e2e8f0` (Light gray for readability).
- **Typography:** Headings: 'Inter' (Bold, sans-serif), Body Text: 'Roboto' (Regular, sans-serif). Ensure good readability and hierarchy.
- **Responsive Design:** Mobile-first approach. Sidebar collapses into a hamburger menu on small screens. All components and tools should adapt to various screen sizes, ensuring usability on desktops, tablets, and smartphones.
- **Interactivity:** Clear visual feedback for interactive elements (buttons, sliders, keys). Loading indicators for any data fetching or processing.
COMPONENT BREAKDOWN:
- `App.jsx`: Main application component, sets up routing and global layout.
- `Layout.jsx`: Contains the main structure: sidebar navigation and content area.
- `Sidebar.jsx`: Navigation menu component. Props: `activeLink` (string).
- `Learn.jsx`: Displays the list of learning modules. Fetches module data.
- `ModuleList.jsx`: Renders individual module cards. Props: `modules` (array).
- `ModuleCard.jsx`: Displays a single module summary. Props: `module` (object), `onComplete` (function).
- `Lesson.jsx`: Displays the content of a single lesson. Props: `lesson` (object), `isCompleted` (boolean).
- `Tools.jsx`: Container for different tools (Synth, MIDI Editor).
- `Synthesizer.jsx`: The web-based synthesizer UI and logic. Props: `audioContext` (AudioContext).
- `OscillatorControls.jsx`: Controls for oscillator type.
- `EnvelopeControls.jsx`: ADSR envelope sliders.
- `FilterControls.jsx`: Filter cutoff/resonance sliders.
- `Keyboard.jsx`: On-screen piano keyboard.
- `MidiEditor.jsx`: The piano roll interface and MIDI logic.
- `PianoRoll.jsx`: Visual grid for note input.
- `Toolbar.jsx`: Playback and export controls.
- `ResourceLibrary.jsx`: Displays the list of external resources.
- `ResourceList.jsx`: Renders individual resource items. Props: `resources` (array).
- `ResourceItem.jsx`: Displays a single resource link. Props: `resource` (object).
- `Profile.jsx`: Displays user progress and saved items.
- `ProgressBar.jsx`: Visual indicator for module completion percentage.
DATA MODEL:
- **Modules:** `[{ id: 'mod1', title: 'Intro to Synthesis', description: 'Learn the basics of sound synthesis.', lessons: [{ id: 'les1-1', title: 'Oscillators', content: '...', videoUrl: '...', quiz: {...} }, ...] }]`
- **Synth Presets:** `[{ id: 'preset1', name: 'My Lead Sound', settings: { oscillator: { type: 'sine' }, envelope: { attack: 0.1, ... }, filter: {...} } }]` (Stored in localStorage)
- **Midi Sequence:** `[{ note: 'C4', time: 0, duration: 1, velocity: 0.8 }, ...]` (Stored in localStorage or managed within MidiEditor state)
- **Completed Lessons:** `{'mod1-les1-1': true, 'mod1-les1-2': true, ...}` (Stored in localStorage)
ANIMATIONS & INTERACTIONS:
- **Hover Effects:** Subtle background color changes or slight scaling on buttons and interactive elements.
- **Page Transitions:** Fade-in/fade-out animations between sections using `Framer Motion` or simple CSS transitions.
- **Loading States:** Spinners or skeleton loaders when fetching module data or initializing tools. Visual feedback when synth notes are played.
- **Micro-interactions:** Smooth transitions for slider changes, visual feedback when a lesson is marked complete.
- **Synthesizer Keys:** Visual press effect on keyboard keys (both on-screen and physical when mapped).
EDGE CASES:
- **Empty States:** Display user-friendly messages when module lists, resources, or saved items are empty (e.g., 'No modules available yet.', 'Your saved presets will appear here.').
- **Error Handling:** Gracefully handle errors during Web Audio API initialization or MIDI file operations. Display informative error messages to the user.
- **Validation:** Basic validation for any user inputs (e.g., preset names). Ensure audio context is available before initializing synthesizer.
- **Accessibility (a11y):** Use semantic HTML5 elements. Ensure proper ARIA attributes for interactive controls. Keyboard navigability for all features. Sufficient color contrast.
- **Browser Compatibility:** Test Web Audio API and other features across modern browsers. Provide fallback messages for unsupported browsers.
SAMPLE DATA:
1. **Module Data Example:**
```json
{
"id": "mod1",
"title": "Introduction to Computer Music",
"description": "Learn the foundational concepts of creating music with computers.",
"lessons": [
{
"id": "mod1-les1",
"title": "What is Digital Audio?",
"content": "Digital audio represents sound using discrete numerical values...",
"videoUrl": "https://example.com/video1",
"quiz": null // or quiz object
},
{
"id": "mod1-les2",
"title": "Understanding MIDI",
"content": "MIDI (Musical Instrument Digital Interface) is a protocol...",
"videoUrl": "https://example.com/video2",
"quiz": null
}
]
}
```
2. **Resource Data Example:**
```json
[
{
"id": "res1",
"title": "Introduction to Computer Music (2009 PDF)",
"url": "https://composerprogrammer.com/introductiontocomputermusic.pdf",
"description": "The original PDF linked on Hacker News."
},
{
"id": "res2",
"title": "Digital Audio Fundamentals",
"url": "https://www.recordingblogs.com/digital-audio-basics/",
"description": "An article explaining the basics of digital audio theory."
}
]
```
3. **Synth Preset Example (localStorage format):**
```json
{
"id": "preset_basic_saw",
"name": "Basic Saw Wave",
"settings": {
"oscillator": {"type": "sawtooth"},
"envelope": {"attack": 0.05, "decay": 0.3, "sustain": 0.7, "release": 0.5},
"filter": {"cutoff": 5000, "resonance": 2}
}
}
```
4. **MIDI Sequence Example (for playback/export):**
```json
[
{"note": "C4", "time": 0, "duration": 0.5, "velocity": 0.9},
{"note": "E4", "time": 0.5, "duration": 0.5, "velocity": 0.8},
{"note": "G4", "time": 1.0, "duration": 1.0, "velocity": 0.7}
]
```
5. **Progress Tracking Example (localStorage format):**
```json
{
"mod1-les1": true,
"mod1-les2": true
}
```
DEPLOYMENT NOTES:
- **Build Tool:** Vite is recommended for its speed. `npm run build` or `yarn build`.
- **Environment Variables:** Use `.env` files for configuration if needed (e.g., API keys if external services are integrated later). `VITE_API_URL` etc.
- **Performance Optimizations:** Code splitting using React lazy loading for components that are not immediately needed. Optimize image/asset loading. Bundle analysis to identify large dependencies.
- **Hosting:** Static hosting platforms like Vercel, Netlify, or GitHub Pages are suitable for SPAs. Ensure correct routing configuration for deep linking (e.g., `_redirects` or `netlify.toml`).
- **HTTPS:** Always use HTTPS for security and to allow access to certain Web Audio API features.