audio-ui/PLAN.md

Audio Editor Implementation Plan

Progress Overview

Current Status: Phase 14 Complete (Settings & Preferences: Global settings with localStorage persistence) - Ready for Phase 15

Completed Phases

• ✅ Phase 1: Project Setup & Core Infrastructure (95% complete)
• ✅ Phase 2: Audio Engine Foundation (90% complete)
• ✅ Phase 3: Waveform Visualization (95% complete)
• ✅ Phase 4: Selection & Editing (70% complete - core editing features done)
• ✅ Phase 5: Undo/Redo System (100% complete)
• ✅ UI Redesign: Professional Audacity-style layout (100% complete)

Working Features

Core Features:

• ✅ Audio file upload with drag-and-drop
• ✅ Waveform visualization with real-time progress
• ✅ Playback controls (play, pause, stop, seek)
• ✅ Volume control with mute
• ✅ Timeline scrubbing (click-to-play, drag-to-scrub)
• ✅ Horizontal zoom (1x-20x)
• ✅ Vertical amplitude zoom
• ✅ Scroll through zoomed waveform
• ✅ Grid lines every second
• ✅ Viewport culling for performance
• ✅ Dark/light theme support
• ✅ Toast notifications
• ✅ File metadata display

Editing Features:

• ✅ Region selection with Shift+drag
• ✅ Visual selection feedback
• ✅ Cut/Copy/Paste operations
• ✅ Delete and Trim operations
• ✅ Keyboard shortcuts (Ctrl+A/X/C/V, Delete, Escape)
• ✅ Clipboard management
• ✅ Undo/Redo system with command pattern
• ✅ History tracking (50 operations)
• ✅ Undo/Redo keyboard shortcuts (Ctrl+Z, Ctrl+Y)

Audio Effects:

• ✅ Normalize (peak amplitude)
• ✅ Fade In (linear/exponential/logarithmic curves)
• ✅ Fade Out (linear/exponential/logarithmic curves)
• ✅ Reverse audio
• ✅ Low-Pass Filter (removes high frequencies)
• ✅ High-Pass Filter (removes low frequencies)
• ✅ Band-Pass Filter (isolates frequency range)
• ✅ Compressor (with visual transfer curve and presets)
• ✅ Limiter (brick-wall limiting with makeup gain)
• ✅ Gate/Expander (noise reduction and dynamics expansion)
• ✅ Delay/Echo (time, feedback, mix with visual pattern)
• ✅ Reverb (Schroeder algorithm with room size and damping)
• ✅ Chorus (LFO modulation with depth, rate controls)
• ✅ Flanger (short modulated delay with feedback)
• ✅ Phaser (allpass filters with LFO modulation)
• ✅ Pitch Shifter (semitones and cents adjustment)
• ✅ Time Stretch (change duration with/without pitch preservation)
• ✅ Distortion (soft/hard/tube overdrive with tone control)
• ✅ Bitcrusher (bit depth and sample rate reduction)
• ✅ All effects support undo/redo
• ✅ Effects accessible via command palette and side panel
• ✅ Parameterized effects with real-time visual feedback

Effect Chain Management:

• ✅ Effect rack with drag-and-drop reordering
• ✅ Enable/disable individual effects (bypass)
• ✅ Save and load effect chain presets
• ✅ Import/export presets as JSON files
• ✅ Chain tab in side panel
• ✅ localStorage persistence for chains and presets
• ✅ Visual effect rack with status indicators

Professional UI:

• ✅ Command Palette (Ctrl+K) with searchable actions
• ✅ Compact header (Logo + Command Palette + Theme Toggle)
• ✅ Collapsible side panel with tabs (File, Chain, Effects, History, Info)
• ✅ Full-screen waveform canvas layout
• ✅ Integrated playback controls at bottom
• ✅ Keyboard-driven workflow

Multi-Track Features (Phase 7 - Complete):

• ✅ Track creation and removal
• ✅ Track naming with inline editing
• ✅ Track colors (9 preset colors)
• ✅ Solo/Mute per track with visual feedback
• ✅ Volume fader per track (0-100%)
• ✅ Pan control per track (L-C-R)
• ✅ Track collapse/expand
• ✅ Waveform visualization per track
• ✅ Real-time multi-track audio mixing
• ✅ Synchronized playback across all tracks
• ✅ Per-track gain and pan during playback
• ✅ Solo/Mute handling during playback
• ✅ Per-track effect chains with device rack
• ✅ Collapsible effects section below each track (192px height)
• ✅ Effect browser with categorized effects
• ✅ Horizontal scrolling device rack (Ableton-style)
• ✅ Individual effect cards with side-folding design (40px collapsed, 384px+ expanded)
• ✅ Real-time parameter controls for all effects (filters, dynamics, time-based, advanced)
• ✅ Inline parameter editing with sliders and controls (multi-column grid layout)
• ✅ Real-time effect processing during playback with Web Audio API nodes
• ✅ Effect bypass functionality (disable/enable effects in real-time)
• ✅ Supported real-time effects: All filters, compressor, limiter, gate, delay
• 🔲 Advanced real-time effects: Reverb, chorus, flanger, phaser, distortion (TODO: Complex node graphs)
• 🔲 Master channel effects (TODO: Implement master effect chain UI similar to per-track effects)

Recording Features (Phase 8 - Complete):

• ✅ Microphone permission request
• ✅ Audio input device selection
• ✅ Input level meter with professional dB scale
• ✅ Real-time input monitoring
• ✅ Per-track record arming
• ✅ Global record button
• ✅ Recording indicator with pulse animation
• ✅ Punch-in/Punch-out controls (time-based recording region)
• ✅ Overdub mode (layer recordings by mixing audio)
• ✅ Input gain control (0.0-2.0 with dB display, adjustable in real-time)
• ✅ Mono/Stereo recording selection
• ✅ Sample rate matching (44.1kHz, 48kHz, 96kHz)
• ✅ Recording settings panel shown when track is armed

Analysis Tools (Phase 10 - Complete):

• ✅ Frequency Analyzer with real-time FFT display
• ✅ Spectrogram with time-frequency waterfall visualization
• ✅ Phase Correlation Meter (stereo phase analysis)
• ✅ LUFS Loudness Meter (momentary/short-term/integrated)
• ✅ Audio Statistics Panel (project info and levels)
• ✅ Color-coded heat map (blue → cyan → green → yellow → red)
• ✅ Toggle between 5 analyzer views (FFT/SPEC/PHS/LUFS/INFO)
• ✅ Theme-aware backgrounds (light/dark mode support)
• ✅ Peak and RMS meters (master and per-track)
• ✅ Clip indicator with reset (master only)

Export Features (Phase 11.1, 11.2 & 11.3 - Complete):

• ✅ WAV export (16/24/32-bit PCM or float)
• ✅ MP3 export with lamejs (128/192/256/320 kbps)
• ✅ FLAC export with fflate compression (quality 0-9)
• ✅ Format selector dropdown with dynamic options
• ✅ Normalization option (1% headroom)
• ✅ Export scope selector:
  • Entire Project (mix all tracks)
  • Selected Region (extract and mix selection)
  • Individual Tracks (separate files with sanitized names)
• ✅ Export dialog with format-specific settings
• ✅ Dynamic file extension display
• ✅ Smart selection detection (disable option when no selection)

Settings & Preferences (Phase 14 - Complete):

• ✅ Global settings dialog with 5 tabs (Recording, Audio, Editor, Interface, Performance)
• ✅ localStorage persistence with default merging
• ✅ Audio settings: buffer size, sample rate (applied to recording), auto-normalize
• ✅ UI settings: theme, font size, default track height (applied to new tracks)
• ✅ Editor settings: auto-save interval, undo limit, snap-to-grid, grid resolution, default zoom (applied)
• ✅ Performance settings: peak quality, waveform quality, spectrogram toggle (applied), max file size
• ✅ Category-specific reset buttons
• ✅ Real-time application to editor behavior

Next Steps

• Phase 6: Audio effects ✅ COMPLETE (Basic + Filters + Dynamics + Time-Based + Advanced + Chain Management)
• Phase 7: Multi-track editing ✅ COMPLETE (Multi-track playback, effects, selection/editing)
• Phase 8: Recording functionality ✅ COMPLETE (Audio input, controls, settings with overdub/punch)
• Phase 9: Automation ✅ COMPLETE (Volume/Pan automation with write/touch/latch modes)
• Phase 10: Analysis Tools ✅ COMPLETE (FFT, Spectrogram, Phase Correlation, LUFS, Audio Statistics)
• Phase 11: Export & Import ✅ COMPLETE (Full export/import with all formats, settings, scope options & conversions)
• Phase 12: Project Management ✅ COMPLETE (IndexedDB storage, auto-save, project export/import)
• Phase 13: Keyboard Shortcuts ✅ COMPLETE (Full suite of shortcuts for navigation, editing, and view control)
• Phase 14: Settings & Preferences ✅ COMPLETE (Global settings with localStorage persistence and live application)

---

Overview

A sophisticated browser-only audio editor built with Next.js 16, React 19, and Tailwind CSS 4. This project aims to provide all AudioMass features plus advanced capabilities like multi-track editing, advanced effects, automation, and more.

Project Goals

• 100% Client-Side: All processing happens in the browser using Web Audio API
• Modern Stack: Next.js 16 with React 19, TypeScript 5, Tailwind CSS 4
• Professional Features: Multi-track editing, advanced effects, automation lanes
• Privacy-First: No server uploads, all data stays local
• Export Ready: Static site generation for easy deployment

Technology Stack

Core Framework

• Next.js 16 - React framework with Turbopack
• React 19 - Latest React with concurrent features
• TypeScript 5 - Type safety and better DX
• Tailwind CSS 4 - Utility-first CSS with OKLCH colors

Audio Technologies

• Web Audio API - Native browser audio processing
• MediaRecorder API - Audio recording from microphone
• Canvas API - Waveform visualization
• WebGL (Optional) - High-performance rendering
• AudioWorklets - Custom low-latency audio processing

Libraries & Dependencies

• lamejs - MP3 encoding (Web Audio doesn't support MP3 export)
• fflate - FLAC encoding for lossless export
• idb - IndexedDB wrapper for project storage
• lucide-react - Modern icon library
• clsx + tailwind-merge - Conditional class names
• zustand or jotai (Optional) - Lightweight state management

Storage & Persistence

• IndexedDB - Project files and audio buffers
• LocalStorage - User settings and preferences
• File System Access API (Optional) - Direct file system access

Project Structure

audio-ui/
├── app/
│   ├── layout.tsx              # Root layout with theme support
│   ├── page.tsx                # Main editor page
│   └── globals.css             # Tailwind + custom styles
├── components/
│   ├── ui/                     # Reusable UI components
│   │   ├── Button.tsx
│   │   ├── Card.tsx
│   │   ├── Slider.tsx
│   │   ├── Select.tsx
│   │   ├── Input.tsx
│   │   ├── Progress.tsx
│   │   ├── Toast.tsx
│   │   ├── Modal.tsx
│   │   ├── Tabs.tsx
│   │   └── Tooltip.tsx
│   ├── editor/                 # Audio editor components
│   │   ├── AudioEditor.tsx     # Main editor container
│   │   ├── Timeline.tsx        # Timeline ruler
│   │   ├── Waveform.tsx        # Waveform display
│   │   ├── WaveformCanvas.tsx  # Canvas renderer
│   │   ├── PlaybackControls.tsx
│   │   ├── TransportBar.tsx
│   │   ├── RegionManager.tsx
│   │   ├── MarkerList.tsx
│   │   └── SelectionInfo.tsx
│   ├── tracks/                 # Multi-track components
│   │   ├── TrackList.tsx
│   │   ├── Track.tsx
│   │   ├── TrackHeader.tsx
│   │   ├── TrackControls.tsx
│   │   ├── Mixer.tsx
│   │   └── MixerChannel.tsx
│   ├── effects/                # Audio effects UI
│   │   ├── EffectRack.tsx
│   │   ├── EffectSlot.tsx
│   │   ├── EQEffect.tsx
│   │   ├── CompressorEffect.tsx
│   │   ├── ReverbEffect.tsx
│   │   ├── DelayEffect.tsx
│   │   └── EffectPresets.tsx
│   ├── automation/             # Automation components
│   │   ├── AutomationLane.tsx
│   │   ├── AutomationPoint.tsx
│   │   └── AutomationEditor.tsx
│   ├── analysis/               # Analysis tools
│   │   ├── FrequencyAnalyzer.tsx
│   │   ├── Spectrogram.tsx
│   │   ├── PhaseMeter.tsx
│   │   └── LoudnessMeter.tsx
│   ├── recording/              # Recording components
│   │   ├── RecordingPanel.tsx
│   │   ├── InputSelector.tsx
│   │   └── RecordingMonitor.tsx
│   ├── export/                 # Export components
│   │   ├── ExportModal.tsx
│   │   ├── FormatSelector.tsx
│   │   └── RenderSettings.tsx
│   ├── project/                # Project management
│   │   ├── ProjectManager.tsx
│   │   ├── ProjectList.tsx
│   │   └── ProjectSettings.tsx
│   └── layout/                 # Layout components
│       ├── ThemeToggle.tsx
│       ├── Toolbar.tsx
│       ├── Sidebar.tsx
│       ├── StatusBar.tsx
│       └── KeyboardShortcuts.tsx
├── lib/
│   ├── audio/                  # Web Audio API logic
│   │   ├── context.ts          # AudioContext management
│   │   ├── engine.ts           # Core audio engine
│   │   ├── player.ts           # Playback controller
│   │   ├── recorder.ts         # Audio recording
│   │   ├── decoder.ts          # Audio file decoding
│   │   ├── encoder.ts          # Audio export encoding
│   │   ├── buffer-utils.ts     # AudioBuffer utilities
│   │   ├── effects/            # Effect implementations
│   │   │   ├── equalizer.ts
│   │   │   ├── compressor.ts
│   │   │   ├── reverb.ts
│   │   │   ├── delay.ts
│   │   │   ├── chorus.ts
│   │   │   ├── phaser.ts
│   │   │   └── pitch-shift.ts
│   │   ├── analysis/           # Analysis tools
│   │   │   ├── fft.ts
│   │   │   ├── spectrogram.ts
│   │   │   └── loudness.ts
│   │   └── worklets/           # AudioWorklet processors
│   │       └── custom-processor.ts
│   ├── storage/                # Data persistence
│   │   ├── db.ts               # IndexedDB setup
│   │   ├── projects.ts         # Project storage
│   │   ├── audio-cache.ts      # Audio buffer cache
│   │   └── settings.ts         # User settings
│   ├── history/                # Undo/redo system
│   │   ├── command.ts          # Command interface
│   │   ├── history-manager.ts  # History stack
│   │   └── commands/           # Edit commands
│   │       ├── cut.ts
│   │       ├── paste.ts
│   │       ├── delete.ts
│   │       └── effect.ts
│   ├── waveform/               # Waveform processing
│   │   ├── peaks.ts            # Waveform peak generation
│   │   ├── renderer.ts         # Canvas rendering
│   │   └── zoom.ts             # Zoom calculations
│   ├── utils/                  # Utility functions
│   │   ├── time.ts             # Time format conversion
│   │   ├── math.ts             # Math utilities
│   │   ├── color.ts            # Color utilities
│   │   └── file.ts             # File handling
│   └── hooks/                  # Custom React hooks
│       ├── useAudioContext.ts
│       ├── useAudioPlayer.ts
│       ├── useWaveform.ts
│       ├── useRecording.ts
│       ├── useKeyboardShortcuts.ts
│       ├── useHistory.ts
│       └── useProject.ts
├── types/
│   ├── audio.ts                # Audio type definitions
│   ├── editor.ts               # Editor state types
│   ├── effects.ts              # Effect types
│   └── project.ts              # Project types
├── public/
│   └── impulse-responses/      # Reverb IR files
├── package.json
├── postcss.config.js           # PostCSS configuration
├── next.config.ts
├── tsconfig.json
├── Dockerfile                  # Docker deployment
├── docker-compose.yml          # Docker compose config
├── nginx.conf                  # Nginx configuration
└── PLAN.md                     # This file

Implementation Phases

Phase 1: Project Setup & Core Infrastructure

1.1 Initialize Project

• Create Next.js 16 project with TypeScript
• Install and configure Tailwind CSS 4
• Set up project structure
• Configure static export mode
• Set up Turbopack

1.2 Core UI Components

• Button component with variants
• Card component
• Slider component (critical for audio controls)
• Select dropdown
• Input fields
• Progress bars
• Toast notifications
• Modal dialogs
• Tabs component
• Tooltip component

1.3 Theme System

• CSS variables setup (OKLCH colors)
• Dark/Light mode toggle
• Theme persistence (LocalStorage)
• Color palette for waveforms
• Custom animations

1.4 Basic Layout

• Header with app title
• Toolbar with primary actions
• Main editor area
• Sidebar for tools/effects
• Status bar with info
• Footer

Phase 2: Audio Engine Foundation

2.1 Web Audio API Setup

• AudioContext initialization
• Audio context state management
• Sample rate detection
• Buffer size configuration
• Audio device enumeration

2.2 Audio File Handling

• File upload component
• Drag-and-drop support
• Audio file decoding (MP3, WAV, OGG, FLAC, etc.)
• Format detection
• Error handling for unsupported formats

2.3 Audio Buffer Management

• AudioBuffer creation and storage
• Multi-channel support (mono, stereo, surround)
• Buffer slicing and concatenation
• Memory management for large files

2.4 Basic Playback

• Play/Pause/Stop controls
• Playback position tracking
• Loop functionality
• Playback speed control
• Real-time position display

Phase 3: Waveform Visualization

3.1 Waveform Rendering

• Canvas-based waveform renderer
• Peak calculation from AudioBuffer
• Multi-resolution peaks (for zooming)
• Stereo waveform display
• Color customization

3.2 Waveform Interaction

• Click to set playhead position
• Drag to scrub audio
• Horizontal scrolling
• Zoom in/out (horizontal)
• Vertical zoom (amplitude)

3.3 Timeline & Ruler

• Time ruler with markers (basic timeline slider)
• Time format switching (samples/seconds/minutes)
• Grid lines with snap-to-grid
• Measure/beat markers (optional)

3.4 Performance Optimization

• OffscreenCanvas for background rendering
• Debounced rendering during zoom/scroll
• Viewport culling (render only visible region)
• Web Worker for peak calculation

Phase 4: Selection & Editing (70% Complete)

✅ Accomplished:

• Region selection with Shift+drag on waveform
• Visual selection feedback (blue overlay with borders)
• Full keyboard shortcuts (Ctrl+A, Ctrl+X/C/V, Delete, Escape)
• Core edit operations (Cut, Copy, Paste, Delete, Trim)
• Internal clipboard management with ClipboardData
• AudioBuffer manipulation utilities (extract, delete, insert, trim, concatenate)
• EditControls UI component with selection info display

📋 Future Features (Optional/Advanced):

• Keyboard-based selection with Shift+Arrow keys
• Named and color-coded region markers
• Region list panel with marker management
• Loop region functionality
• Split at cursor
• Duplicate selection
• Multiple clipboard slots
• Clipboard preview

4.1 Region Selection

• Click-and-drag selection (Shift+drag)
• Keyboard-based selection (Shift+Arrow) - FUTURE
• Select all (Ctrl+A)
• Clear selection (Escape)
• Selection visual feedback

4.2 Region Markers - FUTURE

• Add/Remove region markers
• Named regions
• Color-coded regions
• Region list panel
• Loop region

4.3 Basic Edit Operations

• Cut (Ctrl+X)
• Copy (Ctrl+C)
• Paste (Ctrl+V)
• Delete (Delete key)
• Trim to selection
• Split at cursor - FUTURE
• Duplicate selection - FUTURE

4.4 Clipboard Management

• Internal clipboard for audio data
• Multiple clipboard slots (optional) - FUTURE
• Clipboard preview - FUTURE

Phase 5: Undo/Redo System (100% Complete)

✅ Accomplished:

• Command pattern with interface and base classes
• HistoryManager with 50-operation stack
• EditCommand for cut, delete, paste, and trim operations
• Full keyboard shortcuts (Ctrl+Z undo, Ctrl+Y/Ctrl+Shift+Z redo)
• HistoryControls UI component with visual state display
• Toast notifications for undo/redo actions
• History state tracking (canUndo, canRedo, descriptions)
• useHistory React hook for state management
• Integration with all edit operations
• Clear history functionality

📋 Future Features (Advanced):

• EffectCommand for audio effects (Phase 6)
• VolumeCommand for gain changes (Phase 6)
• SplitCommand for region splitting (Phase 4 future)
• Configurable history limit in settings
• History panel with full operation list

5.1 Command Pattern

• Command interface
• Execute/Undo/Redo methods
• Command factory (createCutCommand, createDeleteCommand, etc.)

5.2 History Manager

• History stack (50 operations)
• Undo (Ctrl+Z)
• Redo (Ctrl+Y or Ctrl+Shift+Z)
• Clear history
• History limit configuration

5.3 Specific Commands

• EditCommand (cut/paste/delete/trim)
• EffectCommand (apply effects) - PHASE 6
• VolumeCommand (gain changes) - PHASE 6
• SplitCommand (split regions) - FUTURE

Phase 6: Audio Effects

6.1 Basic Effects (✅ Complete)

• Gain/Volume adjustment
• Pan (stereo positioning) - FUTURE
• Fade In/Fade Out (linear/exponential/logarithmic)
• Normalize (peak/RMS)
• Reverse
• Silence generator - FUTURE
• EffectCommand for undo/redo integration
• Effects added to command palette
• Toast notifications for effects

6.2 Filters & EQ (Partially Complete)

• Parametric EQ (3-band, 10-band, 31-band) - FUTURE
• Low-pass filter (1000Hz cutoff, configurable)
• High-pass filter (100Hz cutoff, configurable)
• Band-pass filter (1000Hz center, configurable)
• Notch filter (implemented in filters.ts)
• Shelf filters (low/high) (implemented in filters.ts)
• Peaking EQ filter (implemented in filters.ts)
• Visual EQ curve editor - FUTURE
• Filters integrated with undo/redo system
• Filters added to command palette

6.3 Dynamics Processing (✅ Complete)

• Compressor (threshold, ratio, attack, release, knee, makeup gain)
• Limiter (threshold, attack, release, makeup gain)
• Gate/Expander (threshold, ratio, attack, release, knee)
• Visual transfer curve showing input/output relationship
• Professional presets for each effect type
• Real-time parameter visualization
• EffectCommand integration for undo/redo
• Effects added to command palette and side panel
• Selection-based processing support
• Visual gain reduction meter (realtime metering - FUTURE)

6.4 Time-Based Effects ✓

• Delay/Echo (time, feedback, mix)
• Reverb (Schroeder algorithmic reverb with room size and damping)
• Chorus (depth, rate, delay with LFO modulation)
• Flanger (short modulated delay with feedback)
• Phaser (cascaded allpass filters with LFO)
• TimeBasedParameterDialog component with visual feedback
• Integration with command palette and side panel
• 4 presets per effect type
• Undo/redo support for all time-based effects

6.5 Advanced Effects ✓

• Pitch shifter (semitones, cents with linear interpolation)
• Time stretcher (with and without pitch preservation using overlap-add)
• Distortion/Overdrive (soft/hard/tube types with tone and output control)
• Bitcrusher (bit depth and sample rate reduction)
• AdvancedParameterDialog component with visual waveform feedback
• Integration with command palette and side panel
• 4 presets per effect type
• Undo/redo support for all advanced effects

6.6 Effect Management ✓

• Effect rack/chain (EffectRack component with drag-and-drop)
• Effect presets (save/load/import/export presets)
• Effect bypass toggle (enable/disable individual effects)
• Effect chain state management (useEffectChain hook)
• Effect reordering (drag-and-drop within chain)
• Chain tab in SidePanel with preset manager
• localStorage persistence for chains and presets
• Wet/Dry mix control (per-effect) - FUTURE
• Real-time effect preview - FUTURE

Phase 7: Multi-Track Support (In Progress - Core Features Complete)

7.1 Track Management ✓

• Add/Remove tracks
• Track reordering (drag-and-drop) - UI ready
• Track naming (inline editing)
• Track colors (9 preset colors)
• Track groups/folders (optional) - FUTURE

7.2 Track Controls ✓

• Solo/Mute per track
• Volume fader per track (0-100%)
• Pan control per track (L-C-R)
• Record enable per track (UI ready)
• Track height adjustment (60-300px)
• Track collapse/expand

7.3 Multi-Track Playback ✓

• Real-time multi-track audio mixing
• Synchronized playback across tracks
• Per-track gain and pan control
• Solo/Mute handling during playback
• Master volume - FUTURE
• Master output meter - FUTURE
• Track routing - FUTURE
• Send/Return effects - FUTURE
• Sidechain support (advanced) - FUTURE

7.4 Track Effects (Complete)

• Per-track effect chain
• Effect rack UI
• Effect bypass per track
• Real-time effect processing during playback
• Add/remove effects during playback
• Real-time parameter updates
• Effect chain persistence (localStorage)

Phase 8: Recording

8.1 Audio Input ✓

• Microphone permission request
• Audio input device selection
• Input level meter
• Input monitoring (real-time level display)

8.2 Recording Controls ✓

• Arm recording (per-track record enable)
• Start/Stop recording (global record button)
• Recording indicator (visual feedback with pulse animation)
• Punch-in/Punch-out recording (UI controls with time inputs)
• Overdub mode (mix recorded audio with existing audio)

8.3 Recording Settings ✓

• Sample rate matching (44.1kHz, 48kHz, 96kHz)
• Input gain control (0.0-2.0 with dB display)
• Mono/Stereo recording selection
• Real-time gain adjustment during recording
• 🔲 File naming conventions (Future: Auto-name recorded tracks)

Phase 9: Automation

9.1 Automation Lanes

• Show/Hide automation lanes per track
• Automation lane for volume
• Automation lane for pan
• Automation lanes for effect parameters
• Single automation lane with parameter dropdown selector
• Automation controls in left sidebar (matching track controls)
• Perfect alignment with waveform width

9.2 Automation Points

• Add/Remove automation points
• Drag automation points
• Automation curves (linear/step support)
• Select automation points
• Delete with keyboard (Delete/Backspace)
• Copy/Paste automation
• Bezier curves

9.3 Automation Playback & Recording

• Real-time automation during playback
• Automation for volume and pan
• Automation for effect parameters
• Continuous evaluation via requestAnimationFrame
• Proper parameter range conversion
• Automation recording (write mode) - Volume, Pan, Effect Parameters
• Automation editing modes UI (read/write/touch/latch)
• Automation modes recording implementation (write/touch/latch)
• Touch/latch mode tracking with control interaction
• Throttled automation point creation (every ~100ms)
• Parameter touch callbacks for volume and pan controls
• Parameter touch callbacks for effect parameter sliders
• Touch/latch modes for effect parameters (frequency, Q, gain, etc.)
• Proper prop passing through EffectDevice → EffectParameters → Slider

Phase 10: Analysis Tools

10.1 Frequency Analyzer

• Real-time FFT analyzer
• Frequency spectrum display
• Peak/Average display modes
• Logarithmic/Linear frequency scale

10.2 Spectrogram

• Time-frequency spectrogram view
• Color scale customization (heat map: black/gray → blue → cyan → green → yellow → red)
• FFT size configuration (uses analyserNode.frequencyBinCount)
• Overlay on waveform (optional)

10.3 Metering

• Peak meter (master and per-track)
• RMS meter (master and per-track)
• Phase correlation meter
• Loudness meter (LUFS with momentary/short-term/integrated)
• Clip indicator (master only)

10.4 Audio Statistics

• File duration
• Sample rate, bit depth, channels
• Peak amplitude
• RMS level
• Dynamic range
• Headroom calculation

Phase 11: Export & Import (Phase 11.1, 11.2, 11.3 Complete)

11.1 Export Formats ✅ COMPLETE

• WAV export (PCM, various bit depths: 16/24/32-bit)
• Export dialog with settings UI
• Export button in header
• Mix all tracks before export
• MP3 export (using lamejs with dynamic import)
• FLAC export (using fflate DEFLATE compression)
• OGG Vorbis export (skipped - no good browser encoder available)

Technical Implementation:

• MP3 encoding with lamejs: 1152 sample block size, configurable bitrate
• FLAC compression with fflate: DEFLATE-based lossless compression
• TypeScript declarations for lamejs module
• Async/await for dynamic imports to reduce bundle size
• Format-specific UI controls in ExportDialog

11.2 Export Settings ✅ COMPLETE

• Bit depth selection (16/24/32-bit) for WAV and FLAC
• Normalization before export (with 1% headroom)
• Filename customization with dynamic extension display
• Quality/bitrate settings:
  • MP3: Bitrate selector (128/192/256/320 kbps)
  • FLAC: Compression quality slider (0-9, fast to small)
• Format selector dropdown (WAV/MP3/FLAC)
• Sample rate conversion
• Dithering options

11.3 Export Regions ✅ COMPLETE

• Export entire project (mix all tracks)
• Export selected region (extract and mix selection from all tracks)
• Export individual tracks (separate files with sanitized names)
• Batch export all regions (future feature)

11.4 Import ✅ COMPLETE

• Support for WAV, MP3, OGG, FLAC, M4A, AIFF
• Sample rate conversion on import
• Stereo to mono conversion
• File metadata reading (codec detection, duration, channels, sample rate)
• ImportOptions interface for flexible import configuration
• importAudioFile() function returning buffer + metadata
• Normalize on import option
• Import settings dialog component (ready for integration)

Phase 12: Project Management ✅

12.1 Save/Load Projects ✅

• Save project to IndexedDB
• Load project from IndexedDB
• Project list UI (Projects dialog)
• Auto-save functionality (3-second debounce)
• Manual save with Ctrl+S
• Auto-load last project on startup
• Editable project name in header
• Delete and duplicate projects

12.2 Project Structure ✅

• IndexedDB storage with serialization
• Track information (name, color, volume, pan, mute, solo)
• Audio buffer serialization (Float32Array per channel)
• Effect settings (serialized effect chains)
• Automation data (deep cloned to remove functions)
• Project metadata (name, description, duration, track count)

12.3 Project Export/Import ✅

• Export project as JSON (with audio data embedded)
• Import project from JSON
• Export button per project in Projects dialog
• Import button in Projects dialog header
• Auto-generate new IDs on import to avoid conflicts
• Project templates (future enhancement)

12.4 Project Settings ✅

• Sample rate (stored per project)
• Zoom level (persisted)
• Current time (persisted)
• Project name/description
• Created/updated timestamps

Phase 13: Keyboard Shortcuts ✅

13.1 Playback Shortcuts ✅

• Spacebar - Play/Pause
• Home - Go to start
• End - Go to end
• Left/Right Arrow - Seek ±1 second
• Ctrl+Left/Right - Seek ±5 seconds

13.2 Editing Shortcuts ✅

• Ctrl+Z - Undo
• Ctrl+Y / Ctrl+Shift+Z - Redo
• Ctrl+X - Cut
• Ctrl+C - Copy
• Ctrl+V - Paste
• Ctrl+S - Save project
• Ctrl+D - Duplicate selection
• Delete/Backspace - Delete selection
• Ctrl+A - Select All (on current track)
• Escape - Clear selection

13.3 View Shortcuts ✅

• Ctrl+Plus/Equals - Zoom in
• Ctrl+Minus - Zoom out
• Ctrl+0 - Fit to window
• F - Toggle fullscreen (browser native)

13.4 Custom Shortcuts

• Keyboard shortcuts manager (future enhancement)
• User-configurable shortcuts (future enhancement)
• Shortcut conflict detection (future enhancement)

Phase 14: Settings & Preferences ✅ COMPLETE

✅ Accomplished:

• Global settings system with localStorage persistence
• Settings dialog with 5 tabs (Recording, Audio, Editor, Interface, Performance)
• Real-time settings application to editor behavior
• Category-specific reset buttons
• Merge with defaults on load for backward compatibility

14.1 Audio Settings ✅

• Audio output device selection (future: requires device enumeration API)
• Buffer size/latency configuration
• Sample rate preference (applied to recording)
• Auto-normalize on import

14.2 UI Settings ✅

• Theme selection (dark/light/auto)
• Font size (small/medium/large)
• Default track height (120-400px, applied to new tracks)
• Color scheme customization (future: advanced theming)

14.3 Editor Settings ✅

• Auto-save interval (0-60 seconds)
• Undo history limit (10-200 operations)
• Snap-to-grid toggle
• Grid resolution (0.1-10 seconds)
• Default zoom level (1-20x, applied to initial state)

14.4 Performance Settings ✅

• Peak calculation quality (low/medium/high)
• Waveform rendering quality (low/medium/high)
• Enable/disable spectrogram (applied to analyzer visibility)
• Maximum file size limit (100-1000 MB)

Phase 15: Polish & Optimization

15.1 Performance Optimization

• Web Worker for heavy computations
• AudioWorklet for custom processing
• Lazy loading for dialogs and analysis components (GlobalSettingsDialog, ExportDialog, ProjectsDialog, ImportTrackDialog, FrequencyAnalyzer, Spectrogram, PhaseCorrelationMeter, LUFSMeter, AudioStatistics)
• Code splitting for route optimization
• Memory leak prevention (audio-cleanup utilities, proper cleanup in useRecording, animation frame cancellation in visualizations)

15.2 Responsive Design ✅

• Mobile-friendly layout (responsive header, adaptive toolbar with icon-only buttons on small screens)
• Touch gesture support (collapse/expand controls with chevron buttons)
• Adaptive toolbar (hide less critical buttons on mobile: Export on md, Clear All on lg)
• Vertical scrolling for track list (sidebar hidden on mobile < lg breakpoint)
• Collapsible track controls (two-state mobile: collapsed with minimal controls + horizontal meter, expanded with full height fader + pan control; desktop always expanded with narrow borders)
• Collapsible master controls (collapsed view with horizontal level meter, expanded view with full controls; collapse button hidden on desktop)
• Track collapse buttons on mobile (left chevron: collapses/expands track in list, right chevron: collapses/expands track controls)
• Mobile vertical stacking layout (< lg breakpoint: controls → waveform → automation bars → effects bars per track, master controls and transport controls stacked vertically in bottom bar)
• Desktop two-column layout (≥ lg breakpoint: controls left sidebar, waveforms right panel with automation/effects bars, master controls in right sidebar, transport controls centered in bottom bar)
• Automation and effects bars on mobile (collapsible with eye/eye-off icons, horizontally scrollable, full functionality: parameter selection, mode cycling, height controls, add effects)
• Height synchronization (track controls and waveform container heights match exactly using user-configurable track.height on desktop)

15.3 Error Handling

• Graceful error messages (toast notifications for copy/paste/edit operations)
• File format error handling (UnsupportedFormatDialog with format validation and decode error catching)
• Memory limit warnings (MemoryWarningDialog with file size checks)
• Browser compatibility checks (BrowserCompatDialog with Web Audio API detection)

15.4 Documentation

• User guide
• Keyboard shortcuts reference (KeyboardShortcutsDialog with ? shortcut and command palette integration)
• Effect descriptions
• Troubleshooting guide

15.5 Testing

• Unit tests for audio utilities
• Component tests
• Integration tests
• Browser compatibility testing
• Performance benchmarking

Feature Comparison: AudioMass vs Our Editor

AudioMass Features (Baseline)

✅ Waveform editing ✅ Basic effects (EQ, filters) ✅ Recording from microphone ✅ File export (WAV) ✅ Region markers ✅ Undo/redo ✅ Cut/Copy/Paste ✅ Normalize, Fade, Reverse

Our Additional Features (Beyond AudioMass)

🚀 Multi-track editing - Work with multiple audio tracks simultaneously 🚀 Mixer with routing - Professional mixing capabilities 🚀 Advanced effects - Reverb, delay, chorus, phaser, pitch shift 🚀 Automation lanes - Automate volume, pan, and effect parameters 🚀 Spectrogram view - Time-frequency visualization 🚀 LUFS metering - Professional loudness metering 🚀 Better keyboard shortcuts - Extensive shortcuts for fast workflow 🚀 Dark mode - Modern dark theme with Tailwind CSS 4 🚀 Project save/load - Save and load complete projects 🚀 Export formats - MP3, OGG, FLAC in addition to WAV 🚀 Better UX - Modern React patterns, responsive design 🚀 Effect presets - Save and load effect settings 🚀 Track colors & organization - Visual organization 🚀 Auto-save - Never lose your work 🚀 Recording overdub - Layer recordings on top of each other

Technical Considerations

Web Audio API Limitations

• MP3 Encoding: Web Audio API doesn't support MP3 export. We'll use lamejs for encoding.
• Sample Rate: Limited to hardware sample rate (usually 44.1kHz or 48kHz).
• Latency: Recording latency depends on buffer size and browser implementation.
• Browser Support: Some features may require modern browsers (Chrome 90+, Firefox 88+, Safari 14+).

Performance Considerations

• Large Files: Files over 100MB may cause memory issues. We'll implement warnings and chunked processing.
• Waveform Rendering: Use OffscreenCanvas and Web Workers for smooth rendering.
• Real-time Effects: AudioWorklets provide lower latency than ScriptProcessorNode (deprecated).
• Mobile Performance: May need to disable some features (spectrogram) on mobile devices.

Storage Considerations

• IndexedDB Limits: Varies by browser, typically 50MB-unlimited (with user permission).
• Audio Buffer Memory: Keep track of memory usage, implement buffer pooling.
• Project Size: Large projects with many tracks may require compression.

Browser Compatibility

• Target Browsers: Chrome 90+, Firefox 88+, Safari 14+, Edge 90+
• Polyfills: May need polyfills for older browsers (File System Access API)
• Feature Detection: Use feature detection for optional features

Development Workflow

Phase Approach

1. Phase 1-3: Foundation (Setup → Audio Engine → Waveform) - 2-3 weeks
2. Phase 4-6: Core Editing (Selection → Undo/Redo → Effects) - 3-4 weeks
3. Phase 7-9: Advanced Features (Multi-track → Recording → Automation) - 4-5 weeks
4. Phase 10-12: Professional Tools (Analysis → Export → Projects) - 3-4 weeks
5. Phase 13-15: Polish (Shortcuts → Settings → Optimization) - 2-3 weeks

Total Estimated Timeline: 14-19 weeks for full implementation

Iteration Strategy

• Build MVP with Phases 1-6 first (basic single-track editor)
• Test and refine core features
• Add multi-track and advanced features incrementally
• Continuous testing and optimization

Testing Strategy

• Unit Tests: Audio utilities, time conversion, buffer operations
• Integration Tests: Playback, recording, effect chains
• Manual Testing: UI/UX, cross-browser compatibility
• Performance Testing: Large file handling, memory usage

Success Metrics

Functional Metrics

• ✅ Can load and play audio files
• ✅ Can edit audio (cut/copy/paste)
• ✅ Can apply effects
• ✅ Can record audio
• ✅ Can export in multiple formats
• ✅ Can save and load projects

Performance Metrics

• Load time < 3 seconds
• Waveform rendering at 60fps
• Playback latency < 20ms
• Support files up to 500MB

UX Metrics

• Intuitive interface (minimal learning curve)
• Responsive design (works on tablets)
• Keyboard-first workflow
• Undo/redo for all actions

Future Enhancements (Post-Launch)

Advanced Features

• MIDI support (sequence automation)
• VST plugin support (via WASM)
• Collaborative editing (WebRTC)
• Cloud storage integration
• Stem export (separate track files)

AI Features

• Noise reduction (ML-based)
• Auto-mastering
• Stem separation (vocals/instruments)
• Beat detection and tempo mapping

Integration Features

• Export to DAW project format
• Import from cloud storage
• Share projects via URL
• Embed player for web

Resources & References

Web Audio API

• MDN Web Audio API
• Web Audio API Specification
• AudioWorklet

Libraries

• lamejs - MP3 encoding
• wavesurfer.js - Waveform inspiration (we'll build custom)
• Tone.js - Alternative audio framework (reference)

Inspiration

• AudioMass - Feature baseline
• Audacity - Desktop reference
• Soundtrap - Web DAW reference

Design References

• Ableton Live - UI/UX inspiration
• FL Studio - Workflow ideas
• Logic Pro - Professional features

Conclusion

This project aims to create a professional-grade audio editor that runs entirely in the browser, combining the accessibility of web applications with the power of desktop DAWs. By leveraging modern web technologies (Web Audio API, Next.js 16, Tailwind CSS 4), we can deliver a fast, beautiful, and capable audio editing experience.

The phased approach ensures we build a solid foundation before adding advanced features, allowing for continuous testing and refinement. The result will be a tool that not only matches AudioMass but significantly exceeds it with multi-track editing, advanced effects, automation, and a modern, polished user interface.

Let's build the future of browser-based audio editing! 🎵🎧