# MusicGen TOML Configuration Schema
# Complete reference for all available fields and options

# ============================================================================
# METADATA SECTION
# Optional information about your composition
# ============================================================================

[metadata]
title = "My Composition"                  # Title of the track
artist = "Artist Name"                    # Your name or band name
description = "An electronic song"        # Description of the composition
tags = ["electronic", "ambient", "chill"] # Genre tags or keywords

# ============================================================================
# COMPOSITION SECTION
# Core musical settings that define the overall structure
# ============================================================================

[composition]
# Musical key - can be MIDI note number (60 = C4) or note name
key = "C4" # Options: MIDI numbers 0-127 OR note names like "C4", "F#3", "Bb5"

# Scale type - defines which notes are used
scale = "major" # Options: "major", "minor", "dorian", "phrygian", "lydian",
#          "mixolydian", "aeolian", "locrian", "pentatonic",
#          "blues", "chromatic"

# Tempo in beats per minute
tempo = 120.0 # Range: 40.0 - 300.0 BPM

# Time signature - how many beats per measure
[composition.time_signature]
numerator = 4   # Beats per measure (1-16)
denominator = 4 # Note value for one beat (2, 4, 8, or 16)

# Composition length and complexity
measures = 32          # Number of measures (1-1000)
complexity = 0.7       # Overall complexity (0.0-1.0, default: 0.6)
harmony_density = 0.8  # How much harmony/chords (0.0-1.0, default: 0.7)
rhythmic_density = 0.6 # How busy the rhythm is (0.0-1.0, default: 0.8)
seed = 12345           # Random seed for reproducible generation (optional)

# ============================================================================
# TRACKS SECTION
# Each track is like one instrument in your band
# ============================================================================

# Example 1: Custom melody track
[[tracks]]
name = "main_melody"
instrument = "piano" # Options: "sine", "square", "sawtooth", "triangle", "noise", "piano"
volume = 0.8         # Track volume (0.0-1.0)

[tracks.pattern]
type = "custom"    # Pattern type: "custom", "chord", "arpeggio", "sequence"
loop_length = 16.0 # How long before pattern repeats (in beats)

# Individual notes in the pattern
[[tracks.pattern.steps]]
time = 0.0     # When to play (in beats from start of loop)
note = "C5"    # MIDI number or note name
duration = 1.5 # How long to hold the note (in beats)
velocity = 0.7 # How loud to play this note (0.0-1.0)

[[tracks.pattern.steps]]
time = 2.0
note = "E5"
duration = 1.0
velocity = 0.6

[[tracks.pattern.steps]]
time = 4.0
note = "G5"
duration = 2.0
velocity = 0.8

# Effects for this track
[[tracks.effects]]
type = "reverb"
room_size = 0.7 # Size of the reverb space (0.0-1.0)
damping = 0.5   # How much high frequencies are absorbed (0.0-1.0)
mix = 0.3       # How much effect to blend in (0.0-1.0)

[[tracks.effects]]
type = "delay"
time = 0.25    # Delay time in seconds (0.01-2.0)
feedback = 0.3 # How much delay repeats (0.0-0.95)
mix = 0.2      # How much effect to blend in (0.0-1.0)

# Example 2: Chord progression track
[[tracks]]
name = "harmony"
instrument = "sawtooth"
volume = 0.6

[tracks.pattern]
type = "chord"
loop_length = 16.0
voicing = "spread" # Options: "close", "spread", "drop2", "drop3"
octave = 3         # Which octave to play chords in (0-8)

# Chord progression
[[tracks.pattern.chord_progression]]
time = 0.0
chord = "Cmaj7" # Chord name (e.g., "C", "Am", "F#dim", "Bbmaj7")
duration = 4.0

[[tracks.pattern.chord_progression]]
time = 4.0
chord = "Am7"
duration = 4.0

[[tracks.pattern.chord_progression]]
time = 8.0
chord = "Fmaj7"
duration = 4.0

[[tracks.pattern.chord_progression]]
time = 12.0
chord = "G7"
duration = 4.0

# Effects for chord track
[[tracks.effects]]
type = "lowpass"
cutoff = 2000.0  # Cutoff frequency in Hz (20-20000)
resonance = 1.2  # Filter resonance (0.1-10.0)

# Example 3: Bass track
[[tracks]]
name = "bass"
instrument = "sine"
volume = 0.9

[tracks.pattern]
type = "custom"
loop_length = 8.0

[[tracks.pattern.steps]]
time = 0.0
note = "C2"
duration = 1.0
velocity = 0.9

[[tracks.pattern.steps]]
time = 2.0
note = "G2"
duration = 1.0
velocity = 0.8

[[tracks.pattern.steps]]
time = 4.0
note = "A2"
duration = 1.0
velocity = 0.8

[[tracks.pattern.steps]]
time = 6.0
note = "F2"
duration = 1.0
velocity = 0.9

# Bass effects
[[tracks.effects]]
type = "highpass"
cutoff = 80.0     # Remove very low frequencies
resonance = 0.7

# Example 4: Percussion track
[[tracks]]
name = "drums"
instrument = "noise"
volume = 0.7

[tracks.pattern]
type = "custom"
loop_length = 4.0

# Kick drum
[[tracks.pattern.steps]]
time = 0.0
note = "C1"    # Low note for kick
duration = 0.1
velocity = 1.0

[[tracks.pattern.steps]]
time = 2.0
note = "C1"
duration = 0.1
velocity = 1.0

# Snare/hi-hat
[[tracks.pattern.steps]]
time = 1.0
note = "D4"     # Higher note for snare
duration = 0.05
velocity = 0.7

[[tracks.pattern.steps]]
time = 3.0
note = "D4"
duration = 0.05
velocity = 0.7

# Drum effects
[[tracks.effects]]
type = "distortion"
drive = 1.5         # Amount of distortion (1.0-10.0)
tone = 0.6          # Tone control (0.0-1.0)

[[tracks.effects]]
type = "chorus"
rate = 1.2      # Modulation rate in Hz (0.1-10.0)
depth = 0.4     # Modulation depth (0.0-1.0)
layers = 3      # Number of chorus layers (1-8)
mix = 0.3

# ============================================================================
# SECTIONS SECTION (Optional)
# For structured compositions with different parts
# ============================================================================

[[sections]]
name = "intro"
measures = 8
tempo = 100.0    # Optional tempo change for this section
complexity = 0.3 # Lower complexity for intro
repeat = 1       # How many times to repeat this section

[[sections]]
name = "verse"
measures = 16
complexity = 0.6
repeat = 2

[[sections]]
name = "chorus"
measures = 16
tempo = 125.0    # Faster tempo for chorus
complexity = 0.8
key = "F4"       # Optional key change
scale = "major"  # Optional scale change
repeat = 2

[[sections]]
name = "bridge"
measures = 8
complexity = 0.9
key = "Am"       # Relative minor
repeat = 1

[[sections]]
name = "outro"
measures = 8
tempo = 90.0     # Slower outro
complexity = 0.2
repeat = 1

# ============================================================================
# EXPORT SECTION
# How to save your finished composition
# ============================================================================

[export]
filename = "my_song" # Output filename (without extension)
format = "wav"       # Only "wav" currently supported
sample_rate = 44100  # Options: 22050, 44100, 48000, 96000
bit_depth = 24       # Options: 16, 24, 32
stereo = true        # true for stereo, false for mono
max_duration = 180.0 # Maximum length in seconds (optional)

# Optional: Generate variations of your composition
[export.variations]
count = 3              # Number of variations to generate
vary_complexity = true # Vary the complexity between versions
vary_rhythm = true     # Vary the rhythmic patterns
vary_harmony = false   # Vary the chord progressions
vary_tempo = false     # Vary the tempo

# ============================================================================
# EFFECT TYPES REFERENCE
# Complete list of all available effects and their parameters
# ============================================================================

# FILTERS
# [[tracks.effects]]
# type = "lowpass"            # Removes high frequencies (makes sound warmer/duller)
# cutoff = 1000.0             # Frequency cutoff in Hz (20-20000)
# resonance = 1.0             # Emphasis at cutoff frequency (0.1-10.0)

# [[tracks.effects]]
# type = "highpass"           # Removes low frequencies (makes sound thinner/brighter)
# cutoff = 100.0              # Frequency cutoff in Hz (20-20000)
# resonance = 1.0             # Emphasis at cutoff frequency (0.1-10.0)

# TIME-BASED EFFECTS
# [[tracks.effects]]
# type = "delay"              # Echo effect
# time = 0.25                 # Delay time in seconds (0.01-2.0)
# feedback = 0.3              # How much delay feeds back (0.0-0.95)
# mix = 0.3                   # Wet/dry mix (0.0-1.0)

# [[tracks.effects]]
# type = "reverb"             # Spatial reverb
# room_size = 0.5             # Size of reverb space (0.0-1.0)
# damping = 0.5               # High frequency absorption (0.0-1.0)
# mix = 0.3                   # Wet/dry mix (0.0-1.0)

# [[tracks.effects]]
# type = "chorus"             # Thickening/modulation effect
# rate = 1.0                  # Modulation rate in Hz (0.1-10.0)
# depth = 0.5                 # Modulation depth (0.0-1.0)
# layers = 3                  # Number of voices (1-8)
# mix = 0.3                   # Wet/dry mix (0.0-1.0)

# DISTORTION
# [[tracks.effects]]
# type = "distortion"         # Hard clipping distortion
# drive = 2.0                 # Amount of distortion (1.0-10.0)
# tone = 0.5                  # Tone control (0.0-1.0, 0=dark, 1=bright)

# LO-FI EFFECTS
# [[tracks.effects]]
# type = "vinyl"              # Vinyl crackle and surface noise
# intensity = 0.5             # Crackle intensity (0.0-1.0)
# frequency = 0.5             # Crackle frequency (0.0-1.0)
# mix = 0.3                   # Wet/dry mix (0.0-1.0)

# [[tracks.effects]]
# type = "tape"               # Tape saturation and warmth
# drive = 2.0                 # Saturation amount (1.0-10.0)
# warmth = 0.7                # Warmth/color (0.0-1.0)
# mix = 0.5                   # Wet/dry mix (0.0-1.0)

# [[tracks.effects]]
# type = "bitcrusher"         # Digital degradation
# bit_depth = 8.0             # Bit depth reduction (1.0-16.0)
# sample_rate_reduction = 2.0 # Sample rate reduction factor (1.0-10.0)
# mix = 0.5                   # Wet/dry mix (0.0-1.0)

# ============================================================================
# INSTRUMENT TYPES REFERENCE
# ============================================================================

# instrument = "sine"         # Pure sine wave - smooth, warm, flute-like
# instrument = "square"       # Square wave - classic video game sound, punchy
# instrument = "sawtooth"     # Sawtooth wave - bright, buzzy, good for leads
# instrument = "triangle"     # Triangle wave - mellow, soft, like filtered square
# instrument = "noise"        # White noise - for percussion and texture
# instrument = "piano"        # Natural piano with harmonics

# ============================================================================
# PATTERN TYPES REFERENCE
# ============================================================================

# type = "custom"             # Specify exact notes and timing
# type = "chord"              # Play chord progressions
# type = "arpeggio"           # Arpeggiate chords (play notes one after another)
# type = "sequence"           # Step sequencer patterns

# ============================================================================
# CHORD NAMES REFERENCE
# ============================================================================

# Basic triads: "C", "Dm", "E", "F#", "Bb"
# Seventh chords: "Cmaj7", "Dm7", "E7", "F#m7b5", "Bbmaj7"
# Extended chords: "C9", "Dm11", "E13"
# Altered chords: "C7#11", "Dm7b5", "E7alt"
# Diminished/Augmented: "Cdim", "Caug", "C°7", "C+7"

# ============================================================================
# NOTE NAMES REFERENCE
# ============================================================================

# Format: [Note][Accidental][Octave]
# Notes: C, D, E, F, G, A, B
# Accidentals: # (sharp), b (flat), ♯, ♭
# Octaves: 0-9 (C4 = middle C = MIDI 60)
# Examples: "C4", "F#3", "Bb5", "A0", "G9"

# MIDI equivalents:
# C4 = 60, C#4 = 61, D4 = 62, D#4 = 63, E4 = 64, F4 = 65
# F#4 = 66, G4 = 67, G#4 = 68, A4 = 69, A#4 = 70, B4 = 71
# Add/subtract 12 for different octaves