Show files

A show file (*.show.toml) composes a music video from Cycletron songs. For each section of each song it sets what's on screen: the visual mode, the camera, the cuts and transitions, colors, text, the song's code, and effects.

• Live: open the file in Cycletron. The set plays with the show file in a pane beside the song, and edits take effect as you type.
• Rendered: render-viz.mjs writes the same video to an MP4.

Both cut the same video. Every frame is a function of song time, so what you preview live is what renders.

Three shows come with the app, in your library's Demos/Shows/ (ui/shows/ in the repo): agency-ost plays the Agency album, feature-tour uses every setting with a comment on each section saying what it shows, and cycletron-trailer is the trailer.

Contents: Quick start · How a show is built · Key reference · Modes · Palettes · Camera moves · Transitions · Text · Code · Playing live · Rendering · Recipes · Gotchas

#Quick start

[show]
out = "renders/my-video.mp4"

[defaults]
code = "hide"
camera = "drift"

[[song]]
source = "../Songs/my-song.strudel"
mode = "tunnel"

[song.sections]
intro = "lissajous"
drop  = { shots = ["iso-city", "plasma"], every = 2, transition = "flash", strobe = "kick" }

Play it: open the file in Cycletron (⌘O, or click it in the file tree). Render it:

cd ui   # from the cycletron checkout
node scripts/render-viz.mjs path/to/my.show.toml

#How a show is built

#Songs and sections

A show is a list of songs ([[song]]), played in order. Each song needs a form: a pickRestart selector whose labels name its sections.

"<intro@2 verse@2 drop@4 outro>".slow(4).pickRestart({
  intro: stack(…), verse: stack(…), drop: stack(…), outro: stack(…),
})

A section's length in bars is its weight times the slow factor. Here intro@2 under .slow(4) is 8 bars, and outro is 4. The labels (intro, drop, …) are what [song.sections] refers to. To list a song's sections with their bars, run cargo run -p song-check -- song.strudel from the Cycletron repo. A flat MIDI import (one $: track per instrument) gets a form from node ui/scripts/section-song.mjs song.strudel --sections intro:0-5,…, which slices every track at the bars you name.

#Bars

Every position and length in a show is in bars (cycles), so the edit stays locked to the music at any tempo. Fractions are fine: 0.5 is half a bar, and 0.25 is one beat in 4/4.

#Layers

A setting comes from the most specific place it's written:

1. [defaults]: every song and section.
2. [[song]]: that song's sections.
3. [song.sections].<label>: that one section.
4. A shot inside shots: that one shot (only mode, bars, camera, palette).

Anything a layer leaves out comes from the layer above it. Table-valued settings (camera, code, strobe) layer field by field. For example, code = { place = "right" } in a section keeps the song's follow and size, and moves only the column.

#Writing sections

A section is either a mode name, or a table:

[song.sections]
intro = "lissajous"                                # just a mode
drop  = { mode = "plasma", palette = "vapor" }     # an inline table (one line)

[song.sections.break]                              # or a full table: easier for long ones
mode = "forest-drive"
letterbox = 2.39
text = [
  { say = "first line", at = 1 },
  { say = "second line", at = 3 },
]

TOML doesn't allow line breaks inside { … }, except inside a list's [ … ]. Use the [song.sections.label] form for anything long.

#Strictness

Every key and value is checked. A typo or bad value fails with its exact location (song[1].sections.drop.camera.kick: expected 0 to 4, not 5). Live, the error is marked on its line in the show pane, and the last good version keeps playing.

#Key reference

#[show]

#[[song]]

A song can also set any key from the next table, for all its sections.

#Anywhere: [defaults], [[song]], or a section

#Sections only

#Shots

shots = ["iso-city", "cockpit", "tunnel"]          # each holds `every` bars
shots = [
  { mode = "iso-city", bars = 2, palette = "sunset" },
  { mode = "cockpit", camera = "shake" },          # bars from `every`
]

Shots play in order and repeat until the section ends. The last one is cut short if it would run past the end. A shot can set its own mode, bars, camera and palette. Each shot starts a fresh camera move, and each cut uses the section's transition.

#Modes

Modes "driven by the pattern" draw the song's actual notes and tracks: what you see is the code. The others react to the sound.

#Palettes

A palette recolors the mode, and the code overlay with it. Give each shot its own for a color change on every cut.

#Camera moves

Two strengths, scaling from 1 (0 turns one off, 4 is the maximum):

• punch: the slam out on each cut (a section or shot start). There's none at a song's very start.
• kick: the bump on each kick drum in the pattern.

camera = "orbit"
camera = { move = "shake", punch = 2, kick = 3 }
camera = { kick = 0 }        # keep the move from above, no kick bumps

#Transitions

How each shot, and each section, is entered.

transition = "fade"
transition = { kind = "glitch", bars = 0.15 }

A kind alone takes its default bars; { kind, bars } sets them.

#Text

#Section title cards

With titles = true, each section opens with a card: a flash, then // LABEL glitches in, holds about 1.3 seconds, and fades. A small 03 / 07 counter sits above it. title = "…" replaces the text, and also turns that one card on.

#Lines of text

text = [
  { say = "every sound a district", at = 1.5, hold = 2.4 },
  { say = "THIS VIDEO IS CODE.", at = 2, hold = 2.4, style = "card" },
  { say = "shots = [\"iso-city\", …]", at = 2.2, hold = 2, place = "top" },
]

Text has no background box: a thin dark outline keeps it legible over the visuals. Long text shrinks to fit the frame width. text is set per section and isn't inherited.

#Code

The song's own code, drawn over the visuals the way Stage Mode draws it, with the playing notes lit.

code = "solo"
code = { follow = "solo", place = "right", size = 22, opacity = 0.6, scrim = false, type = 2 }

#Playing live

• New: in the file tree, New File and a name ending .show.toml. It starts out playing the song that's open.
• Open: ⌘O, click a .show.toml in the file tree, or drag it onto the window. The first song opens in the editor and plays from its start, and the show opens in a pane beside it. A show with a mistake opens with the mistake marked, and starts playing once it's fixed.
• Edit: changes in the show pane take effect about 0.3 s after you stop typing. An error is marked on its line, and the last good version keeps playing. ▶ marks the line setting the playing section. Edits to the song itself apply as usual and re-cue the show.
• Suggestions: the pane suggests the keys that fit where you're typing, and their values: modes, palettes, moves, the song's section names, and songs in your library for source. They open as you type; ⌃Space opens them anywhere. Hover a key to see what it does and what it takes.
• Save: ⌘S saves whichever editor you last typed in, the show pane or the song.
• Stage: ⌘⇧F shows the visuals full-frame with the code layer. ⌘⇧V toggles the visuals behind the editor. The camera, text, palettes and effects play in both.
• Commands (⌘⇧P palette): Show: Next Song, Show: Previous Song (switch on the next bar), Stop Show.
• The set: each song plays its form passes times, then the next starts on the downbeat at its own tempo. The last song loops. If the playing song has unsaved edits, the set waits, then moves on at the next section once you save. Edits made in the last bars before the next song starts are saved when it does.
• Closing: closing the pane or opening another file ends the show. An unsaved show asks Save / Discard / Cancel.

#Rendering

cd ui   # from the cycletron checkout
node scripts/render-viz.mjs path/to/show.toml [flags]

#Previews

# one section, small and fast
node scripts/render-viz.mjs my.show.toml --song 1 --section drop --size 960x540 --fps 30 --out /tmp/drop.mp4

# the whole set, small: about 10 s per minute of video
node scripts/render-viz.mjs my.show.toml --size 640x360 --fps 24 --out /tmp/preview.mp4

A full 1080p60 render takes about as long as the video plays, on 8 cores.

#Exports and audio

Rendering needs each song's mix and section timing (a performance export). The first render of a song makes one, in about 20 s, and caches it in ~/.cache/cycletron/performance. It's redone when the song file changes.

The render carries the raw mix, at the level the visuals are tuned to react to. To master it, re-encode the audio only:

ffmpeg -i video.mp4 -af "acompressor=threshold=-26dB:ratio=2:attack=15:release=150:makeup=3dB,volume=15dB,alimiter=limit=0.84" -c:v copy video-master.mp4

Or swap in a separately mastered WAV:

ffmpeg -i video.mp4 -i master.wav -map 0:v -map 1:a -c:v copy -c:a aac -b:a 320k -shortest video-master.mp4

Songs play back to back, each starting on the downbeat after the previous one ends. In a render the video ends with the last song, which doesn't loop.

#Recipes

A cut on every bar, each shot its own color

[song.sections.drop]
shots = [
  { mode = "iso-city", palette = "sunset" },
  { mode = "tunnel", palette = "vapor" },
  { mode = "matrix-rain", palette = "toxic" },
]
every = 1
transition = "flash"
strobe = { on = "kick", strength = 0.12 }
camera = { move = "drift", punch = 1.5 }

A cinematic break

[song.sections.break]
mode = "forest-drive"
palette = "sunset"
letterbox = 2.39
grain = 0.45
transition = "black"
camera = { move = "drift", punch = 0 }

Code typing itself in, then lighting up

[song.sections.intro]
mode = "neon-circuit"
code = { follow = "solo", size = 34, type = 1.6 }
camera = { move = "push", punch = 0 }

Lyrics, a line per phrase

[song.sections.verse]
text = [
  { say = "11 PM.", at = 0, hold = 2 },
  { say = "the phone lights up", at = 2, hold = 2 },
  { say = "and I'm already gone", at = 4, hold = 3 },
]

Big word slams on the beat

text = [
  { say = "LINK.", at = 3, hold = 0.2, style = "card" },
  { say = "OSC.", at = 3.25, hold = 0.2, style = "card" },
  { say = "GO.", at = 3.75, hold = 0.2, style = "card" },
]

Visuals only, cards only on chosen sections

[defaults]
code = "hide"
titles = false

[song.sections.drop]
title = "THE DROP"          # this one section gets a card

A song that fades in and out, played twice

[[song]]
source = "../Songs/x.strudel"
mode = "lissajous"
passes = 2
fade = { in = 2, out = 4 }

#Gotchas

• The code shows by default (code = "off"), in Stage and in renders. Put code = "hide" in [defaults] for visuals only, and turn it on per section.
• A center line on a section's downbeat sits on that section's title card. Use place = "bottom" or start it a bar later.
• Cards and centered code overlap. Move the code (place = "right"), fade it (opacity), or hide it for that section.
• orbit shows the frame's corners in very wide windows (the live visuals behind the editor). Stage and renders are 16:9 and fine.
• The kick strobe on four-on-the-floor flashes four times a bar. Keep strength around 0.1–0.35 or it washes the frame grey.
• The opening fade: a fade transition into a song's first section comes up from black, live and rendered alike.
• passes and the last song: live, the last song loops forever, and dips to black at the end of its passes if it has fade.out. A render ends with it.
• Section labels must match the song's pickRestart labels exactly. A label the song doesn't have fails with the list of the ones it does.
• mode vs shots: a section's own mode replaces the song's shots. Giving both in one section is an error.
• The palette applies to the code overlay too, since the code is drawn in the theme's colors.

From docs/SHOW_FILES.md at v0.1.0-alpha.27.