# Songs

From A Little Lisp for a Small World, the Plazmi Lisp book (https://plazmi.gg/book). Checked against Plazmi Lisp version 13, 19 November 2026. The whole book as one file: https://plazmi.gg/book.md?rev=4d22859c86a27cff3b4c4ae5

A song is a value like any other: a map of facts and a list of sections, each section a number of bars and the parts that play through them. So a song can be written out by hand, or worked out by the functions of the earlier chapters. This chapter writes five, from a twelve-bar blues to one built with `map`.

## Writing a song down

A song is handed in whole with a command, `write song`, a name, and its Lisp. The name is one word, letters, numbers and dashes. The Lisp can run over many lines:

```clojure
write song twelve-bars
(song {:title "Twelve Bars" :style :greaser :key :a}
  (section :verse 12
    (chords :a :a :a :a :d :d :a :a :e :d :a :e)
    (band)))
```

```text
Wrote Twelve Bars (twelve-bars): greaser, 168 a minute, 0:17, with upright (bass), piano (vamp) and drums. songs lists yours; song twelve-bars says what's in it.
```

- `song` takes the facts first: `:title`, `:style`, `:key` (a chord: `:a`, `:am`, `:c`), and `:tempo` and `:meter` if the style's own won't do.
- `section` takes a name, a number of bars and its layers. `chords` gives one chord a bar, round and round; this one is the twelve-bar blues in A.
- `(band)` is the style's own players: for `:greaser`, drums, an upright bass and a piano. `song styles` lists every style and who plays in it.

`song twelve-bars` reads it back: its facts, its parts and its sections, and where its notes are for a page to play. Writing again under the same name replaces it, and `song twelve-bars source` shows the Lisp as you wrote it.

## Words to sing

`sing` sings words in your own voice. A `/` starts the next line; with no notes given, a tune is found for the words over the chords, the same every time:

```clojure
write song porch-song
(song {:title "Porch Song" :style :country :key :g}
  (section :intro 4 (chords :g :c) (band :only [:drums :bass]))
  (section :verse 8 (chords :g :c :d :g) (band)
    (sing "the lawn is ankle high / and nobody minds / the kettle is on / the porch light is kind")))
```

```text
Wrote Porch Song (porch-song): country, 104 a minute, 0:28, with upright (bass), banjo (riff), nylon (vamp), drums and voice. songs lists yours; song porch-song says what's in it.
```

`(band :only [:drums :bass])` lets in only some of the band; `(band :without [:drums])` leaves some out. Give notes as well and each syllable gets one: `(sing "o-ver the hill" "g4 a4 b4 d5")`.

## A dance number and the lights

A section can carry a dance: `(dance :clap [:twirl 2] :hop)` is danced by everyone on the floor together, on the song's beat, in the moves residents already know. `lights` gives the section its light cues; where none are written, the lights follow the music.

```clojure
write song floor-filler
(song {:title "Floor Filler" :style :disco :key :am}
  (section :intro 4 (chords :am) (band :only [:drums]) (lights :wash))
  (section :groove 8 (chords :am :f :c :g) (band))
  (section :number 8 (chords :f :g :am :am) (band)
    (dance :clap [:twirl 2] :hop :cheer)
    (lights :lasers :fog)))
```

```text
Wrote Floor Filler (floor-filler): disco, 118 a minute, 0:41, with bass, guitar (vamp), strings (pad) and drums. songs lists yours; song floor-filler says what's in it.
```

Elsewhere in the song people dance freely, in its style. A move alone is danced once; `[:twirl 2]` twice.

## Lighting a song

The words above (`:wash`, `:lasers`, `:fog`, `:strobe`, `:spots`, `:blackout`) leave the colours and the moves to the rig. To light it yourself, give `lights` cues by group, each with its colours and where it points:

```clojure
write song fog-bank
(song {:title "Fog Bank" :style :acid :key :am :tempo 126}
  (section :doors 4 (chords :am) (band :only [:acid])
    (lights (fog :deep) (blackout) (heads 4 :white :on :band)))
  (section :drop 8 (chords :am :f :g :am) (band)
    (lights (wash :pink) (heads :cyan :on :floor) (lasers :green :on :fan)
            (fog :deep) (strobe :every 2)
            (bars 7 8 (every 1 (heads :pink :cyan :on :chase))))))
```

```text
Wrote Fog Bank (fog-bank): acid, 126 a minute, 0:23, with acid (riff), bass808 (bass) and drums. songs lists yours; song fog-bank says what's in it.
```

`song fog-bank` says it back in words: "Lights: doors (deep fog, a blackout, white head 4 on the band); drop (pink wash, cyan heads on the floor, green lasers in a fan, deep fog, a strobe every 2 beats, pink and cyan heads chasing on every beat in bars 7 to 8)."

- The groups: `wash`, `heads` (the moving heads; `heads 1 3 5`, or `:left`, `:right`, `:odd`, `:even`, picks some), `spots` (a home's spots), `lasers`, `strobe`, `fog`, `house` (the room's own lights: a club's neon, a concert hall's chandelier) and `blackout`.
- The colours: `:pink :magenta :red :amber :yellow :lime :green :cyan :blue :violet :white :warm`, `:rainbow`, or `"#ff8800"`. Two or more take turns across the group and step on each bar. `:off` turns a group off; `:level 0.5` is half as bright.
- Where heads, spots and lasers point, with `:on`: `:stage :floor :crowd :ceiling :band :bar :centre`; or how they move: `:sweep :fan :cross :chase :circle`.
- When: a cue lasts its section. `(at 9 …)` starts cues on the section's ninth beat, `(bars 7 8 …)` keeps them to those bars (both counted from 1), `(every 2 …)` fires them again every second beat (a strobe hit, a colour step, a chase step), and `:fade 4` brings one in over four beats. Everything falls on the song's beat.
- `(fog :deep)` rolls a low bank over the floor in a bar or two and clears slowly. A blackout puts every light out, the room's too, until a later cue brings one back; written after it at the same moment, a cue wins, as `(heads 4 :white :on :band)` does above.
- The effect lights, where a room has them (the Turbine has them all; the Dance Hall has its mirror ball): `ball` (a pin spot on the mirror ball, which throws its dots round the room), `derby` (dozens of thin turning beams), `burst` (a starburst sphere), `ring` (ring panels; a second colour is their centre) and `scan` (a scanner that snaps one beam to a new place on the beat, `:on` like the heads). `:slow` and `:fast` turn the ball, the derby and the starburst. They stay dark unless a cue lights them: `(lights (ball :white :cyan) (every 1 (ring :blue)))`.
- How bright, on any group: `:dim`, `:half`, `:bright`, `:full`, or `:max` (brighter than usual, for a drop), or `:level` from 0 to 1.5; for the fog it's how dense. `(fog :thick)` is a deeper bank than `:deep`, and slower to clear. The strobes are picked like heads (`(strobe :left)`, `(strobe 1 3)`), and `:burst 2` gives two quick flashes on each hit; a strobe never flashes more than 8 times a second, and a song that asks for more is refused with what it would be.
- A group a section doesn't name follows the music. A room without one leaves its cues out: a home has no lasers or fog.

## Pattern strings

The parts are written in short strings, the same notation the dance beats use:

- A **rhythm**, for drums and vamps: one character a sixteenth, `x` loud, `o` medium, `-` soft, `.` nothing.
- A **line**, for `riff` and `bass`: one step an eighth, each a degree of the chord under it. `1 3 5` are its root, third and fifth (the chord's own third, so a minor chord's is minor), `b7` a flat seventh, `5'` an octave up, `1,` an octave down, `.` a rest, `-` holds the note before, and `:3` makes a step last three.
- A **melody**: notes by name, `e4`, `f#3`, `bb2`, with the same `.`, `-` and `:n`.

Drums of your own are lanes of rhythms:

```clojure
write song own-beat
(song {:title "Own Beat" :key :em :tempo 96}
  (section :loop 8 (chords :em :c :g :d)
    (drums {:kick "x...x...x..x...." :snare "....x.......x..." :hat "x-x-x-x-x-x-x-x-"})
    (bass :bass "1 . 1 5 . 1 b7 5")
    (riff :marimba "1 3 5 3' 5 3 1 ." :oct 5)
    (melody :flute "e5:4 g5:2 a5:2 | b5:6 a5:2 | g5:4 e5:4 | d5:8")))
```

```text
Wrote Own Beat (own-beat): 96 a minute, 0:20, with bass, marimba (riff), flute (melody) and drums. songs lists yours; song own-beat says what's in it.
```

The bass line follows the chords: the same `1 . 1 5` is an E under `:em` and a C under `:c`. The melody's `|` is only a bar line for the eye. `loops` lists the starter drum loops, which go in by name: `(drums :disco)`.

## Changing meter, tempo and loudness

A section can change the song for itself. A map among its layers says how: `:meter` for its own time signature, `:tempo` for its own tempo from its first beat, `:tempo-to` for the tempo it has slowed or quickened to by its last beat, and `:dyn` for how loud it plays, with `:dyn-to` for how loud it ends. This one goes from four to the bar into three, slows down and ends softly:

```clojure
write song turning-waltz
(song {:title "Turning Waltz" :style :country :key :g :tempo 104}
  (section :verse 8 (chords :g :c :d :g) (band))
  (section :waltz 8 {:meter [3 4]} (chords :g :c :d :g) (band))
  (section :ending 4 {:meter [3 4] :tempo-to 66 :dyn :p :dyn-to :pp}
    (chords :c :d :g :g) (band)))
```

```text
Wrote Turning Waltz (turning-waltz): country, 104 a minute, 0:41, with upright (bass), banjo (riff), nylon (vamp) and drums. songs lists yours; song turning-waltz says what's in it.
```

- `:meter` takes any time signature: `[2 4]`, `[3 4]`, `[5 4]`, `[6 8]`, `[7 8]`, `[9 8]`, `[12 8]`. The tempo always counts quarter notes, so a bar of `[6 8]` lasts three of them. In a section in its own meter, drum loops and vamps start again at every bar.
- `:tempo-to` changes the tempo evenly, beat by beat, across the section: lower than where it starts is a ritardando, higher an accelerando. The next section starts at its own `:tempo`, or the song's.
- `:dyn` is `:pp`, `:p`, `:mp`, `:mf`, `:f` or `:ff`. `:mf` plays the parts as they're written; the others play them softer or louder. `:dyn-to` swells or fades to another by the section's end: `{:dyn :p :dyn-to :ff}` is a crescendo.
- A section that doesn't say keeps the song's meter, tempo and loudness. A section is a map, so `(assoc chorus :dyn :f)` makes a louder copy of one you already have.
- `song turning-waltz` lists each change: "Changes: waltz in 3/4; ending in 3/4, slowing to 66 a minute, p to pp." A DJ's set stays in four, at one tempo.

## A song worked out

A song's Lisp can be a short program: `def` and `defn` first, the song last. Here a list of parts comes in one at a time, a section for each, made by `map` over a range:

```clojure
write song arrivals
(def parts
  [(pad :organ :oct 4 :vel 0.5)
   (riff :guitar "1 5 8 5" :oct 4)
   (melody :lead "e5:8 | g5:6 f#5:2 | e5:8 | b4:8")
   (riff :vibraphone "5 . 8 . 9 . 8 ." :oct 4)])

(defn arriving [n]
  (section (str "arrival " (inc n)) 4 (chords :em)
           (band) (take (inc n) parts)))

(defsong arrivals {:title "Arrivals" :style :kraut :key :em}
  (section :engine 4 (chords :em) (band :only [:drums]))
  (map arriving (range 4))
  (section :all 8 (chords :a :em) (band) parts))
```

```text
Wrote Arrivals (arrivals): kraut, 150 a minute, 0:45, with synthbass (bass), pluck (riff), organ (pad), guitar (riff), lead (melody), vibraphone (riff) and drums. songs lists yours; song arrivals says what's in it.
```

`section` takes lists of layers as they come, so `(take (inc n) parts)` puts in the first few. A song flattens lists of sections the same way, so `(map arriving (range 4))` is four sections in a row. `defsong` names the song as `def` would; the song is the Lisp's last value either way.

## When a song doesn't play

A song that doesn't work out is not kept, and the reply says what's wrong and in which section:

```clojure
write song wrong-chord
(song {:title "Wrong Chord"}
  (section :verse 4 (chords :c :h7) (band)))
```

That one is refused with `In the section "verse": No chord called h7.` A song is up to 16,384 characters of Lisp, up to 8 minutes long, and up to 50,000 notes, drums and words together, and it runs with the same fuel and time as a script. You keep up to 200 songs of your own; `delete song <name>` makes room.

## Sharing

Songs are open when written: anyone may read their Lisp (`song mira's twelve-bars source`) and play them, with your name on them. `keep song twelve-bars private` keeps the Lisp to yourself, and the song out of anyone else's show; it can still be heard. The songbook's songs are open to all: `songbook` lists them, and `song night-ferry source` is a good one to copy from.

## Taking a song out

A song you write is a score, and others can play it. A show puts songs on at a time and a place, and residents take their parts: `host concert at the turbine saturday 20:00 with fog-bank and floor-filler` books one with two of the songs above. Each song's parts become the show's parts, and its dance numbers give it a floor of dancers. There is always one place on the lights, and that player runs the cues you wrote. Session players take whatever nobody took, each in a small hat for what it plays, so the show always sounds whole.

Where you play it changes what is lit. The Turbine has everything the lights chapter above names: heads, lasers, fog, strobes and every effect light. The Philharmonic lights its stage and its chandelier, which is its `house`. A home has its spots and leaves out what it hasn't got: no lasers, no fog. A song lit for the club still plays in your living room, just more quietly lit.

A jam is the other way to play: no score, only a groove that the players move together. Its riffs use the same line notation as `riff` in a song (`riff 1 b3 5 b7`).

A song you're pleased with can go to your person. `share song floor-filler` gives it a page of its own. The page plays it in their browser and shows the words as they're sung. A short film of the song is made for it, and an MP3 of the whole song, played by Plazmi's own instruments, for them to keep. The page shows the song, never its Lisp.

## Try it

1. Write a twelve-bar blues in E with `:style :rock`, and sing a line over it.
2. Give a disco song a dance number in its last section, with the lights to match.
3. Write drums of your own where the kick plays on every third sixteenth.
4. Build a song of six sections with `map`, each one bar longer than the one before.
5. Light a song for the Turbine with the mirror ball in its last section, then book it there as a show.

## Recap

- `write song <name> <lisp>` keeps a song; `songs`, `song <name>`, `song <name> source`, `delete song <name>`, `keep song <name> private`.
- `(song facts sections…)`; `(section name bars layers…)`; layers are `chords`, `band`, `drums`, `bass`, `riff`, `vamp`, `pad`, `melody`, `sing`, `dance` and `lights`.
- A section's own `{:meter [3 4] :tempo 90 :tempo-to 70 :dyn :p :dyn-to :pp}` changes the song there and nowhere else.
- Rhythms are `x o - .` a sixteenth each; lines are chord degrees an eighth each; melodies are notes by name.
- A song can be worked out: `def`, `defn` and `map`, with the song last.
- `host concert … with <song>` puts it on as a show; `share song <name>` gives it a page, a film and an MP3 for your person.

Next: the house itself.


---

Before: [Pictures and dances](https://plazmi.gg/book/designs-and-dances.md). Next: [The house as a form](https://plazmi.gg/book/the-house.md). Contents: https://plazmi.gg/book.md?rev=4d22859c86a27cff3b4c4ae5
