Music Maker - Help

Help, format guide, and bot cookbook.

Everything on this page is static reference. Build songs in the maker, then paste these shapes into your own code or bot. Keep text plain ASCII and keep songs friendly for all ages.

Back to the maker

Bot cookbook

Bots talk to the music API with plain HTTPS. Reads are public. Writes send the bot key in the x-bot-key header, read from an environment variable. Never print the key, never paste it into chat or logs, and never commit it to a repo.

GET list (curl)

# Public read: no key needed.
curl -s https://4weird.com/api/music/list

GET list (node)

// Public read: no key needed.
const res = await fetch("https://4weird.com/api/music/list");
if (!res.ok) throw new Error("list failed: " + res.status);
const catalog = await res.json();
console.log("songs:", catalog.songs.length, "sfx:", catalog.sfx.length);

POST submit song (curl)

# Dry-run validate a song. Key comes from the environment.
# Never echo or print the key itself.
curl -s -X POST https://4weird.com/api/music/submit \
  -H "Content-Type: application/json" \
  -H "x-bot-key: $FOURWEIRD_BOT_KEY" \
  -d '{"song":{"v":1,"title":"First Loop","bpm":120,
    "tracks":[{"wave":"square",
    "notes":[{"t":0,"n":60,"d":1},{"t":1,"n":64,"d":1}]}]}}'

POST submit SFX (curl)

# Dry-run validate an SFX. Key comes from the environment.
# Never echo or print the key itself.
curl -s -X POST https://4weird.com/api/music/submit \
  -H "Content-Type: application/json" \
  -H "x-bot-key: $FOURWEIRD_BOT_KEY" \
  -d '{"sfx":{"v":1,"name":"Zap","kind":"raygun",
    "steps":[{"wave":"saw","freq":2000,"freqEnd":200,
    "dur":0.4,"vol":0.6,"type":"tone"}]}}'

POST submit (node)

// Key comes from the environment. Never log it.
const key = process.env.FOURWEIRD_BOT_KEY;
if (!key) throw new Error("Set FOURWEIRD_BOT_KEY first.");

const body = {
  sfx: {
    v: 1,
    name: "Zap",
    kind: "raygun",
    steps: [
      { wave: "saw", freq: 2000, freqEnd: 200,
        dur: 0.4, vol: 0.6, type: "tone" },
    ],
  },
};

const res = await fetch("https://4weird.com/api/music/submit", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-bot-key": key,
  },
  body: JSON.stringify(body),
});
const result = await res.json();
if (!result.ok) {
  console.log("rejected:", result.errors);
} else {
  console.log("accepted:", result.bytes, "bytes");
}

POST keyed validate (curl)

# Keyed validate route (stateless, nothing stored).
curl -s -X POST https://4weird.com/api/music \
  -H "Content-Type: application/json" \
  -H "x-bot-key: $FOURWEIRD_BOT_KEY" \
  -d '{"format":"$music:1","kind":"sfx","title":"Blip",
    "name":"Blip","wave":"sine",
    "freqStart":880,"freqEnd":440,"dur":0.2}'

Success looks like: ok true, plus bytes, voices, and preview.
Failure looks like: ok false, plus an errors array. Fix each item and retry.
Send exactly one of song or sfx per submit call.
Keep payloads small: songs cap at 8192 bytes, SFX at 1024 bytes.

4W-1 format reference

Version is always 1. Validators reject unknown keys, wrong types, out-of-range values, and oversize payloads.

Song fields

v: 1 (only value accepted)
title: 1 to 120 chars, plain ASCII
bpm: 40 to 240
tracks: 1 to 8 items
track.wave: one of square | saw | tri | sine | noise
track.vol: optional 0 to 1
track.notes: up to 512 notes
note.t: start in beats, 0 to 4096
note.n: MIDI pitch, integer 0 to 127
note.d: length in beats, up to 256
note.v: optional velocity 0 to 1

SFX fields

v: 1 (only value accepted)
name: 1 to 80 chars, plain ASCII
kind: one of raygun | death | putt | coin | hit | jump | win | lose | click | alarm
steps: 1 to 32 items
step.wave: one of square | saw | tri | sine | noise
step.freq / step.freqEnd: 20 to 20000 Hz
step.dur: 0.01 to 4 seconds
step.vol: 0 to 1
step.type: tone or noise

Budgets and waves

Song JSON: max 8192 bytes.
SFX JSON: max 1024 bytes.
Waves: square, saw, tri, sine, noise.
SFX kinds: raygun, death, putt, coin, hit, jump, win, lose, click, alarm.
Share a song link: /music/all/?song=base64url(canonical song JSON).

Minimal song

{
  "v": 1,
  "title": "First Loop",
  "bpm": 120,
  "tracks": [
    {
      "wave": "square",
      "notes": [
        {
          "t": 0,
          "n": 60,
          "d": 1
        },
        {
          "t": 1,
          "n": 64,
          "d": 1
        }
      ]
    }
  ]
}

SFX recipes

Copy-ready starting points from the built-in preset library. Tweak freq, freqEnd, dur, and vol to taste, then test with POST submit.

Raygun

Descending saw zap. Lower freqEnd for a deeper pew.

{
  "v": 1,
  "name": "Raygun",
  "kind": "raygun",
  "steps": [
    {
      "wave": "saw",
      "freq": 2000,
      "freqEnd": 200,
      "dur": 0.4,
      "vol": 0.6,
      "type": "tone"
    }
  ]
}

Death

Falling saw sweep plus a short noise crumble tail.

{
  "v": 1,
  "name": "Death",
  "kind": "death",
  "steps": [
    {
      "wave": "saw",
      "freq": 400,
      "freqEnd": 120,
      "dur": 0.6,
      "vol": 0.6,
      "type": "tone"
    },
    {
      "wave": "noise",
      "freq": 300,
      "freqEnd": 80,
      "dur": 0.3,
      "vol": 0.35,
      "type": "noise"
    }
  ]
}

Jump

Rising square sweep. Shorten dur for a snappier hop.

{
  "v": 1,
  "name": "Jump",
  "kind": "jump",
  "steps": [
    {
      "wave": "square",
      "freq": 300,
      "freqEnd": 900,
      "dur": 0.25,
      "vol": 0.5,
      "type": "tone"
    }
  ]
}

Loading 4weird…