Mods / Guides

Songs

The song file, how a tune is fitted to a fight, and where each tune came from. File and folder names in this guide are paths inside the game’s project.

Every fight in Counterbeat has a song, and the song is data. It names a style, a key, the chords, which instruments play in which bars, and the note each of your punches plays. The band in the game plays what the song says and nothing else, so a fight sounds the same every time you play it.

This page is for people who want to read a song, edit one, or write one for a fight pack or a mod.

Where a song comes from

The game looks for a fight's song in this order:

  1. A song a pack or a mod added. A fight pack can carry its song in fight.json as score (see docs/CUSTOM-FIGHTS.md). A mod can give a built-in fight another song with a music entry that names a score file (see docs/MODDING.md).
  2. A stored song. songs/<fight id>.json, listed in songs/index.json. The game reads these when it starts.
  3. A song written from the chart. When a fight has no stored song, or the stored one does not fit, makeSong in src/song.js writes one from the fight's chart as the fight loads. The same code wrote the stored songs, so a new fight gets a song of the same kind without anyone doing anything.

A stored song fits a fight when each round has the same number of bars, the same bars before play, and the same tempo as the chart. If one does not fit, the game says why in the console and plays a song written from the chart.

Stored today, all of them arrangements of old tunes (see "A song with a tune" below): tape-201 plays El Choclo, tape-202 the Toreador Song from Carmen, tape-203 El Manisero, and tape-204 La Paloma. tutorial (every lesson), training and the four drills play the Habanera from Carmen. Every other fight gets its song at load.

A fight pack with an audio file plays the recording. Its song only decides the notes your punches play.

The file

{
  "format": "counterbeat-song", "version": 1,
  "title": "Flint Goes Down", "fight": "tape-201",
  "style": "son", "key": "D", "mode": "minor", "bpm": 104, "seed": 123456,
  "progressions": {
    "montuno": [[[0,"m"],[5,"m"]], [[7,"7"],[0,"m"]], [[0,"m"],[5,"m"]], [[7,"7"],[7,"7"]]],
    "verse":   [[[5,"m"],[10,"7"]], [[3,"M"],[8,"M"]], [[5,"m"],[7,"7"]], [[0,"m"],[7,"7"]]]
  },
  "parts": {
    "verse":   { "prog": "verse",   "layers": ["clave","kick","bongo","congas","guiro","maracas","bass","piano"], "level": 0.85 },
    "montuno": { "prog": "montuno", "layers": ["clave","kick","bell","congas","guiro","maracas","bass","piano"], "level": 1 }
  },
  "sides": {
    "A": { "rounds": [
      { "round": 0, "bpm": 104, "bars": 78, "intro": 2, "transpose": 0,
        "sections": [ { "bar": 0, "bars": 1, "part": "rest" }, { "bar": 1, "bars": 1, "part": "intro" }, { "bar": 2, "bars": 6, "part": "verse", "hit": true } ],
        "lead": [[8, 62], [9, 65], [9.5, 69]] }
    ] }
  }
}
Field Meaning
style son, songo, timba, chacha, tango or pasodoble. It picks the patterns: what the clave, bell, congas, bass and piano play in one bar. The patterns are in src/music2.js. The tango has no drums: the bass plays the habanera figure and the piano a chord on every beat. The pasodoble is a march: bass on the beat, piano off it, a rim (the timbal layer) and castanets (the clave layer).
key, mode C to B (flats: Db, Eb, Ab, Bb; and F#), with minor, dorian or major.
bpm The tempo of round 1, for reference. The chart sets the tempo of a fight; the song never does.
seed The number the writer drew its choices from. Kept so a song can be traced to its fight.
progressions Named chord progressions, 1 to 16 bars each. A bar is two chords, one for each half. A chord is [semitones above the key, quality]; the qualities are m, M, m7, 7, M7.
parts Named settings for a stretch of the form: which progression, which instruments (layers), and how loud (level, 0 to 1.25).
sides A, B or both: the same fight from each corner has its own rounds, because the notes you play are different. A song with a melody has no sides.
source, melody Only in a song that carries a tune. See "A song with a tune".

A round:

Field Meaning
round The round's number in the fight, from 0.
bpm, bars, intro Copied from the chart: tempo, length in bars of four beats, and the bars before the first punch. These must match the chart or the song is not played.
transpose Semitones up or down for this round. The writer lifts the last round of a fight by 2.
sections The form. Each has bar (where it starts), bars (how long) and part. Sections follow one another from bar 0 and cover the whole round. Optional: hit (a crash on its first bar), fill (1 a short timbal fill in its last bar, 2 a long roll), and level, layers or prog to change the part's settings for that section alone.
lead [beat, note] for each of your punches: the beat counted from the start of the round, the note as a MIDI number from 36 to 96.
harmony Optional. The chords bar by bar, one [chord, chord] for each bar of the round. When a round has it, the sections' progressions are not used.
tune Optional. Notes the band plays itself: [beat, note, beats]. The style's lead instrument plays them over a quiet piano.

The instruments you can put in layers: clave, kick, bell, congas, bongo, guiro, maracas, cascara, timbal, block, bass, piano, horns. A style has no pattern for some of them (son has no cascara, for example); naming one of those does nothing.

A song with a tune

A song can carry a real melody. You write the tune once and the game fits it to the fight, from either corner.

{
  "format": "counterbeat-song", "version": 1,
  "title": "El Manisero", "fight": "tape-203", "style": "son", "key": "G", "mode": "major", "bpm": 104, "seed": 0,
  "source": { "title": "El Manisero (The Peanut Vendor)", "composer": "Moisés Simons", "died": 1945, "published": 1930,
              "from": "Voice part of the 1930 Edward B. Marks print", "verified": true, "note": "Melody only." },
  "melody": {
    "notes": [[null, 0.5], [4, 0.25], [5, 0.25], [7, 0.25], [9, 0.25], [7, 0.25], [6, 0.25], [7, 0.5], [7, 0.25], [5, 0.5], [5, 0.25], [4, 0.5]],
    "chords": [[[0, "M"], [7, "7"]]],
    "phrases": [0]
  },
  "progressions": { "tune": [[[0, "M"], [7, "7"]]] },
  "parts": { "intro": { "prog": "tune", "layers": ["clave", "kick", "congas", "maracas", "bass", "piano"], "level": 0.8 } }
}

(The example is cut short: one bar of the tune, and one part of the six.)

Field Meaning
melody.notes The tune from start to end: [semitones above the key note, beats], with null for a rest. 0 is the key note at or above middle C, so in G a 4 is the B above it and a -5 the D below. Beats are the game's beats: four to a bar.
melody.chords The chords under the tune, one [first half, second half] for each bar of four beats. The notes must last exactly as many bars as there are chords.
melody.phrases The bars a phrase starts on, counted from 0.
source Whose tune it is: title, composer, died and published (years), from (where the notes were taken from), note, and verified: true when the notes were read from a printed score of the tune, false when they come from someone else's transcription or from memory.

The song needs the six parts the form uses (intro, rest, verse, montuno, mambo, break), each written as in any other song, and one progression for them to name. It has no sides.

How the game fits the tune (arrange in src/song.js):

  • Your punches play the tune's notes in order. The first punch plays the first note, the next punch the next. Land them and the tune comes out; miss one and that note is missing. The rhythm is the chart's, the notes are the tune's.
  • The chords follow the notes. Under each punch the band plays the chord the tune has under that note, and holds it until the next one.
  • Where you have nothing to hit for two bars or more, the band plays the tune itself, from the top of the next phrase and in its own rhythm, on the style's lead instrument. The same happens in the bars before a round starts. Your punches then carry on from the note the band stopped at.
  • Each round starts on a phrase: round 1 on the first, round 2 on the second, and so on round the list.
  • The form (which instruments play, and how loud) is read from the chart as for any other song.

How long a beat of the tune is depends on the style. The Habanera is stored the same way as the tangos: its eighth note is the game's beat. In a tango the game's beat is the tune's eighth note, so a bar of the game is a bar of 2/4. In a pasodoble it is the quarter note, so a bar of the game is two bars of 2/4. In son a bar of the game is one clave, two bars of the print in cut time, and a printed quarter note is half a beat.

node tools/make-song.mjs tape-201 --fitted prints a song with a tune as the game fits it to its fight: the lead, harmony and tune of every round.

A pack's score and a mod's score file can be a song with a tune too. It is fitted to the pack's or the fight's chart when the fight starts.

The tunes in the game, and where the notes came from

Fight Tune Composer Published Notes taken from verified
tape-201 Onyx v Flint El Choclo (tango) Ángel Villoldo, died 1919 1903 John Chambers's ABC transcription, parts A and B (trillian.mit.edu/~jc/music/abc/Argentina/tango/Choclo_Am.abc). Not compared with the 1903 print. no
tape-202 Cobalt v Ember Toreador Song from Carmen, the refrain (played as a pasodoble) Georges Bizet, died 1875 1875 The refrain as it stands in the Prelude, 24 bars of 2/4 in F: the top voice of the Mutopia Project's LilyPond file (mutopiaproject.org/ftp/BizetG/prelude/prelude.ly, typeset from the Schirmer 1895 piano score), from the bar marked 5-1b. Chords from an ABC lead sheet of the song (github.com/SBurrell23/Sheets, songs/classical/toreador-song.abc), moved from C to F. The two differ in one note of bar 17 (C natural here, C sharp in the ABC). The G in bar 22 is a grace note in the piano score. Grace notes left out. Not compared with a print. no
tape-203 Slate v Gold El Manisero (son-pregón) Moisés Simons, died 1945 1930 The voice part of "The Peanut Vendor (El Manisero)" (Edward B. Marks, 1930), read from the scan at archive.org/details/the-peanut-vendor. The piano part of that print is not used. yes
tutorial, training, drill-basics, drill-turn, drill-defend, drill-fast Habanera from Carmen (played as a tango) Georges Bizet, died 1875 1875 The voice part of the first two phrases, eight bars. Bars 1 to 4 are the excerpt engraved in the English Wikipedia article "Habanera (aria)". Bars 5 to 8 were written from memory. Not compared with a print. no
tape-204 Tide v Hammer La Paloma (habanera, played as a tango) Sebastián Yradier (Iradier), died 1865 about 1859 An ABC lead sheet from the Wikifonia collection (github.com/oriolcolomefont/The-Sound-of-AI-workshop, wikifonia-dataset/original-abc/SebastianYradienLaPaloma.abc), melody and chords: the verse, the second strain and the refrain, once each, 26 bars in C. It agrees with the tenor line of a second ABC file (github.com/baobach/abc_search, database/abc/QmTKDqnk2k82yFfjfFjCYGKjnnXvg3VnLSRaQSNaDyYvYQ.abc) except for one pick-up note (G here, D there). Both write the habanera rhythm as short, long, short where old prints often have a triplet. Not compared with a print. no
tape-201 with the mod mods/example-song Jarabe Tapatío (played as a pasodoble) Jesús González Rubio, died 1874 1800s The first strain, eight bars of 6/8, as engraved in the English Wikipedia article "Mexican hat dance". Not compared with a print. no

Only the melody and the plain chords under it are used: no words, and nothing from a later arrangement or recording. The band's parts are the game's own patterns.

Why these are thought to be free to use: the four fight tunes were published before 1931, so they are in the public domain in the United States. Yradier, Bizet, González Rubio and Villoldo died more than 100 years ago (1865, 1875, 1874, 1919), so La Paloma, the two Carmen tunes, the Jarabe Tapatío and El Choclo are past every term in use, the 100 years of Mexico included. Simons died in 1945, more than 80 years ago: El Manisero is past the 70 years of most countries and the 80 years Spain keeps for authors who died before 7 December 1987, and is still protected where the term is longer than that. This is not legal advice.

Until 18 November 2026 tape-202 played España cañí and tape-204 La Cumparsita. Both composers died in 1948, so those tunes stay protected in Spain until the end of 2028, and they were taken out.

A lesson is one short round, so every lesson starts the Habanera from the top: the band plays its first two bars while the cue is shown, and your three punches play the next three notes. A lesson with no punches (block, slip, roll, lean back, footwork) has the band play the tune through. The lessons need no stored rounds: a song with a tune is fitted to whatever rounds the game builds.

La Paloma (Yradier) was wanted for training and the drills first, and no score of it could be read then. It is now the song of tape-204, from the ABC named in the table.

The Jarabe Tapatío is in 6/8. Its dotted quarter note is the game's beat, so its eighth notes fall in threes over a band that plays in twos and fours.

How the writer makes a song

makeSong reads the chart and decides:

  • Style from the fight's year: before 1980 son, 1980 to 1994 songo, later timba. Lessons are cha-cha-cha. A fight with no year gets one of the three from its id.
  • Key and chords from the fight's id, so a fight always gets the same ones and two fights rarely share them.
  • Form from how busy the chart is, two bars at a time. Bars with no punches are a rest, or a break when a man is down. The quietest third of the others is the verse, the middle third the montuno, and the busiest third the mambo, where the horns come in. A round never opens on the mambo, and the last round of a fight ends on it.
  • Lead from your punches. Each one is a tone of the chord in force at that moment. A jab is the root, a cross the next tone up from the note before, a hook the fifth, an uppercut the octave, and a body shot one tone lower. A new phrase starts after a gap of more than a beat and a half, so the same combination over the same chord is the same riff each time.

Your notes are not in the band's part. Each one sounds when the punch lands, so a miss leaves a hole in the tune.

Tools

node tools/make-song.mjs --list --form          every built-in fight: stored or written at load, style, key, tempo, form
node tools/make-song.mjs tape-201               print the song the writer makes for a fight
node tools/make-song.mjs tape-201 --title "Flint Goes Down" --style son --key D --write     store it in songs/
node tools/make-song.mjs --pack packs/my-fight/fight.json     print the song for a fight pack
node tools/make-song.mjs --check                every stored song is valid and fits its fight

--check also says whether a stored song is still what the writer makes or has been edited by hand since. For a song with a tune it fits the tune to the fight and checks the result.

To change a fight's song by hand: write it with --write, edit songs/<id>.json (move a section, change a part's layers, rewrite the lead), then run --check. If you later change the fight's chart so that a round's bars or tempo differ, the song stops fitting and has to be written again.

For a pack, node tools/make-pack.mjs <chart id> --bpm 108 writes a pack with a score and no audio file. packs/example-score/fight.json was made that way; try index.html?pack=packs/example-score/fight.json. For a mod, node tools/make-mod.mjs my-mod --score tape-201 writes scores/tape-201.json to edit and the music entry that points to it. node tools/validate-mod.mjs checks a score and that it fits its fight.

When a song is wrong

A song from outside the game is checked before it is used (validateSong in src/song.js). It is only data: names, numbers and lists, with limits on every one (400,000 characters, 40 rounds a side, 600 sections a round, 6,000 lead notes a round, 2,000 notes and 256 bars in a melody). A song that fails is not played. The fight still loads, the band plays a song written from the chart, and the reason is shown: in the console for a pack, in the mod's error list for a mod.

Back to mods