simple-beatmaker/README.md

Generate drum sounds from scratch and create beats programmatically with pure JavaScript - no external WAV files needed!

# Simple Beatmaker

A Node.js package that generates drum sounds from scratch and creates beats programmatically. No external WAV files needed - all drum sounds are synthesized using mathematical formulas!

## Features

- 🥁 **3 Drum Sets**: Classic (acoustic), Electronic (synthetic), Vintage (analog)
- 🎵 **5 Built-in Patterns**: basic-rock, electronic-dance, vintage-groove, funky-break, minimal-techno
- 🎛️ **Custom Patterns**: Create your own 16-step patterns
- 🔊 **6 Drum Types**: Kick, Snare, Hi-hat, Clap, Crash, Tom
- 🎮 **Easy Generation**: Generate template files with CLI commands
- ⚡ **Cross-platform**: Works on Windows, macOS, and Linux

## Installation

```bash
npm install -g simple-beatmaker
```

## Quick Start

### Option 1: Generate Template Files

Create a template file with all options:
```bash
beatmaker generate init
```

Or generate a simple kick-clap beat:
```bash
beatmaker generate kick-clap
```

Then edit the generated `.js` file and play it:
```bash
beatmaker play beatmaker-template.js
```

### Option 2: Create Your Own JS File

Create a file called `my-beat.js`:

```javascript
const SimpleBeatmaker = require('simple-beatmaker');

const beatmaker = new SimpleBeatmaker();

// Create and play a beat
beatmaker
  .setBPM(120)
  .setDrumSet('classic')
  .usePreset('basic-rock')
  .play(2); // Play 2 loops
```

Then play it:
```bash
beatmaker play my-beat.js
```

That's it! The command will execute your JavaScript file and generate a WAV file that plays automatically.

## CLI Commands

```bash
# Generate template files
beatmaker generate init            # Creates beatmaker-template.js with all options
beatmaker generate kick-clap       # Creates kick-clap-beat.js with simple beat

# Play JavaScript beat files  
beatmaker play my-beat.js          # Execute and play your beat file

# Get help
beatmaker help                     # Show all available commands
```

## API Reference

### Creating Beats

```javascript
const SimpleBeatmaker = require('simple-beatmaker');
const beatmaker = new SimpleBeatmaker();

// Set tempo
beatmaker.setBPM(120); // Default: 120 BPM

// Choose drum set
beatmaker.setDrumSet('classic');   // Options: 'classic', 'electronic', 'vintage'

// Set output directory (optional)
beatmaker.setOutputDir('beats');   // Save to 'beats' folder (creates if needed)

// Use a preset pattern
beatmaker.usePreset('basic-rock'); // See available presets below

// Or create custom pattern
beatmaker.createPattern(bars, pattern);

// Generate and play
beatmaker.play(loops, filename);
```

### Drum Sets

- **classic**: Warm acoustic drum sounds with natural tones
- **electronic**: Sharp synthetic drums with digital character  
- **vintage**: Analog-style drums with warm, saturated sound

### Built-in Presets

- **basic-rock**: Classic 4/4 rock beat (4 bars)
- **electronic-dance**: Electronic dance pattern (2 bars)
- **vintage-groove**: Laid-back vintage groove (4 bars)
- **funky-break**: Syncopated funk pattern (2 bars)
- **minimal-techno**: Minimal techno beat (4 bars)

### Custom Patterns

Create 16-step patterns (16th notes per bar):

```javascript
const customPattern = [
  // Bar 1
  [
    ['kick'], null, ['hihat'], null,           // Steps 1-4
    ['snare'], null, ['hihat'], null,          // Steps 5-8
    ['kick'], null, ['hihat'], null,           // Steps 9-12
    ['snare'], null, ['hihat'], null           // Steps 13-16
  ],
  // Bar 2
  [
    ['kick'], ['hihat'], null, ['hihat'],
    ['snare'], ['snare'], ['hihat'], null,
    ['kick'], ['kick'], ['hihat'], ['snare'],
    ['snare'], ['kick'], ['hihat'], ['kick']
  ]
];

beatmaker.createPattern(2, customPattern);
```

#### Pattern Format

- Each bar has 16 steps (16th notes)
- `null` = silence on that step
- `['kick']` = kick drum on that step
- `['snare']` = snare drum on that step
- `['hihat']` = hihat on that step
- `['kick', 'snare']` = multiple drums on same step

#### Available Drums

- `kick` or `k`: Kick drum
- `snare` or `s`: Snare drum  
- `hihat` or `h`: Hi-hat
- `clap` or `c`: Hand clap
- `crash` or `x`: Crash cymbal
- `tom` or `t`: Tom drum

### Output Directory

By default, WAV files are saved to the current directory. You can specify a custom output directory:

```javascript
// Save to a specific folder
beatmaker.setOutputDir('my-beats');        // Creates 'my-beats' folder if needed

// Relative paths
beatmaker.setOutputDir('./output/drums');  // Save to output/drums

// Absolute paths  
beatmaker.setOutputDir('/home/user/music'); // Linux/macOS
beatmaker.setOutputDir('C:\\Music\\Beats'); // Windows

// Reset to default (current directory)
beatmaker.setOutputDir(null);
```

The directory will be created automatically if it doesn't exist.

## Examples

### Electronic Dance Beat

```javascript
const SimpleBeatmaker = require('simple-beatmaker');

const beatmaker = new SimpleBeatmaker();

beatmaker
  .setBPM(130)
  .setDrumSet('electronic')
  .usePreset('electronic-dance')
  .play(4, 'dance-track.wav');
```

### Custom Funk Pattern

```javascript
const SimpleBeatmaker = require('simple-beatmaker');

const beatmaker = new SimpleBeatmaker();

const funkyPattern = [
  [
    ['kick'], null, null, ['hihat'],
    null, ['clap'], ['kick'], null,           // Using clap instead of snare
    null, ['hihat'], ['kick'], null,
    ['tom'], null, ['hihat'], ['crash']       // Tom and crash at the end
  ]
];

beatmaker
  .setBPM(95)
  .setDrumSet('vintage')
  .createPattern(1, funkyPattern)
  .play(8, 'funk-groove.wav');
```

### Multiple Drum Sets Demo

```javascript
const SimpleBeatmaker = require('simple-beatmaker');

const beatmaker = new SimpleBeatmaker();

// Classic version
beatmaker.setBPM(120).setDrumSet('classic').usePreset('basic-rock').play(1, 'classic.wav');

// Electronic version  
beatmaker.setBPM(120).setDrumSet('electronic').usePreset('basic-rock').play(1, 'electronic.wav');

// Vintage version
beatmaker.setBPM(120).setDrumSet('vintage').usePreset('basic-rock').play(1, 'vintage.wav');
```

### Using Custom Output Directory

```javascript
const SimpleBeatmaker = require('simple-beatmaker');

const beatmaker = new SimpleBeatmaker();

// Organize beats by genre
beatmaker
  .setBPM(128)
  .setDrumSet('electronic')
  .setOutputDir('beats/electronic')     // Save to beats/electronic/ folder
  .usePreset('electronic-dance')
  .play(2, 'dance-beat.wav');

// Different folder for rock beats
beatmaker
  .setBPM(120)
  .setDrumSet('classic')
  .setOutputDir('beats/rock')           // Save to beats/rock/ folder
  .usePreset('basic-rock')
  .play(2, 'rock-beat.wav');
```

## Workflow

1. **Option A**: Use `beatmaker generate init` to create a template, then customize it
2. **Option B**: Use `beatmaker generate kick-clap` for a quick start
3. **Option C**: Write your own JavaScript file from scratch
4. **Play**: Use `beatmaker play filename.js` to execute and generate audio

## Audio Output

- **Format**: WAV (44.1kHz, 16-bit, stereo)
- **Auto-play**: Generated files open in your default audio player
- **File location**: Saved in current directory with descriptive names

## How It Works

Simple Beatmaker generates all drum sounds mathematically:

- **Kick Drum**: Low-frequency sine waves with exponential decay
- **Snare Drum**: Filtered noise mixed with tonal components  
- **Hi-hat**: High-frequency filtered noise with fast decay
- **Clap**: Multiple burst noise patterns to simulate hand clapping
- **Crash Cymbal**: Complex metallic harmonics with shimmer
- **Tom Drum**: Tuned drum sounds with pitch bending

Different drum sets use different parameters and processing to create distinct sonic characters.

## Requirements

- Node.js 14.0.0 or higher
- No additional dependencies required

## License

MIT

## Contributing

Issues and pull requests welcome on GitHub!