{"name":"clef.im","about":"clef.im renders public-domain scores as notation, plays them back, and synthesizes them to 16-bit PCM WAV on the server. It also generates random rhythm snippets and renders any score you POST to it.","notation":{"summary":"A melody is a space-separated list of tokens. Each token is Pitch/beats, or r/beats for a rest.","beats":"`beats` is measured in quarter notes: 1 = quarter, 0.5 = eighth, 0.25 = sixteenth, 1.5 = dotted quarter, 2 = half. Omit `/beats` for a default quarter note.","pitches":"Pitches are scientific notation with # or b: C4 is middle C, so Bb3 and F#5 are valid.","chords":"Pitches joined with + sound simultaneously as a chord, sharing one duration and cursor step: C4+E4+G4/1 is a quarter-note C major triad.","tuplets":"Tuplets / triplets are written as decimal beats: 0.333333 for an eighth-note triplet (1/3 beat), 0.166667 for a sixteenth-note sextuplet (1/6 beat).","barlines":"`|` is ignored, so bar lines can be written for readability.","limits":"Max 512 sounding notes and 256 total beats per phrase. BPM is clamped to 40-240 (default 100).","example":"C5/1 D5/0.75 C5/0.25 | C4+E4+G4/1 A4/1 r/0.5 Bb4/0.5"},"endpoints":[{"method":"GET","path":"/api/tunes","summary":"The public-domain catalogue: every tune with its key, tempo, bar count and provenance.","returns":"application/json","example":"curl https://clef.im/api/tunes"},{"method":"GET","path":"/api/tunes/:id","summary":"One catalogue tune, with its notes and the source its transcription was checked against.","returns":"application/json","example":"curl https://clef.im/api/tunes/ode"},{"method":"GET","path":"/api/tunes/:id/score.svg","summary":"One catalogue tune as a standalone SVG score.","returns":"image/svg+xml","example":"curl https://clef.im/api/tunes/ode/score.svg"},{"method":"GET","path":"/api/tunes/:id/audio.wav","summary":"One catalogue tune, synthesized server-side with the accompaniment.","params":[{"name":"drums","description":"Set to 0 to drop the drum kit.","example":"0"},{"name":"bass","description":"Set to 0 to drop the bass line.","example":"0"},{"name":"pad","description":"Set to 0 to drop the pad.","example":"0"}],"returns":"audio/wav","example":"curl https://clef.im/api/tunes/ode/audio.wav -o ode.wav"},{"method":"POST","path":"/api/render","summary":"Render a score you supply. Echoes the canonical phrase back, so this is the cheapest way to check that your notes parsed the way you meant.","body":"{\n  \"notes\": \"C5/1 D5/0.75 C5/0.25 | C4+E4+G4/1 A4/1\",\n  \"bpm\": 108,\n  \"key\": \"F\",\n  \"timeSig\": [4, 4],\n  \"pickup\": 0\n}\n\nOnly `notes` is required. It is either a token string (see notation below) or an array of note objects. Optional fields: `id` (string), `title` (string), `bpm` (40-240, default 100), `timeSig` (array [beatsPerBar, beatUnit], default [4,4]), `key` (standard key string, default \"C\"), `pickup` (beats of anacrusis, default 0).\n\nArray shape for `notes`:\n[{ \"pitch\": \"C5\", \"dur\": 1, \"at\": 0, \"vel\": 0.85 }, { \"pitch\": \"D5\", \"dur\": 0.75 }]\nIn an object, only `pitch` is required (`midi` is derived, `at` falls back to the running cursor, `dur` to 1, `vel` to 0.85).\n\nCanonical Response (`application/json`):\n{\n  \"id\": \"render\",\n  \"title\": \"render\",\n  \"bpm\": 108,\n  \"timeSig\": [4, 4],\n  \"key\": \"F\",\n  \"pickup\": 0,\n  \"notes\": [\n    { \"pitch\": \"C5\", \"midi\": 72, \"dur\": 1, \"at\": 0, \"vel\": 0.85 },\n    { \"pitch\": \"D5\", \"midi\": 74, \"dur\": 0.75, \"at\": 1, \"vel\": 0.85 }\n  ]\n}","returns":"application/json","example":"curl -X POST https://clef.im/api/render -H \"content-type: application/json\" -d '{\"notes\":\"C5/1 D5/0.75 C5/0.25 A4/1 A4/1\",\"bpm\":108,\"key\":\"F\"}'"},{"method":"POST","path":"/api/render.wav","summary":"Synthesize a score you supply to 16-bit PCM WAV, with the accompaniment.","body":"{\n  \"notes\": \"C5/1 D5/0.75 C5/0.25 | C4+E4+G4/1 A4/1\",\n  \"bpm\": 108,\n  \"key\": \"F\",\n  \"timeSig\": [4, 4],\n  \"pickup\": 0\n}\n\nOnly `notes` is required. It is either a token string (see notation below) or an array of note objects. Optional fields: `id` (string), `title` (string), `bpm` (40-240, default 100), `timeSig` (array [beatsPerBar, beatUnit], default [4,4]), `key` (standard key string, default \"C\"), `pickup` (beats of anacrusis, default 0).\n\nArray shape for `notes`:\n[{ \"pitch\": \"C5\", \"dur\": 1, \"at\": 0, \"vel\": 0.85 }, { \"pitch\": \"D5\", \"dur\": 0.75 }]\nIn an object, only `pitch` is required (`midi` is derived, `at` falls back to the running cursor, `dur` to 1, `vel` to 0.85).\n\nCanonical Response (`application/json`):\n{\n  \"id\": \"render\",\n  \"title\": \"render\",\n  \"bpm\": 108,\n  \"timeSig\": [4, 4],\n  \"key\": \"F\",\n  \"pickup\": 0,\n  \"notes\": [\n    { \"pitch\": \"C5\", \"midi\": 72, \"dur\": 1, \"at\": 0, \"vel\": 0.85 },\n    { \"pitch\": \"D5\", \"midi\": 74, \"dur\": 0.75, \"at\": 1, \"vel\": 0.85 }\n  ]\n}","params":[{"name":"drums","description":"Set to 0 to drop the drum kit.","example":"0"},{"name":"bass","description":"Set to 0 to drop the bass line.","example":"0"},{"name":"pad","description":"Set to 0 to drop the pad.","example":"0"}],"returns":"audio/wav","example":"curl -X POST \"https://clef.im/api/render.wav?drums=0\" -H \"content-type: application/json\" -d '{\"notes\":\"C5/1 D5/0.75 C5/0.25 A4/1 A4/1\",\"bpm\":108,\"key\":\"F\"}' -o tune.wav"},{"method":"POST","path":"/api/render.svg","summary":"A score you supply, engraved as a standalone SVG.","body":"{\n  \"notes\": \"C5/1 D5/0.75 C5/0.25 | C4+E4+G4/1 A4/1\",\n  \"bpm\": 108,\n  \"key\": \"F\",\n  \"timeSig\": [4, 4],\n  \"pickup\": 0\n}\n\nOnly `notes` is required. It is either a token string (see notation below) or an array of note objects. Optional fields: `id` (string), `title` (string), `bpm` (40-240, default 100), `timeSig` (array [beatsPerBar, beatUnit], default [4,4]), `key` (standard key string, default \"C\"), `pickup` (beats of anacrusis, default 0).\n\nArray shape for `notes`:\n[{ \"pitch\": \"C5\", \"dur\": 1, \"at\": 0, \"vel\": 0.85 }, { \"pitch\": \"D5\", \"dur\": 0.75 }]\nIn an object, only `pitch` is required (`midi` is derived, `at` falls back to the running cursor, `dur` to 1, `vel` to 0.85).\n\nCanonical Response (`application/json`):\n{\n  \"id\": \"render\",\n  \"title\": \"render\",\n  \"bpm\": 108,\n  \"timeSig\": [4, 4],\n  \"key\": \"F\",\n  \"pickup\": 0,\n  \"notes\": [\n    { \"pitch\": \"C5\", \"midi\": 72, \"dur\": 1, \"at\": 0, \"vel\": 0.85 },\n    { \"pitch\": \"D5\", \"midi\": 74, \"dur\": 0.75, \"at\": 1, \"vel\": 0.85 }\n  ]\n}","returns":"image/svg+xml","example":"curl -X POST https://clef.im/api/render.svg -H \"content-type: application/json\" -d '{\"notes\":\"C5/1 D5/0.75 C5/0.25 A4/1 A4/1\"}'"},{"method":"GET","path":"/api/rhythm","summary":"A random but deterministic melody, for callers with no score of their own. Same seed always returns the same phrase.","params":[{"name":"seed","description":"Integer. Reproduces a previous phrase.","example":"42"},{"name":"bars","description":"Length in bars, 1-16 (default 8).","example":"4"},{"name":"key","description":"Key root, e.g. C, G, Bb, Eb (default C).","example":"G"},{"name":"bpm","description":"Tempo, 40-240 (default 96).","example":"120"}],"returns":"application/json","example":"curl 'https://clef.im/api/rhythm?seed=42&bars=4&key=G&bpm=120'"},{"method":"GET","path":"/api/rhythm.wav","summary":"The same generated phrase, synthesized server-side.","params":[{"name":"seed","description":"Integer. Reproduces a previous phrase.","example":"42"},{"name":"bars","description":"Length in bars, 1-16 (default 8).","example":"4"},{"name":"key","description":"Key root, e.g. C, G, Bb, Eb (default C).","example":"G"},{"name":"bpm","description":"Tempo, 40-240 (default 96).","example":"120"},{"name":"drums","description":"Set to 0 to drop the drum kit.","example":"0"},{"name":"bass","description":"Set to 0 to drop the bass line.","example":"0"},{"name":"pad","description":"Set to 0 to drop the pad.","example":"0"}],"returns":"audio/wav","example":"curl 'https://clef.im/api/rhythm.wav?seed=42&bars=8' -o rhythm.wav"},{"method":"GET","path":"/api/rhythm.svg","summary":"The same generated phrase, engraved as a standalone SVG.","params":[{"name":"seed","description":"Integer. Reproduces a previous phrase.","example":"42"},{"name":"bars","description":"Length in bars, 1-16 (default 8).","example":"4"},{"name":"key","description":"Key root, e.g. C, G, Bb, Eb (default C).","example":"G"},{"name":"bpm","description":"Tempo, 40-240 (default 96).","example":"120"}],"returns":"image/svg+xml","example":"curl 'https://clef.im/api/rhythm.svg?seed=42&bars=4'"}]}