Documentation | BeatBlocks

What Are Stems?

In music production, stems are individual audio tracks that make up a complete musical composition. In BeatBlocks, stems are the building blocks of your generative music compositions. Each stem represents a distinct musical element such as drums, bass, melody, vocals, or effects.

BeatBlocks uses these stems to create dynamic, generative compositions by selectively combining and arranging them based on rules you define. This allows for unique but reproducible musical experiences that can be inscribed on the Bitcoin blockchain.

Key Characteristics of Stems

Individual audio files (MP3, WAV, OGG formats)
Typically loop-able musical elements
Represent distinct parts of a composition
Can be combined with other stems to create a full mix
Have properties like volume, looping behavior, and alignment

Stem Properties

Each stem in BeatBlocks has several properties that define how it behaves within a composition:

Basic Properties

id:
Unique identifier for the stem
name:
Human-readable name for the stem
path:
URL or path to the audio file (often an inscription ID)
volume:
Playback volume (0.0 to 1.0)

Playback Properties

loopLength:
Length of the stem in bars (e.g., 1, 2, 4, 8)
loop:
Whether the stem should loop (true/false)
alignment:
How the stem aligns with the beat ("start", "center", "end")
offset:
Optional timing offset in beats

Generation Properties

groups:
Categories the stem belongs to (e.g., "v1", "drums", "melody")
mutex:
Mutually exclusive categories (only one stem from each mutex can play at once)
weight:
Optional selection probability weight for random generation

Example Stem

{
  "id": "kick_drum",
  "name": "Kick Drum",
  "loopLength": 2,
  "path": "/content/<INSCRIPTION_ID>",
  "volume": 1,
  "loop": true,
  "alignment": "start",
  "groups": ["drums", "v1"],
  "mutex": ["percussion"]
}

Preparing Stems for BeatBlocks

Creating effective stems for BeatBlocks requires careful preparation to ensure they work well together in a generative context.

Audio Format Recommendations

Supported formats: MP3, WAV, OGG
Recommended format: MP3 (good balance of quality and file size)
Sample rate: 44.1kHz (standard for web audio)
Bit depth: 16-bit is sufficient for most use cases
File size: Keep files as small as possible while maintaining quality (important for blockchain inscriptions)

Organizing Stems with Groups and Mutexes

BeatBlocks uses a powerful system of groups and mutexes to organize stems and control how they interact with each other.

Groups

Groups are categories that stems can belong to. They help organize stems by type or function and can be used in generation rules.

Examples of common groups:

Instrument types: "drums", "bass", "melody", "fx"
Variation sets: "v1", "v2", "v3", "v4"
Energy levels: "low", "medium", "high"
Sections: "intro", "verse", "chorus", "bridge"

Mutexes

Mutexes (mutually exclusive categories) ensure that only one stem from each mutex category can play at a time. This prevents conflicting elements from playing simultaneously.

Examples of common mutexes:

"drums" - Only one drum pattern plays at once
"bass" - Only one bassline plays at once
"lead" - Only one lead melody plays at once
"vocals" - Only one vocal track plays at once

Example: Organizing Stems with Groups and Mutexes

// Drum stems with different patterns
{
  "id": "kick_pattern_1",
  "name": "Kick Pattern 1",
  "loopLength": 2,
  "path": "/content/<INSCRIPTION_ID>",
  "volume": 1,
  "loop": true,
  "alignment": "start",
  "groups": ["drums", "v1"],
  "mutex": ["percussion"]
},
{
  "id": "kick_pattern_2",
  "name": "Kick Pattern 2",
  "loopLength": 2,
  "path": "/content/<INSCRIPTION_ID>",
  "volume": 1,
  "loop": true,
  "alignment": "start",
  "groups": ["drums", "v2"],
  "mutex": ["percussion"]
},

// Bass stems with different patterns
{
  "id": "bass_pattern_1",
  "name": "Bass Pattern 1",
  "loopLength": 4,
  "path": "/content/<INSCRIPTION_ID>",
  "volume": 0.9,
  "loop": true,
  "alignment": "start",
  "groups": ["bass", "v1"],
  "mutex": ["basslines"]
},
{
  "id": "bass_pattern_2",
  "name": "Bass Pattern 2",
  "loopLength": 4,
  "path": "/content/<INSCRIPTION_ID>",
  "volume": 0.9,
  "loop": true,
  "alignment": "start",
  "groups": ["bass", "v2"],
  "mutex": ["basslines"]
}

In this example, the generation algorithm can select one percussion pattern and one bassline pattern. The "v1" and "v2" groups could be used to create consistent variations where all "v1" elements play together.

Advanced Alignment Techniques

One of the most powerful features of BeatBlocks is the ability to precisely control how stems align within bars. By strategically using alignment properties, you can create sophisticated musical effects and transitions.

Alignment Options

start:
Aligns the stem to begin playing at the start of the section (default)
center:
Positions the stem to begin playing at the middle of the section
center-end:
Calculates the start time so that the stem will finish playing exactly at the center of the section
end:
Calculates the start time so that the stem will finish playing exactly at the end of the section

Creative Applications

Use end alignment for risers leading into new sections
Apply center alignment for impact sounds at section transitions
Combine different alignments to create complex rhythmic interplay
Use start alignment for downbeat-focused elements

Example: Creating Transitions with Alignment

// Template section with transition elements
{
  "length": 2,
  "layerCount": 3,
  "inclusions": ["transition", "fx"],
  "exclusions": ["drums", "bass", "lead"],
  "layers": [
    {
      "id": "reverse_crash",
      "loopLength": 1,
      "path": "/content/<INSCRIPTION_ID>",
      "volume": 1,
      "loop": false,
      "alignment": "end",  // Will end exactly at the section boundary
      "groups": ["fx", "transition"],
      "mutex": ["impact"]
    },
    {
      "id": "riser_synth",
      "loopLength": 2,
      "path": "/content/<INSCRIPTION_ID>",
      "volume": 0.8,
      "loop": false,
      "alignment": "end",  // Will build up to the section boundary
      "groups": ["fx", "transition"],
      "mutex": ["riser"]
    },
    {
      "id": "impact_hit",
      "loopLength": 1,
      "path": "/content/<INSCRIPTION_ID>",
      "volume": 1,
      "loop": false,
      "alignment": "start",  // Will hit exactly at the start of the next section
      "groups": ["fx", "impact"],
      "mutex": ["impact"]
    }
  ]
}

This example shows how to create a transition section where a reverse crash and riser build up to the section boundary (using "end" alignment), while an impact hit is positioned to land exactly at the start of the next section (using "start" alignment).

Combining Alignment with Loop Properties

For even more control, combine alignment settings with loop properties:

One-shot effects (loop: false):
Perfect for impacts, hits, and transitional elements. Use with "start" or "end" alignment for precise timing.
Looping elements with strategic alignment:
Create interesting rhythmic effects by centering looping elements or offsetting them from the grid.

Offset property:

For even more precise control, combine alignment with the offset property to fine-tune timing.

{
  "id": "delayed_clap",
  "loopLength": 2,
  "path": "/content/<INSCRIPTION_ID>",
  "volume": 0.9,
  "loop": true,
  "alignment": "start",
  "offset": 0.5,  // Delays by half a beat
  "groups": ["drums", "percussion"],
  "mutex": ["clap"]
}

Inscribing Stems to Bitcoin

To use stems in BeatBlocks, they need to be inscribed to the Bitcoin blockchain. This creates permanent, immutable audio files that can be referenced in your BeatBlock compositions.

Steps to Inscribe Stems

Prepare your audio file
Optimize your audio file for size and quality. MP3 format at 128-192kbps is recommended for a good balance.

Use an Ordinals wallet to inscribe

# Using the ord CLI tool
ord wallet inscribe kick_pattern.mp3 \
  --fee-rate 10 \
  --content-type audio/mpeg

Get the inscription ID
After inscription, you'll receive an inscription ID that looks like: 1234abcd5678efgh9012ijkl3456mnop7890qrst...

Reference in your BeatBlock JSON

{
  "id": "kick_pattern_1",
  "name": "Kick Pattern 1",
  "loopLength": 2,
  "path": "/content/<INSCRIPTION_ID>",
  "volume": 1,
  "loop": true,
  "alignment": "start",
  "groups": ["drums", "v1"],
  "mutex": ["percussion"]
}

Core Concepts

Advanced Topics

Protocol

API Reference

Stems