Musicboxmelodies

Lists the music box types a melody can be written for, with their exact playable notes and rules. Call this before composing or validating a melody.

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

{
  "type": "object",
  "properties": {
    "ticks_per_beat": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "default_min_repeat_beats": {
      "type": "number"
    },
    "boxes": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "box": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "playable_notes": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "lowest": {
            "type": "string"
          },
          "highest": {
            "type": "string"
          },
          "has_sharps": {
            "type": "boolean"
          },
          "repeated_note_rule": {
            "type": "boolean"
          },
          "printable_strip": {
            "type": "boolean"
          }
        },
        "required": [
          "box",
          "name",
          "description",
          "playable_notes",
          "lowest",
          "highest",
          "has_sharps",
          "repeated_note_rule",
          "printable_strip"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "ticks_per_beat",
    "default_min_repeat_beats",
    "boxes"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

Searches the public catalog of music box tunes made by the Musicboxmelodies community. Search by song name, artist or arranger; optionally only tunes that have a version for one box type. Returns at most 20 per page.

{
  "type": "object",
  "properties": {
    "query": {
      "description": "Words to search in the song name, artist or arranger. Omit to list tunes.",
      "type": "string",
      "maxLength": 100
    },
    "box": {
      "description": "Only tunes with a version for this box.",
      "type": "string",
      "enum": [
        "15",
        "20",
        "30",
        "freestyle"
      ]
    },
    "page": {
      "description": "Page number, starting at 1.",
      "type": "integer",
      "minimum": 1,
      "maximum": 500
    },
    "page_size": {
      "description": "Results per page, 1-20 (default 10).",
      "type": "integer",
      "minimum": 1,
      "maximum": 20
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

{
  "type": "object",
  "properties": {
    "page": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "pages": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "total": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "songs": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "song_id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "artist": {
            "type": "string"
          },
          "arranged_by": {
            "type": "string"
          },
          "boxes": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "url": {
            "type": "string"
          }
        },
        "required": [
          "song_id",
          "name",
          "artist",
          "arranged_by",
          "boxes",
          "tags",
          "url"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "page",
    "pages",
    "total",
    "songs"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

Gets a music box tune with its notes in the melody format (the same one validate_melody accepts), for one box version. Works for public tunes, for the signed-in person's own songs, and for a song this agent saved anonymously (pass its claim_token). Use search_songs or list_my_songs to find song ids.

{
  "type": "object",
  "properties": {
    "song_id": {
      "type": "string",
      "maxLength": 40,
      "description": "Song id from search_songs, list_my_songs or create_song."
    },
    "box": {
      "description": "Which version to return. Defaults to the version the arranger marked as preferred.",
      "type": "string",
      "enum": [
        "15",
        "20",
        "30",
        "freestyle"
      ]
    },
    "claim_token": {
      "description": "Only for songs saved without an account: the claim_token create_song returned.",
      "type": "string",
      "maxLength": 100
    }
  },
  "required": [
    "song_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

{
  "type": "object",
  "properties": {
    "song_id": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "artist": {
      "type": "string"
    },
    "arranged_by": {
      "type": "string"
    },
    "description": {
      "type": "string"
    },
    "private": {
      "type": "boolean"
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "url": {
      "type": "string"
    },
    "composer_url": {
      "type": "string"
    },
    "available_boxes": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "melody": {
      "type": "object",
      "properties": {
        "box": {
          "type": "string"
        },
        "bpm": {
          "type": "number"
        },
        "notes": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "pitch": {
                "type": [
                  "string",
                  "number"
                ]
              },
              "beat": {
                "type": "number"
              },
              "ticks": {
                "type": "number"
              }
            },
            "required": [
              "pitch"
            ],
            "additionalProperties": false
          }
        }
      },
      "required": [
        "box",
        "bpm",
        "notes"
      ],
      "additionalProperties": false
    },
    "stats": {
      "type": "object",
      "properties": {
        "note_count": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991
        },
        "illegal_count": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991
        },
        "duration_seconds": {
          "type": "number"
        },
        "strip_length_cm": {
          "type": "number"
        }
      },
      "required": [
        "note_count",
        "illegal_count",
        "duration_seconds"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "song_id",
    "name",
    "artist",
    "arranged_by",
    "private",
    "tags",
    "url",
    "available_boxes",
    "melody",
    "stats"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

Checks whether a melody can be played on a music box: notes outside the box, same note repeated too fast, off-grid notes, tempo and length. Every issue names the note and how to fix it. Saves nothing. Call it before offering a melody to the person.

{
  "type": "object",
  "properties": {
    "box": {
      "type": "string",
      "enum": [
        "15",
        "20",
        "30",
        "freestyle"
      ],
      "description": "Music box type: \"15\", \"20\", \"30\" (notes) or \"freestyle\" (digital only). See list_music_boxes."
    },
    "bpm": {
      "type": "number",
      "minimum": 30,
      "maximum": 300,
      "description": "Tempo in beats per minute (30-300)."
    },
    "notes": {
      "minItems": 1,
      "maxItems": 2000,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "pitch": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 8
              },
              {
                "type": "integer",
                "minimum": 0,
                "maximum": 127
              }
            ],
            "description": "Note name like \"C5\", \"F#4\", \"Bb3\", or a MIDI number (60 = C4)."
          },
          "beat": {
            "description": "When the note sounds, in quarter notes from 0 (e.g. 0, 1, 1.5).",
            "type": "number",
            "minimum": 0
          },
          "ticks": {
            "description": "Alternative to beat: 192 ticks per quarter note.",
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991
          }
        },
        "required": [
          "pitch"
        ]
      },
      "description": "Notes in any order, at most 2000. Only onsets matter: music boxes have no note durations."
    },
    "illegal_threshold_ticks": {
      "description": "Minimum gap between two identical notes, in ticks (default 384 = 2 beats).",
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    },
    "snap_beats": {
      "description": "Optional grid in beats (e.g. 0.5) to warn about notes off that grid.",
      "type": "number",
      "exclusiveMinimum": 0
    }
  },
  "required": [
    "box",
    "bpm",
    "notes"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

{
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean"
    },
    "issues": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string"
          },
          "severity": {
            "type": "string",
            "enum": [
              "error",
              "warning"
            ]
          },
          "index": {
            "description": "Index of the note in the input, when the issue is about one note.",
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "message": {
            "type": "string"
          },
          "suggestions": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "code",
          "severity",
          "message"
        ],
        "additionalProperties": false
      }
    },
    "stats": {
      "type": "object",
      "properties": {
        "note_count": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991
        },
        "illegal_count": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991
        },
        "duration_seconds": {
          "type": "number"
        },
        "strip_length_cm": {
          "type": "number"
        }
      },
      "required": [
        "note_count",
        "illegal_count",
        "duration_seconds"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "ok",
    "issues",
    "stats"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

Adjusts a melody so it can be played on a music box and lists every change. Strategies: "transpose" (shift the whole melody to the key that fits best), "nearest_note" (move each unplayable note to the closest playable one), "transpose_then_nearest" (default: both). Optionally snaps notes to a grid. Returns the new melody and its validation.

{
  "type": "object",
  "properties": {
    "box": {
      "type": "string",
      "enum": [
        "15",
        "20",
        "30",
        "freestyle"
      ],
      "description": "Music box type: \"15\", \"20\", \"30\" (notes) or \"freestyle\" (digital only). See list_music_boxes."
    },
    "bpm": {
      "type": "number",
      "minimum": 30,
      "maximum": 300,
      "description": "Tempo in beats per minute (30-300)."
    },
    "notes": {
      "minItems": 1,
      "maxItems": 2000,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "pitch": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 8
              },
              {
                "type": "integer",
                "minimum": 0,
                "maximum": 127
              }
            ],
            "description": "Note name like \"C5\", \"F#4\", \"Bb3\", or a MIDI number (60 = C4)."
          },
          "beat": {
            "description": "When the note sounds, in quarter notes from 0 (e.g. 0, 1, 1.5).",
            "type": "number",
            "minimum": 0
          },
          "ticks": {
            "description": "Alternative to beat: 192 ticks per quarter note.",
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991
          }
        },
        "required": [
          "pitch"
        ]
      },
      "description": "Notes in any order, at most 2000. Only onsets matter: music boxes have no note durations."
    },
    "illegal_threshold_ticks": {
      "description": "Minimum gap between two identical notes, in ticks (default 384 = 2 beats).",
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    },
    "target_box": {
      "description": "Box to fit into. Defaults to the melody's box.",
      "type": "string",
      "enum": [
        "15",
        "20",
        "30",
        "freestyle"
      ]
    },
    "strategy": {
      "type": "string",
      "enum": [
        "transpose",
        "nearest_note",
        "transpose_then_nearest"
      ]
    },
    "quantize_beats": {
      "description": "Snap every note to this grid in beats (e.g. 0.5 = eighth notes).",
      "type": "number",
      "exclusiveMinimum": 0
    }
  },
  "required": [
    "box",
    "bpm",
    "notes"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

{
  "type": "object",
  "properties": {
    "summary": {
      "type": "string"
    },
    "semitones": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "changes": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "index": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "kind": {
            "type": "string"
          },
          "from": {
            "type": "string"
          },
          "to": {
            "type": "string"
          }
        },
        "required": [
          "index",
          "kind",
          "from",
          "to"
        ],
        "additionalProperties": false
      }
    },
    "melody": {
      "type": "object",
      "properties": {
        "box": {
          "type": "string"
        },
        "bpm": {
          "type": "number"
        },
        "notes": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "pitch": {
                "type": [
                  "string",
                  "number"
                ]
              },
              "beat": {
                "type": "number"
              },
              "ticks": {
                "type": "number"
              }
            },
            "required": [
              "pitch"
            ],
            "additionalProperties": false
          }
        }
      },
      "required": [
        "box",
        "bpm",
        "notes"
      ],
      "additionalProperties": false
    },
    "validation": {
      "type": "object",
      "properties": {
        "ok": {
          "type": "boolean"
        },
        "issues": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string"
              },
              "severity": {
                "type": "string",
                "enum": [
                  "error",
                  "warning"
                ]
              },
              "index": {
                "description": "Index of the note in the input, when the issue is about one note.",
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              },
              "message": {
                "type": "string"
              },
              "suggestions": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            },
            "required": [
              "code",
              "severity",
              "message"
            ],
            "additionalProperties": false
          }
        },
        "stats": {
          "type": "object",
          "properties": {
            "note_count": {
              "type": "integer",
              "minimum": -9007199254740991,
              "maximum": 9007199254740991
            },
            "illegal_count": {
              "type": "integer",
              "minimum": -9007199254740991,
              "maximum": 9007199254740991
            },
            "duration_seconds": {
              "type": "number"
            },
            "strip_length_cm": {
              "type": "number"
            }
          },
          "required": [
            "note_count",
            "illegal_count",
            "duration_seconds"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "ok",
        "issues",
        "stats"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "summary",
    "semitones",
    "changes",
    "melody",
    "validation"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

Lists what Musicboxmelodies sells, with current prices in US dollars and delivery times: custom music box melodies, custom printable strip designs and PRO composer accounts. Orders are placed and paid by the person on the website.

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

{
  "type": "object",
  "properties": {
    "currency": {
      "type": "string"
    },
    "products": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "product": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "url": {
            "type": "string"
          },
          "what_you_get": {
            "type": "string"
          },
          "delivery": {
            "type": "string"
          },
          "notes": {
            "type": "string"
          },
          "variations": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                },
                "price_usd": {
                  "type": "number"
                }
              },
              "required": [
                "name",
                "price_usd"
              ],
              "additionalProperties": false
            }
          }
        },
        "required": [
          "product",
          "name",
          "url",
          "what_you_get",
          "delivery",
          "notes",
          "variations"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "currency",
    "products"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

Saves a melody as a new private song. The melody must have no errors (run validate_melody or fit_melody_to_box first); warnings such as notes repeated too quickly are saved and marked, as in the composer. If the person is signed in, the song goes to their account and you get a link to open it in the composer. Without an account the song is saved anonymously and you get a claim link: give it to the person so they can keep it (valid 30 days). Set save_to_my_account to true to ask the person to sign in first (apps that cannot sign in mid-conversation should save without an account and give the claim link instead). Limits: 5 songs a day without an account, 15 a day with one.

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "description": "Song title."
    },
    "artist": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "description": "Original artist or composer (\"Traditional\" if unknown)."
    },
    "description": {
      "description": "Optional notes about the arrangement.",
      "type": "string",
      "maxLength": 1000
    },
    "tags": {
      "maxItems": 10,
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 30
      }
    },
    "box": {
      "type": "string",
      "enum": [
        "15",
        "20",
        "30",
        "freestyle"
      ],
      "description": "Music box type: \"15\", \"20\", \"30\" (notes) or \"freestyle\" (digital only). See list_music_boxes."
    },
    "bpm": {
      "type": "number",
      "minimum": 30,
      "maximum": 300,
      "description": "Tempo in beats per minute (30-300)."
    },
    "notes": {
      "minItems": 1,
      "maxItems": 2000,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "pitch": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 8
              },
              {
                "type": "integer",
                "minimum": 0,
                "maximum": 127
              }
            ],
            "description": "Note name like \"C5\", \"F#4\", \"Bb3\", or a MIDI number (60 = C4)."
          },
          "beat": {
            "description": "When the note sounds, in quarter notes from 0 (e.g. 0, 1, 1.5).",
            "type": "number",
            "minimum": 0
          },
          "ticks": {
            "description": "Alternative to beat: 192 ticks per quarter note.",
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991
          }
        },
        "required": [
          "pitch"
        ]
      },
      "description": "Notes in any order, at most 2000. Only onsets matter: music boxes have no note durations."
    },
    "illegal_threshold_ticks": {
      "description": "Minimum gap between two identical notes, in ticks (default 384 = 2 beats).",
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    },
    "save_to_my_account": {
      "description": "True to save it in the person's account; they will be asked to sign in if they are not.",
      "type": "boolean"
    }
  },
  "required": [
    "name",
    "artist",
    "box",
    "bpm",
    "notes"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

{
  "type": "object",
  "properties": {
    "song_id": {
      "type": "string"
    },
    "box": {
      "type": "string"
    },
    "private": {
      "type": "boolean"
    },
    "saved_to_account": {
      "type": "boolean"
    },
    "composer_url": {
      "type": "string"
    },
    "claim_url": {
      "type": "string"
    },
    "claim_token": {
      "type": "string"
    },
    "claim_expires_at": {
      "type": "string"
    },
    "quota": {
      "type": "object",
      "properties": {
        "used": {
          "type": "number"
        },
        "limit": {
          "type": "number"
        },
        "resets_at": {
          "type": "string"
        }
      },
      "required": [
        "used",
        "limit",
        "resets_at"
      ],
      "additionalProperties": false
    },
    "validation": {
      "type": "object",
      "properties": {
        "ok": {
          "type": "boolean"
        },
        "issues": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string"
              },
              "severity": {
                "type": "string",
                "enum": [
                  "error",
                  "warning"
                ]
              },
              "index": {
                "description": "Index of the note in the input, when the issue is about one note.",
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              },
              "message": {
                "type": "string"
              },
              "suggestions": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            },
            "required": [
              "code",
              "severity",
              "message"
            ],
            "additionalProperties": false
          }
        },
        "stats": {
          "type": "object",
          "properties": {
            "note_count": {
              "type": "integer",
              "minimum": -9007199254740991,
              "maximum": 9007199254740991
            },
            "illegal_count": {
              "type": "integer",
              "minimum": -9007199254740991,
              "maximum": 9007199254740991
            },
            "duration_seconds": {
              "type": "number"
            },
            "strip_length_cm": {
              "type": "number"
            }
          },
          "required": [
            "note_count",
            "illegal_count",
            "duration_seconds"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "ok",
        "issues",
        "stats"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "song_id",
    "box",
    "private",
    "saved_to_account",
    "quota",
    "validation"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

Saves a melody as the version of an existing song for one box (a song can have one version per box: 15, 20, 30 notes or freestyle). Replaces that box's version if it exists. Works on the signed-in person's songs, or on a song saved without an account if you pass its claim_token. The melody must have no errors.

{
  "type": "object",
  "properties": {
    "song_id": {
      "type": "string",
      "maxLength": 40
    },
    "claim_token": {
      "description": "Only for songs saved without an account.",
      "type": "string",
      "maxLength": 100
    },
    "box": {
      "type": "string",
      "enum": [
        "15",
        "20",
        "30",
        "freestyle"
      ],
      "description": "Music box type: \"15\", \"20\", \"30\" (notes) or \"freestyle\" (digital only). See list_music_boxes."
    },
    "bpm": {
      "type": "number",
      "minimum": 30,
      "maximum": 300,
      "description": "Tempo in beats per minute (30-300)."
    },
    "notes": {
      "minItems": 1,
      "maxItems": 2000,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "pitch": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 8
              },
              {
                "type": "integer",
                "minimum": 0,
                "maximum": 127
              }
            ],
            "description": "Note name like \"C5\", \"F#4\", \"Bb3\", or a MIDI number (60 = C4)."
          },
          "beat": {
            "description": "When the note sounds, in quarter notes from 0 (e.g. 0, 1, 1.5).",
            "type": "number",
            "minimum": 0
          },
          "ticks": {
            "description": "Alternative to beat: 192 ticks per quarter note.",
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991
          }
        },
        "required": [
          "pitch"
        ]
      },
      "description": "Notes in any order, at most 2000. Only onsets matter: music boxes have no note durations."
    },
    "illegal_threshold_ticks": {
      "description": "Minimum gap between two identical notes, in ticks (default 384 = 2 beats).",
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "song_id",
    "box",
    "bpm",
    "notes"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

{
  "type": "object",
  "properties": {
    "song_id": {
      "type": "string"
    },
    "box": {
      "type": "string"
    },
    "replaced": {
      "type": "boolean"
    },
    "composer_url": {
      "type": "string"
    },
    "validation": {
      "type": "object",
      "properties": {
        "ok": {
          "type": "boolean"
        },
        "issues": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string"
              },
              "severity": {
                "type": "string",
                "enum": [
                  "error",
                  "warning"
                ]
              },
              "index": {
                "description": "Index of the note in the input, when the issue is about one note.",
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              },
              "message": {
                "type": "string"
              },
              "suggestions": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            },
            "required": [
              "code",
              "severity",
              "message"
            ],
            "additionalProperties": false
          }
        },
        "stats": {
          "type": "object",
          "properties": {
            "note_count": {
              "type": "integer",
              "minimum": -9007199254740991,
              "maximum": 9007199254740991
            },
            "illegal_count": {
              "type": "integer",
              "minimum": -9007199254740991,
              "maximum": 9007199254740991
            },
            "duration_seconds": {
              "type": "number"
            },
            "strip_length_cm": {
              "type": "number"
            }
          },
          "required": [
            "note_count",
            "illegal_count",
            "duration_seconds"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "ok",
        "issues",
        "stats"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "song_id",
    "box",
    "replaced",
    "validation"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

Lists the signed-in person's songs on Musicboxmelodies, newest first, including private ones. Requires signing in.

{
  "type": "object",
  "properties": {
    "page": {
      "type": "integer",
      "minimum": 1,
      "maximum": 500
    },
    "page_size": {
      "description": "Default 20.",
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

{
  "type": "object",
  "properties": {
    "page": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "pages": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "total": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "songs": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "song_id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "artist": {
            "type": "string"
          },
          "private": {
            "type": "boolean"
          },
          "boxes": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "created": {
            "type": "string"
          },
          "url": {
            "type": "string"
          },
          "composer_url": {
            "type": "string"
          }
        },
        "required": [
          "song_id",
          "name",
          "artist",
          "private",
          "boxes",
          "created",
          "url",
          "composer_url"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "page",
    "pages",
    "total",
    "songs"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

Makes one of the signed-in person's songs public (anyone can find and play it on musicboxmelodies.com) or private. Only make a song public when the person asked for it: ask them to confirm, then call again with confirmed: true.

{
  "type": "object",
  "properties": {
    "song_id": {
      "type": "string",
      "maxLength": 40
    },
    "visibility": {
      "type": "string",
      "enum": [
        "public",
        "private"
      ]
    },
    "confirmed": {
      "description": "Required to make a song public: true only after the person confirmed.",
      "type": "boolean"
    }
  },
  "required": [
    "song_id",
    "visibility"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

{
  "type": "object",
  "properties": {
    "song_id": {
      "type": "string"
    },
    "visibility": {
      "type": "string"
    },
    "status": {
      "type": "string",
      "enum": [
        "updated",
        "needs_confirmation"
      ]
    },
    "url": {
      "type": "string"
    }
  },
  "required": [
    "song_id",
    "visibility",
    "status",
    "url"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

Creates a download link for one box version of a song: a MIDI file or a printable strip PDF to cut and punch for a hand-crank music box ("pdf_long" is one continuous strip, "pdf_a4"/"pdf_letter" are sliced to fit the page). Works on the person's songs and on public tunes. Requires signing in, like exporting in the composer.

{
  "type": "object",
  "properties": {
    "song_id": {
      "type": "string",
      "maxLength": 40
    },
    "box": {
      "description": "Which version. Defaults to the preferred one.",
      "type": "string",
      "enum": [
        "15",
        "20",
        "30",
        "freestyle"
      ]
    },
    "format": {
      "type": "string",
      "enum": [
        "midi",
        "pdf_long",
        "pdf_a4",
        "pdf_letter"
      ]
    },
    "strip_shape": {
      "description": "Shape of the strip ends (PDF only). Default capped.",
      "type": "string",
      "enum": [
        "capped",
        "straight",
        "pointy",
        "round"
      ]
    },
    "grid": {
      "description": "Grid printed on the strip (PDF only). Default standard.",
      "type": "string",
      "enum": [
        "standard",
        "note_lines",
        "tempo_lines",
        "empty"
      ]
    },
    "show_title": {
      "description": "Print the song title on the strip (PDF only). Default true.",
      "type": "boolean"
    }
  },
  "required": [
    "song_id",
    "format"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

{
  "type": "object",
  "properties": {
    "song_id": {
      "type": "string"
    },
    "box": {
      "type": "string"
    },
    "format": {
      "type": "string"
    },
    "download_url": {
      "type": "string"
    }
  },
  "required": [
    "song_id",
    "box",
    "format",
    "download_url"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

Converts a MIDI file (base64, up to 512 KB) into the melody format and validates it for a box, so you can fit, edit and save it. Drums are ignored. Saves nothing.

{
  "type": "object",
  "properties": {
    "midi_base64": {
      "type": "string",
      "minLength": 8,
      "maxLength": 699056,
      "description": "The .mid file, base64-encoded."
    },
    "box": {
      "description": "Box to validate against. Default \"30\".",
      "type": "string",
      "enum": [
        "15",
        "20",
        "30",
        "freestyle"
      ]
    }
  },
  "required": [
    "midi_base64"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string"
    },
    "notes_in_file": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "skipped_percussion_tracks": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "melody": {
      "type": "object",
      "properties": {
        "box": {
          "type": "string"
        },
        "bpm": {
          "type": "number"
        },
        "notes": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "pitch": {
                "type": [
                  "string",
                  "number"
                ]
              },
              "beat": {
                "type": "number"
              },
              "ticks": {
                "type": "number"
              }
            },
            "required": [
              "pitch"
            ],
            "additionalProperties": false
          }
        }
      },
      "required": [
        "box",
        "bpm",
        "notes"
      ],
      "additionalProperties": false
    },
    "validation": {
      "type": "object",
      "properties": {
        "ok": {
          "type": "boolean"
        },
        "issues": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string"
              },
              "severity": {
                "type": "string",
                "enum": [
                  "error",
                  "warning"
                ]
              },
              "index": {
                "description": "Index of the note in the input, when the issue is about one note.",
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              },
              "message": {
                "type": "string"
              },
              "suggestions": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            },
            "required": [
              "code",
              "severity",
              "message"
            ],
            "additionalProperties": false
          }
        },
        "stats": {
          "type": "object",
          "properties": {
            "note_count": {
              "type": "integer",
              "minimum": -9007199254740991,
              "maximum": 9007199254740991
            },
            "illegal_count": {
              "type": "integer",
              "minimum": -9007199254740991,
              "maximum": 9007199254740991
            },
            "duration_seconds": {
              "type": "number"
            },
            "strip_length_cm": {
              "type": "number"
            }
          },
          "required": [
            "note_count",
            "illegal_count",
            "duration_seconds"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "ok",
        "issues",
        "stats"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "name",
    "notes_in_file",
    "skipped_percussion_tracks",
    "melody",
    "validation"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}