Rows and settings

The inside of a stem is rows and settings. Rows say what plays and settings say how it sounds. This page teaches enough of both to read any track Songcode writes and to change one with confidence. The song format covers the track around the stems.

#Read one stem

stem hats: club {
  hat      [xxxx xxxx xxxx xxxx]
  velocity [100 40 65 45]
  chance   88%
  highpass 420hz
}

To change it: swap hat for openhat, thin the row to [x.x. x.x. x.x. x.x.], change the kit name, or move the filter. Press update to hear it.

#Step grids

A step grid is the row a drum machine shows. One character is one step, and spaces only group the steps so you can count them.

The number of steps in a bar sets the note value. In 4/4, 16 steps are 16th notes, 8 are 8ths, 12 are triplets, 4 are quarters and 1 is the whole bar.

stem drums: live {
  kick  [x... ..x. x... ....]
  snare [.... x... .... x..o | .o.. x... ..o. x...]
  hat   [x.xx x.x. xxxx x.22]
}

• | ends a bar. A row one bar long repeats every bar, and a row two bars long repeats every two.
• On a drum kit each row is a lane, named for its drum: kick, snare, clap, hat, openhat, rim, cowbell, lowtom, midtom, hightom, crash, ride, shaker and tambourine.
• A closed hat cuts an open hat on the same kit.
• Every group in a bar is the same size. A group of three among fours is an error.

In an odd meter the steps group the way the meter’s beats do:

meter 7/8, beats: 2+2+3

stem kick: club {
  kick [x. .. x..]
}

#Pitch rows

A part that repeats, such as a bassline, a stab, a pad or an arpeggio, keeps its rhythm and its pitches in two rows. The rhythm is a step grid called rhythm. The pitch row beside it is read hit by hit: the first pitch goes to the first hit.

stem lead: sawlead {
  rhythm  [x.x. x.x. x-x. x... | x.x. x.x. x--- ....]
  degrees [1 3 5 7 5 3 4       | 1 3 5 8 7]
  octave  4
}

• A bar holds one pitch, used for every hit in it, or exactly as many pitches as it has hits.
• Pitches joined with + sound together: c3+eb3+g3, or tones [2+3+4] for a chord without its root.
• A ~ after a pitch slides into the next note.
• octave says where degrees and tones sit.

Keeping the two rows apart means you can change the groove without touching the tune. A bass written as tones [root] follows the chord chart and never names a note, so changing a chord in the chart moves the bass with it.

#Lines

A line carries rhythm and pitch together. Melodies are written this way, and so is anything that does not repeat on a grid.

stem melody: nylon {
  line [mp c4/4 d4/8 e4 f4/4. g4/8 | a4/2 r/4 b4 | < c5/4 b4/8 a4 g4/4 e4 | f d4/1]
}

Every bar adds up to the meter. A bar that is short or long is an error that names the line, the bar and both totals.

#Ornaments

An ornament follows its note after a colon, one to a note.

stem fiddle: violin {
  line [(d5/8 e5 f#5 g5) a5/4:trill b5/g a5/4 | (g5/8 f#5) e5/4:turn d5/2:fall]
}

In the stems view an ornament is one note with its mark, the way it is written, and a slur is the notes it joins. Editing the notes there writes the same marks back into the code.

#Ways of playing

Some recorded instruments were recorded played more than one way. A word between notes picks one, and it holds until the next word:

stem cello: cello {
  line [pizz c3/4 g3 e3 g3 | arco (c3/2 d3) | e3/1]
}

technique pizzicato as a setting does the same for the whole stem, or for a section inside a block. Sounds lists which instruments have which ways. Asking for one an instrument does not have is an error that names the ones it has. Pizzicato, spiccato, staccato and marcato notes are short, so a slur does not join them.

#Styles of playing

A style is what the player does with a note, so it needs no recording of its own. Each has its name from the score and a plain word, and both work everywhere:

stem violins: violins {
  line [stacc c5/8 d5 e5 f5 marc g5/4 g5 | ten a5/2 port g5/4 f5 | arco (e5/2 d5) | c5/1]
}

stem riff: crunch_guitar {
  line [short e3/8 e3 e3 e3 punch g3/4 a3 | held e3/1]
}

On bowed strings, winds, brass and choirs a style sets the whole shape of the note: how it starts, whether it holds or drops back, and how it ends. On every other pitched instrument it sets how long the note sounds and, for punch, how hard it is hit. The ' mark on a note is one staccato note and _ is one tenuto note, whatever style stands. technique marcato sets a style for the whole stem or a section. Code written in the stems view comes back with the score names.

Two lines in one stem sound together as two voices, which is how a piano gets two hands:

stem piano: epiano {
  line [e4/4 g4 c5/2 | d5/4 b4 g4/2]
  line [c3/2 g2 | g2/2 b2]
}

#Themes

A melody that comes back gets a name. let names a line above the stems, and any line can then quote it among its notes: as it is, or changed.

key a minor
let theme = line [a4/4 b4/8 c5 e5/4. d5/8 | c5/2 a4/2]

stem lead: sawlead {
  line [theme | theme(up 2) | theme(first 1bar) e5/2 d5 | c5/1]
}

That line is six bars: the theme, the theme a third higher, its first bar, and two bars of new notes. The changes go in ( ) after the name.

• A quote takes the room its notes take and brings its own bar lines. A two-bar theme fills two bars wherever it starts, and a note that would cross a bar line is carried over it, tied.
• A short theme sits among other notes: [motif motif(up 1) g4/2]. The bar still has to add up.
• up and down count in the key of the section the line is written for, so a section with its own key moves the theme inside that key.
• A theme carries its dynamics with it. reversed leaves them behind.
• A theme may quote another theme. A name cannot look like a note or a dynamic: not c4, r, p or mf.
• An accompaniment figure is a theme too. let figure = line [c3/8 g3 e3 g3 c3 g3 e3 g3], and figure(up 3) is the same figure on the fourth degree of the key.

A stem whose line quotes a theme is code in the stems view: edit notes turns the quotes into the notes they play.

#Settings

A setting is a word and a value with its unit. The unit is part of the value, so 400hz cannot be read as bars, seconds or an amount.

#Notes

#Envelope

A short decay with sustain 0% is a pluck. A long attack and release is a pad.

#Filter

#Tone

#Tone controls

Each needs its gain, and a stem takes one of each.

#Dirt and space

#Moves

Level and pan are not stem settings. They live in the mix table: a row for the track, and blocks there for the parts where they change. Swing is the track’s. A stem that sets any of them is an error that says where it goes.

#Lists

Two settings can take a list in place of one value: velocity and take. The list is read hit by hit and loops, like a pitch row.

stem bass: sawtooth {
  rhythm   [xxxx xxxx xxxx xxxx]
  tones    [root]
  octave   1
  velocity [110 60 85 60]
}

stem perc: conga {
  rhythm [..x. .x.. ..x. .x.x]
  take   [0 2 1 3]
}

• velocity [110 60 85 60] on 16th notes is an accent on every beat.
• take [0 2 1 3] plays a different recording of the conga on each hit: an open tone, a slap, a mute. Recorded percussion, the textures, the ambience beds and the live and rock kits have several takes. Every other kit has one, and take on it raises a warning. The rock kit picks a take by itself from how hard a hit is played, so a ghost note (o) is a soft recording and an accent (X) a hard one; take overrides that.
• A list that is shorter than the bar goes round again, so three values against four hits land somewhere new each bar.
• On a drum kit, a list is read for each lane on its own.
• A list may carry | to line up with the rhythm’s bars.

Every other setting takes one value. To move a filter over time, use ramp or sweep, below.

#Values that move

A value can move over time. Two calls cover it:

stem pad: ensemble {
  rhythm  [x]
  tones   [all]
  lowpass sweep(600hz, 2.5khz, every: 8bars)
  in break {
    lowpass ramp(500hz, 6khz)
  }
  last 1bar into peak {
    highpass ramp(240hz, 2khz)
  }
}

A ramp inside in break runs across the break. A ramp inside last 1bar into peak runs across that one bar. You never work out how long it lasts.

A filter that moves runs smoothly, through held notes too, so one long chord can open across a whole section. A crescendo or diminuendo in a line swells through a held note the same way. Level and pan do as well: fade, a trim or pan that moves, and every move in the mix table. Any other effect (reverb, delay, drive) takes its value at the moment each note starts.

#Swing and feel

swing 58%

stem snare: live {
  snare  [.... x... .... x..o]
  behind 8ms
}

stem hats: live {
  hat      [x.xo x.xo x.xo x.22]
  velocity [100 70 30 85]
  ahead    4ms
}

stem arp: synthpluck {
  rhythm [x.x. x.x. x.x. x.x.]
  tones  [1 2 3 2 1 2 3 2]
  straight
}

• Swing is one number for the whole track. 50% is straight and 66% is a full triplet. It runs from 50% to 75% and delays every second 16th note.
• It applies to every stem. No stem sets its own amount. A stem that must stay rigid says straight.
• swing 66% 8ths swings the 8th notes, the way jazz and shuffles do.
• behind and ahead drag one stem a few milliseconds late or push it early. Neither goes past 30ms.
• Timing is exact unless the track says loose. loose 8ms at the top of a track lets every note land up to 8 ms early or late, most of them close to the grid and a few further out. A stem can set its own amount, and loose 0ms puts one stem back on the grid. It stops at 30ms. humanize varies loudness only, and chance only drops hits.
• loose moves what you hear, not what is written. The piano roll and the code still show each note on its step.
• loose comes last. It is added after swing and after behind or ahead, so a stem that is behind 20ms with loose 10ms lands 10 to 30 ms late. With both at their limits a note can be 60 ms from its step.
• The same seed gives the same looseness. Every play, every audio export and every MIDI export of a track has each note in the same place.
• Accents carry the groove. X, x and o in a grid and a velocity list are where most of a track’s feel is written.
• A digit is a roll. 2222 at the end of a bar or x.33 in a hat row.

Swing wants to be heavier at slow tempos and lighter at fast ones. The app warns when a track’s swing is heavy for its tempo, and the track still plays:

line 3: swing 70% is heavy at 120 bpm: 16ths this fast usually sit at 54 to 58%

#Recordings that sound played

A recorded instrument never plays two notes exactly alike. The app does this on its own, for every recorded sound:

• It rotates recordings. The rock kit has up to four recordings of every drum at every strength, the electric bass four of every note, the power chords two and the palm mutes three. Each note takes the next one.
• It borrows a neighbour. An instrument with one recording of each note plays a repeated note from the recording next to it, retuned, every other time.
• Level and tuning stray a little. Each note is up to 0.7 dB louder or quieter than written (1 dB on the rock kit) and up to 3 cents sharp or flat.
• Soft notes are darker. A pitched recording played under full velocity loses some of its top, the way an instrument does when played gently.

• A bow or a breath shapes each note. A bowed string, a wind, a brass instrument or a choir swells into a note and sinks away before the next, fast when the note is loud and slow when it is soft. bow and breath set it by hand, a style of playing replaces the shape with its own, and notes under a slur cross over with no gap.

vary on a stem scales the first four. vary 0% turns them off and plays every note as recorded. vary 200% doubles the strays. Synthesised sounds are not touched. The pattern of strays does not come from the seed: it is fixed, so an export sounds the same every time. vary changes sound only, so it is not in a MIDI export.

#Played by a person

A stem on a real instrument (a piano, a guitar, a violin, a trumpet, the live and rock kits) is checked against what one person could play on it. Synths, drum machines and found sounds are not.

How the check thinks about each instrument:

• Every stem on one keyboard, harp or kit is one player. A piano split into a right-hand and a left-hand stem has two hands between them, five fingers each, each hand within a 10th.
• A guitar has one note per string, and a chord is a shape the fretting hand holds within five frets, with a barre. Basses are the same on four strings.
• A bowed string sustains two notes on neighbouring strings. Three or four are struck short.
• A drummer has two hands, the right foot on the kick and the left foot on the hi-hat pedal or a second kick pedal. A closed hat that the hands have no room for is the foot, as the jazz hat on 2 and 4 is. A crash takes the place of the hat on its beat, and a fill takes the hands off the hats.

A problem is an error with its place in the song, and the stem still plays. When it is meant (a piano with three hands, a flute that never breathes), write allow with the rules it breaks at the top of the stem:

stem lead: flute {
  allow breath
  line [c5/1 | d5/1 | e5/1 | f5/1]
}

allow range, speed on its own line at the top of a track covers every stem, and allow all waives all five.

#Chance and the seed

chance, humanize and loose draw from the track’s seed. The same seed gives the same track, so the same hits drop on every play and an export matches what you heard. Change seed 7 to seed 8 and a different set of hits drops.

#Edits worth trying first

If an edit breaks a stem, the status line says which line and why. That stem falls silent and the other stems keep playing. If nothing in the new code can play, the last working version carries on. See errors.