# AG Beats - Requirements Specification

AG Beats is a web-based, collaborative drum machine and bass sequencer that allowing multiple users to compose music together in real-time.

## 1. Functional Requirements

### 1.1 Step Sequencer
- **Instruments**: Support for 5 drum tracks (Kick, Snare, Hi-Hat, Open Hat, Ride).
- **Step Configuration**:
  - Adjustable sequence length from 4 to 64 steps (increments of 4).
  - Default length: 16 steps.
- **Grid Interaction**:
  - Toggle notes on/off for each instrument per step.
  - Support for "drag-to-toggle" to quickly fill or clear steps in a row.
- **Bass Line**:
  - 2-octave bass sequencer (C2 to B3).
  - Selectable notes per step (supports polyphony).
  - Visual distinction between natural and sharp notes.

### 1.2 Audio Engine
- **Synthesis**: Real-time sound generation using the Web Audio API.
  - Integrated synthesizers for Kick, Snare, and Hi-Hats.
  - Sine-wave based bass synthesizer.
- **Sample Support**: Capability to load and play audio samples for instruments.
- **Playback Controls**:
  - Global Play/Stop functionality.
  - Tempo (BPM) control range: 40 to 240 BPM (Default: 76 BPM).
  - Real-time step highlighting during playback.
- **Mixer**:
  - Individual "Mute" toggle for each drum track.
  - Master volume control for the Drum section.
  - Master volume control for the Bass section.
- **Interactive Preview**: Trigger individual drum sounds or bass notes by clicking their respective labels (outside of playback).

### 1.3 Real-time Collaboration
- **Presence**:
  - Real-time visibility of other connected users' cursors with unique colors.
  - Synchronization of connected user list.
- **State Synchronization**:
  - Instant broadcasting of all grid changes (drums and bass).
  - Synchronization of playback state (start/stop), tempo, steps, mutes, and volumes.
  - Shared "Clear" and "Import" actions across the session.
- **Stability**: Support for "Synchronizing" state when a new user joins an existing session.

### 1.4 Session & Data Management
- **Named Sessions**: Support for multiple concurrent sessions identified by a `sessionId` URL parameter.
- **Session Sharing**: One-click functionality to copy the current session URL to the clipboard.
- **Persistence**: Session state is maintained in-memory on the server for the duration of the session.
- **Import/Export**:
  - Export current pattern as a `.json` file.
  - Import patterns from previously exported `.json` files.

## 2. Technical Stack
- **Frontend**: React 19, TypeScript, Tailwind CSS (via CDN).
- **Backend**: Node.js with Express and WebSocket (`ws`).
- **Communication**: WebSockets for real-time state synchronization and cursor presence.
- **Audio**: Web Audio API for low-latency synthesis and playback.

## 3. User Interface & Experience
- **Responsive Design**: Mobile-friendly layout with horizontal scrolling for large sequences.
- **Modern Aesthetics**: Sleek, slate-based color palette with vibrant accents (Orange for drums, Purple for bass).
- **Interactive Feedback**:
  - Hover effects on sequencer cells.
  - Confirmation modals for destructive actions (e.g., Clear Pattern).
  - Scroll-wheel support for tempo adjustment.
  - Sticky labels for easy navigation in large grids.

## 4. Constraints & Limits
- **Tempo Range**: 40 - 240 BPM.
- **Sequence Steps**: 4 - 64 steps (must be multiple of 4).
- **Instruments**: Fixed set of 5 drum instruments.
- **Storage**: State is currently ephemeral (in-memory) and lost if the server restarts or the last user leaves the session.