Percussion Studio

A web-based percussion pattern sequencer for Afro-Cuban rhythms and beyond.

🎵 Live Demo: https://pich78.github.io/percussion-studio/

Overview

Percussion Studio is a browser-based application for creating, editing, and playing percussion patterns. It features a grid-based sequencer with support for multiple instruments, sound packs, and complex multi-measure compositions. It is optimized for both desktop creation and mobile playback.

Key Features

• 🥁 Multi-track sequencer with visual grid interface
• 📱 Optimized Mobile View for playback and practice
• 🎼 Multiple instruments (Batá drums, congas, and more)
• 🪘 Batá Rhythm Support with dedicated organization
• 🔊 Sound pack system for different audio samples
• 📊 Multi-measure sections with repeats and tempo control
• 🎵 Count-in with customizable settings (4/4, 6/8)
• 💾 Import/Export rhythms as YAML files
• 🎨 Modern, responsive UI with real-time playback

Getting Started

Running Locally

1. Clone the repository:

   git clone https://github.com/pich78/percussion-studio.git
   cd percussion-studio

2. Start the local web server (this will automatically regenerate the manifest, then serve the app on port 8000):

   python launch_local.py

   Add -v (or --verbose) to print every HTTP request (path and status) to the terminal — useful when debugging data loading:

   python launch_local.py --verbose

Project Structure

percussion-studio/
├── index.html              # Main application entry point
├── desktop.html            # Desktop interface
├── mobile.html             # Mobile interface
├── manifest.json           # Auto-generated resource registry
├── precache.json           # Auto-generated offline snapshot (SW version + hashes)
├── sw.js                   # Service worker: atomic offline cache/updates
├── js/                     # Application source code
│   └── vendor/             # Vendored browser deps (js-yaml, Tailwind)
├── data/                   # All content data
│   ├── instruments/        # Instrument definitions
│   ├── sounds/             # Instrument sound folders (WAV files)
│   ├── rhythms/            # Rhythm compositions
│   └── assets/             # Shared assets (icons, etc.)
└── tools/                  # Utility scripts
    ├── generate_manifest.py
    └── migrate_sounds.py

Creating Content

1. Creating a New Instrument

Instruments define the abstract capabilities of a percussion instrument type (e.g., what sounds it can make).

Location: data/instruments/{SYMBOL}.yaml

Example: data/instruments/CON.yaml (Conga)

name: "Conga"
symbol: "CON"
description: "A tall, narrow, single-headed drum from Cuba"
sounds:
  - letter: "O"
    name: "open"
    description: "Open tone"
  - letter: "S"
    name: "slap"
    description: "Slap"
  - letter: "B"
    name: "bass"
    description: "Bass"
  - letter: "D"
    name: "dedo"
    description: "Finger stroke"

Full step-by-step guide: docs/adding-instruments.md

2. Creating a Sound Pack

Sound packs are convention-driven: just drop WAV files in the instrument's sound folder following the naming pattern {SYMBOL}.{SOUND}.{PACK}.wav. No YAML needed.

Location: data/sounds/{instrument-name}/

Example: data/sounds/conga/

con.open.studio.wav
con.slap.studio.wav
con.bass.studio.wav
con.open.studio.live.wav

3. Creating a Rhythm

Rhythms define complete compositions with multiple instruments and patterns.

Location: data/rhythms/{RHYTHM_NAME}.yaml

Example: data/rhythms/basic_conga_pattern.yaml

name: "Basic Conga Pattern"
global_bpm: 120

sound_kit:
  conga_1:
    instrument: "CON"
    pack: "studio"
  
  conga_2:
    instrument: "CON"
    pack: "studio"

playback_flow:
  - name: "Main Pattern"
    repetitions: 4
    subdivision: 4      # 4 for binary (4/4), 3 for ternary (6/8)
    steps: 16
    measures:
      - pattern:
          conga_1: "||O---|S---|O---|S---|"
          conga_2: "||--B-|--B-|--B-|--B-|"
        dynamics:                              # Optional
          conga_1: "||a---|----|l---|----|"

4. Creating Batà Rhythms

Batà rhythms have a special structure and metadata system.

Location: data/rhythms/Batà/{Folder}/

Structure:

• Each rhythm family gets its own folder (e.g., Yakota, Alumbanche)
• Metadata File: A file named {Folder}_metadata.yaml defines properties for the whole group (Orishas, Classification)
• Rhythm Files: Individual .yaml files for each variation

5. Updating the Manifest

After creating or modifying any data files, regenerate the manifest:

cd tools
python generate_manifest.py

Pattern Writing Tips

Meter and Subdivision

• Binary (4/4): Use 16 steps, subdivision of 4
• Ternary (6/8): Use 12 steps, subdivision of 3
• Compound (12/8): Use 24 steps, subdivision of 3

Dynamics

Each measure can include an optional dynamics block that mirrors the pattern block. The dynamics string uses the same visual separator format and must have the same number of steps. Each character controls the volume and visual intensity of the corresponding step:

Character	Level	Volume	Visual Effect
g	Ghost	30%	Small (50%), faded
s	Soft	60%	Reduced (75%), slightly faded
-	Normal	100%	Default size and brightness
l	Loud	130%	Larger (120%), orange glow
a	Accent	160%	Largest (140%), red glow

• Dynamics are optional — if omitted, all steps default to Normal (-).
• You only need to include dynamics for tracks that have non-normal dynamics.
• A - in the dynamics string means "normal" (not silence — silence is controlled by the pattern).

Example:

measures:
  - pattern:
      conga_1: "||O---|S---|O---|S---|"
    dynamics:
      conga_1: "||a---|----|l---|----|"
      # Beat 1: Accent, Beat 3: Loud, rest: Normal

Common Patterns

Basic 4/4 Beat:

"||O---|O---|O---|O---|"  # Quarter notes
"||O-O-|O-O-|O-O-|O-O-|"  # Eighth notes

6/8 Pattern:

"||O--|S--|O--|S--|"      # 12 steps, grouped by 3

User Guides

Comprehensive guides for using Percussion Studio:

Platform	English	Italiano
Desktop	User Guide (EN)	Guida Utente (IT)
Mobile	User Guide (EN)	Guida Utente (IT)

Documentation

• data-specifications.md: Detailed technical specifications
• adding-instruments.md: Step-by-step guide for adding new instruments
• symbol-design.md: Shape-sound design principles (phono-symbolism)

License

This project is open source. See the repository for license details.