ag-beats/requirements.md

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.