Write songs with an AI agent

A PIKOTO project is one plain text file, a .pikoto, in JSON. Anything that can write a file can write a song: you, a script, or an AI agent. Give an agent this page and an idea, and it can arrange all sixteen patterns, every lock and every effect, and hand you a song to open, play and change.

How it works

1. Unlock PIKOTO. Importing and exporting project files are part of the unlock.
2. Brief an agent. One that can write and run code does this best. Give it this page's address, the DEMO, and your idea. There's a brief to copy below.
3. Import the song. Open ≡, tap the project name, then IMPORT and pick the file. It opens as a new project and replaces nothing. On iPhone and iPad, tapping a .pikoto in Files, AirDrop or Mail does the same.
4. Listen and steer. Press ▶. With CHAIN on, the whole song plays through. The agent can't hear it, so tell it what you hear: the bass disappears on the phone speaker, the hats are too busy in P03, the break needs to drop out harder.
5. Keep going together. Change things in the app, then EXPORT from the same projects list and give the agent that file, so its next version starts from yours.

The brief

Paste this into your agent and fill in the brackets:

Read https://pikoto.app/songs and follow it.
Start from the DEMO at https://pikoto.app/songs/DEMO.pikoto
and the sounds at https://pikoto.app/songs/sounds.json.

Write a PIKOTO song: [style and mood], [tempo] BPM, about [length],
in [key and scale]. Instruments: [kick, bass, keys, lead...].
Arrangement: [intro, verse, chorus, break, outro...].

Build it with a script, check it against the checklist on the page,
and give me the .pikoto file and a short map of each pattern.

Some ideas to start from:

• A two-minute lo-fi piece in D minor at 84 BPM, swung, with a kalimba melody that changes every time round and soft, dusty drums.
• Techno at 128 that builds with filter locks and a riser, stutters with REPEAT before the drop, and ends on BRAKE.
• An ambient piece of slow chords through the arpeggiator, with long reverb, grain and a SLOPE on the filter.
• My exported project: keep the first three patterns and write a break, a last chorus and an outro.

For agents

PIKOTO is an FM groovebox. It has four tracks, and each plays one four-operator FM sound. A project holds sixteen patterns; each has its own four sounds, tempo, swing and up to 64 steps per track. A chain plays patterns in order, and that is the song.

1. Read the DEMO. Download DEMO.pikoto and look at how it's built: six patterns, a chain of [0, 1, 1, 2, 3, 4, 4, 5], chords on track 4, and hats, clap, rim and shaker played on the snare track through sound locks.
2. Write a script, not the JSON. A song is thousands of steps. Write a program in Python or JavaScript that builds the project from functions like drums(pattern, style) and chord(step, notes, length), and writes the file. Changes are then a line, not a rewrite.
3. Start sounds from the factory. Take sounds from sounds.json (each entry's patch) or the DEMO's patches, and change a few parameters. Sound designed from defaults usually sounds thin.
4. Check, then hand over. Run the checklist in your script. Name the file after the song, like NIGHT_DRIVE.pikoto.
5. Explain it. Tell the human what each pattern is and what the chain does, so they can ask for changes by pattern: P05 is the drop.

You can't hear the result. Lean on what's known to work: the DEMO's levels, factory sounds, kick on track 1, three-note chords. Then ask the human what to change.

The file

One JSON object. Everything but patterns can be left out, and anything left out takes its default: missing patterns, tracks and steps are empty, missing parameters take their defaults. Here is the shape, cut short:

{
  "name": "NIGHT DRIVE",
  "version": 1,
  "chain": [0, 1, 1, 2],
  "chainOn": true,
  "activePattern": 0,
  "fx": { "params": { "Delay Time": 8, "Reverb Size": 0.7, "Master Duck": 0.25 } },
  "soundPool": [
    { "name": "HIHAT CL", "chromatic": true, "params": { "Algorithm": 3, ... } }
  ],
  "patterns": [
    {
      "tempo": 118,
      "swing": 0.12,
      "scale": 2,
      "key": 9,
      "patches": [ {KICK 808}, {SNARE}, {FM BASS}, {E PIANO} ],
      "tracks": [
        {
          "length": 64,
          "speed": 1,
          "defaultNote": 60,
          "steps": [
            { "active": true, "notes": [60], "velocity": 0.9, "length": 1 },
            { "active": false },
            { "active": true, "notes": [60], "micro": 0.04, "ratchet": 2,
              "condition": 5, "locks": { "41": 0.62, "64": 0.4 } },
            { "active": true, "sound": 0, "velocity": 0.5 }
          ]
        }
      ]
    }
  ]
}

Project

Pattern

Track

Step

Sound

A sound in patches or soundPool is {"name": "WARM PAD", "chromatic": false, "params": {...}}. The params are named as in the sound parameters. chromatic is true for drums: the pads stay a chromatic keyboard for it whatever the scale. Keep names short and in capitals.

What makes a file fail

• Not a JSON object, or no patterns list: NOT A PIKOTO PROJECT.
• A wrong type anywhere. Notes, lengths of tracks, ratchets, conditions, keys, scales, sound indices, defaultNote, transpose, activePattern and chain entries are whole numbers: 60.0 reads, 60.5 fails the file. punches are whole numbers 0 to 65535. active, chainOn and the others are true or false, not 1 or 0.
• A lock keyed by name. Lock keys are the numbers from the table: "41", not "Cutoff".
• A version above 1.
• A file over 16 MB. A whole song is well under 1 MB.

Each of these is refused with NOT A PIKOTO PROJECT, except the version (UPDATE PIKOTO TO OPEN IT) and the size (FILE TOO BIG).

Everything else opens without a word, so a mistake plays wrong rather than failing:

• Values out of range are clamped, so a cutoff of 800 meant as hertz plays as fully open. Stepped parameters are rounded to whole numbers. Check your units against the reference.
• Names are exact and case-sensitive. A field, sound parameter or effect parameter the app doesn't know is ignored, and the parameter keeps its default: "cutoff" or "note" does nothing. So does a lock key that isn't a parameter, such as "99".
• Notes outside 0 to 127 are dropped, and a step with more than four keeps the last four. Chain entries outside 0 to 15 are dropped.
• A condition above 19 plays always. A sound past the end of soundPool plays the track's own sound. A speed snaps to the nearest of the five.

Tips

What makes a PIKOTO song sound finished, and how to write it in the file.

Arrange with patterns and the chain

Write each section as a pattern: intro, verse, chorus, break, outro. At speed 1 a 64-step track is four bars, and the chain repeats a pattern by naming it twice. Change a pattern's patches to bring in new instruments, as the DEMO does with STRINGS in its fourth pattern. Thin out the drums before a drop, and bring them back all at once.

Lock parameters on steps

Locks are what make a loop move. Open the filter over sixteen steps (41, Cutoff), shorten the decay on off-beat hats (49, Amp Decay), brighten one chord with a modulator's level (18, Op 2 Level), or throw one snare into the delay (64, Delay Send). A lock trig, a step with locks and lockTrig but no note, moves a held pad or bass note without playing it again.

Track parameters (the LFOs, SLOPE, the arp, chord, voice mode, unison and width) hold a lock until the next trig on that track, and a trig without the lock puts them back. For a whole section, set them in the pattern's sound instead.

Micro-timing and velocity

Straight steps sound like a machine, which is sometimes the point. For a groove, play the snare a little late (micro 0.03 to 0.08), push ghost notes and some hats early, and vary hat velocity in a pattern rather than at random. The DEMO plays its claps 0.04 late and pulls a few chords 0.04 early. A ratchet of 2 to 4 rolls a hat or snare into the next bar.

The master compressor evens out velocity, so halving it across a section barely changes its level. For dynamics, change the arrangement or lock Volume (55).

Variation with conditions

One pattern can play differently every time round. Conditions count the loops of the step's own track, from when the pattern starts: 1:2 and 2:2 alternate, 1:4 to 4:4 take turns in four, 1ST plays only on the first loop, and 25% or 50% make ghost notes that come and go.

On a track as long as the pattern's longest, a loop is a pass of the pattern. There 1:2 and 2:2 give the pattern two endings, 1ST is a crash at the start of a section, and a chain that names the pattern twice in a row keeps counting, so 1:2 and 2:2 tell the two passes apart. A shorter track counts its own loops: a 16-step track in a 64-step pattern goes round four times a pass, so its 1:2 and 2:2 alternate every bar, and its 1ST plays only in the first bar. Give a track the pattern's full length when its conditions should follow the song.

FILL steps play only while the player has FILL on, so write some for them to perform.

Chords and the arpeggiator

A step plays up to four notes. Three-note voicings with a long length make pads; the Chord parameter stacks intervals on one note. Sixteen voices are shared by all four tracks, and a four-note chord with a long release holds eight while it overlaps the next one. The Chord parameter takes a voice for each interval it adds, and Voice Mode UNISON two for every note, so four notes with Chord MIN7 already take all sixteen.

For an arpeggio, set Arp Mode in the track's sound (1 to 5) with Arp On Trigs at 1, and give it chord trigs with a long length: the arp plays the chord for as long as the trig lasts. Arp Speed, Range and Gate shape it. Lock Arp Mode to 0 on one trig to play that chord straight.

More sounds than tracks

Put extra sounds in soundPool and set sound on a step to play one there. The DEMO plays hats, clap, rim and shaker on its snare track this way, and a kalimba between the chords on its keys track. A sound-locked step keeps the track's LFOs, SLOPE, arp and voice mode.

Polymeter and speed

Tracks of different lengths drift against each other: a 12-step percussion line over a 16-step beat lines up again every three bars. Speed 2 makes 32nd-note hats, 0.5 a slow bass line with room for long notes.

Modulation

Each track has two LFOs and a SLOPE. Point a destination at a parameter and set a depth: a slow LFO on Cutoff breathes a pad, a fast one on PITCH is vibrato. SLOPE in ENV mode is a shaped rise and fall on each note, and SYNC ties it to the tempo.

Effects

Delay, reverb and grain are shared; each sound sends to them. Keep kick and bass dry, give keys and leads some reverb, and lock sends on single steps for throws. Delay Time is in note divisions, so echoes stay in time. Master Duck pumps the mix under track 1, so put the kick there. Grain turns whatever is sent to it into a cloud, good on pads and in breaks.

FX pads

The sixteen FX pads can be written into a pattern as if a player held them. A track's punches holds one bitmask per step of that track; a pattern's holds one per sixteenth for every track at once. A pad is held while the clock is on a step with its bit, so set the bit on each step it should last.

REPEAT 1 or 2 on the last beat before a drop, ROLL on a snare build, REVERSE for half a bar, FILTER LOW on an intro, DELAY or REVERB on a last chord, CUT for a gap, and BRAKE on the last bar of the song.

Mix for phone speakers

KICK 808 and FM BASS play two octaves down, so note 60 sounds as C2, and KALIMBA one octave up. Bass notes under about 55 disappear on phone speakers. An intro, break or outro should sit a little under the main sections. Leave Master Volume near the DEMO's 0.8.

Checklist

For agents, before handing a file over. Check it in your script:

1. It parses as JSON, has "version": 1 and a patterns list of at most 16.
2. Whole numbers and booleans are written as such, with no fractions or 0 and 1 for true and false.
3. Every lock key is in the table, and every value is in the file's range: 0 to 1 for cutoff and times, not hertz or milliseconds.
4. Steps have at most four notes, 0 to 127. Every sound is less than the length of soundPool.
5. Track lengths are what you meant, and the chain plays every section, with chainOn true.
6. Every pattern has the same tempo, unless the song changes it on purpose.
7. No moment needs more than 16 voices: count the notes sounding at once, releases included, with each note's Chord intervals and twice for UNISON.
8. The kick is on track 1, and every pattern in the chain has its four patches.

Reference

Conditions

The values of a step's condition. A:B plays on loop A of every B, counting the loops of the step's own track (see variation with conditions).

0 ALL (always) ·1 FILL · 2 !FILL (not with FILL) · 3 1ST (first loop only) · 4 !1ST (never the first) · 5 1:2 · 6 2:2 · 7 1:3 · 8 2:3 · 9 3:3 · 10 1:4 · 11 2:4 · 12 3:4 · 13 4:4 · 14 1:8 · 15 10% · 16 25% · 17 50% · 18 75% · 19 90%

Scales

The values of a pattern's scale. Keys are 0 C, 1 C#, 2 D, and so on to 11 B.

0 chromatic · 1 major · 2 minor · 3 dorian · 4 phrygian · 5 lydian · 6 mixolydian · 7 locrian · 8 harmonic minor · 9 major pentatonic · 10 minor pentatonic · 11 blues · 12 whole tone · 13 hirajoshi · 14 in sen

FX pad bits

Add the values of the pads to hold together: 4096 + 16 is DELAY with HALF SPEED. The first eight bend timing, the last eight the sound.

1 REPEAT 1 STEP · 2 REPEAT 2 STEPS · 4 REPEAT 4 STEPS · 8 ROLL 1/32 · 16 HALF SPEED · 32 DOUBLE SPEED · 64 REVERSE · 128 RANDOM STEPS · 256 FILTER LOW · 512 FILTER HIGH · 1024 OCTAVE DOWN · 2048 OCTAVE UP · 4096 DELAY SEND · 8192 REVERB SEND · 16384 CUT · 32768 BRAKE

Chord parameter

The intervals the Chord parameter adds to each note, in semitones.

0 OFF · 1 OCT +12 · 2 5TH +7 · 3 OCT5 +7 +12 · 4 MIN +3 +7 · 5 MAJ +4 +7 · 6 SUS4 +5 +7 · 7 MIN7 +3 +7 +10 · 8 MAJ7 +4 +7 +11 · 9 STACK +12 +19 +24

Sound parameters

A sound's params and a step's locks. Locks use the key, sounds the name. Values are what the file holds, not what the screen shows. Track marks the parameters a track reads once rather than per note: a lock on one holds until the next trig on that track.

Effect parameters

The project's fx.params: the delay, reverb and grain every track sends to, and the master. They can't be locked.

Modulation destinations

The values of LFO 1 Dest, LFO 2 Dest and Slope Dest. A depth of 1 or -1 sweeps the destination across its whole range, and PITCH by 12 semitones.

0 OFF · 1 PITCH · 2 ALGO ALGO · 3 ALGO FDBK · 4 ALGO HARM · 5 ALGO DTUN · 6 ALGO PENV · 7 ALGO PDEC · 8 ALGO CHRD · 9 ALGO CLIK · 10 OP1 RAT · 11 OP1 FINE · 12 OP1 LEV · 13 OP1 WAVE · 14 OP1 ATK · 15 OP1 DEC · 16 OP1 SUS · 17 OP1 REL · 18 OP2 RAT · 19 OP2 FINE · 20 OP2 LEV · 21 OP2 WAVE · 22 OP2 ATK · 23 OP2 DEC · 24 OP2 SUS · 25 OP2 REL · 26 OP3 RAT · 27 OP3 FINE · 28 OP3 LEV · 29 OP3 WAVE · 30 OP3 ATK · 31 OP3 DEC · 32 OP3 SUS · 33 OP3 REL · 34 OP4 RAT · 35 OP4 FINE · 36 OP4 LEV · 37 OP4 WAVE · 38 OP4 ATK · 39 OP4 DEC · 40 OP4 SUS · 41 OP4 REL · 42 FLTR TYPE · 43 FLTR FREQ · 44 FLTR RESO · 45 FLTR ENV · 46 FLTR ATK · 47 FLTR DEC · 48 FLTR SUS · 49 FLTR REL · 50 AMP ATK · 51 AMP DEC · 52 AMP SUS · 53 AMP REL · 54 AMP VEL · 55 AMP PAN · 56 AMP DRIV · 57 AMP VOL · 58 FX DLY · 59 FX REV · 60 FX GRN · 61 FX MODE · 62 FX GLID · 63 FX OCT · 64 FX UDET · 65 FX WIDE

Operator ratios

An operator's Ratio is an index into this list: 3 is ×1, the note itself.

0 ×0.25 · 1 ×0.5 · 2 ×0.75 · 3 ×1 · 4 ×1.5 · 5 ×2 · 6 ×2.5 · 7 ×3 · 8 ×3.5 · 9 ×4 · 10 ×4.5 · 11 ×5 · 12 ×5.5 · 13 ×6 · 14 ×6.5 · 15 ×7 · 16 ×7.5 · 17 ×8 · 18 ×8.5 · 19 ×9 · 20 ×9.5 · 21 ×10 · 22 ×10.5 · 23 ×11 · 24 ×11.5 · 25 ×12 · 26 ×12.5 · 27 ×13 · 28 ×13.5 · 29 ×14 · 30 ×14.5 · 31 ×15 · 32 ×15.5 · 33 ×16 · 34 ×18 · 35 ×20 · 36 ×24 · 37 ×32

Curves

Times, frequencies and rates are stored as 0 … 1 and mapped like this:

To go the other way: v = log₁₀(seconds / 0.001) / 4 for a time, and v = log₁₀(hertz / 20) / 3 for a frequency.