KickSideYour Musical SideKick

Help

FAQ

DraftThe song file section is written from the project's format document (firmware 0.10.6, song format up to 2.2). The questions are the ones we expect; tell us which ones people really ask.

Questions

Are there video demos?

Yes, one for each mode. They are also on the welcome page.

How do I contact you?

Use the contact page, or write to websiteInfo@KickSideSideKick.com. Bug reports, song takedown requests and questions are all welcome.

Does it work on every FM-1?

It has been tested over stock firmware V15 only. On any other version the installer warns you and lets you continue at your own risk. It has been tried on one unit. See Install the firmware.

Can I go back to the stock firmware?

Yes: install the official V15 package again, or restore the backup you made of your own unit. Songs live in their own area of the flash and the stock firmware does not use it.

Do I need to send songs?

No. From firmware 0.10.5 the FM-1 already holds 15 songs and 42 backtracks. You can send more from the browser: see Song library. That needs Google Chrome or Microsoft Edge on a computer. Firefox, Safari, phones and tablets are not supported.

Will an update erase my songs or sounds?

No. A firmware update leaves the song store, your saved SYNTH presets (U01–U30) and the settings alone. One thing resets: Pop-ups is ON again after every update, so switch it off again if you prefer.

Can I delete the built-in songs?

No. They are part of the firmware and use none of the song store. If you send a song with the same name as a built-in, your copy is listed instead, and deleting your copy brings the built-in back. “Wipe song store” and a factory reset do not remove them either.

What does “SONG ERROR” mean?

A stored song failed its internal check when the FM-1 read it, so it is listed with its reason and is not played. Send it again, or wipe the song store (Settings, hold PLAY for 2 seconds) if several are affected.

What is the difference between SONG LEARN and BACKTRACK?

SONG LEARN plays a particular song and shows you one layer to play, with a melody. BACKTRACK plays only a chord progression in a style you choose, with no melody: you make one up with the scale marked on the screen. Instructions explain both.

Can I use my own MIDI files?

Yes. The Import a MIDI file page turns a MIDI file into a song, lets you listen to it, and installs it on your FM-1 from Chrome or Edge. Keep in mind that a MIDI file of a public-domain tune is often someone's copyrighted arrangement.

How do I install a song from my own computer, without the website?

Most people should use the website: the importer and the song library send songs to the FM-1 from Chrome or Edge. Use this route if you cannot use Chrome or Edge, or you prefer the command line. It runs on Windows, Mac or Linux.

  1. Get the song file. On the importer, open Other ways to get the song and download the ZIP. It holds the finished .fm1s file, the MIDI file, the lead sheet (song.yaml) and a short HOW-TO-USE.txt.
  2. Get the tools. Download or clone the GitHub repository (git clone https://github.com/kjs4discovery/kicksidesidekick.git). You need Python 3.
  3. Set them up once. In the repository folder run python3 -m venv .venv, then .venv/bin/pip install PyYAML numpy lameenc mido python-rtmidi (on Windows the folder is .venv\Scripts).
  4. Check the song. Unzip the ZIP into the repository's songs/ folder, then run tools/fm1song.sh validate songs/<song>/. Add preview songs/<song> out.mp3 to hear it first.
  5. Send it. Plug the FM-1 in by USB, put it in SONG LEARN mode, run tools/fm1song.sh list to check it answers, then tools/fm1song.sh send songs/<song>/. The tool refuses to write unless the unit runs KickSide.

Back up first, as on the firmware page. send, delete and wipe write to the FM-1's song area; list only asks. The repository's README has the details.

Where is the code?

The firmware, the song tools and this site's source are on the GitHub repository.

The song file format

Songs do not need this website. Anyone can write a song file by hand or with their own tools and send it to an FM-1 running KickSide. The format is small and fully documented; the reference tools in the GitHub repository read and write it.

1. Two ways to look at a song

A song is authored as a folder with two files and compiled to a single .fm1s file, which is what the FM-1 stores and reads.

FileHolds
song.yamlThe lead sheet: title, key, tempo, time signature, sections, the chord chart, the style and rights notes
song.midA standard MIDI file with the notes: at least a melody track, plus any drums, bass or harmony parts you write yourself
song.fm1sThe compiled file, checked and compact. The device reads only this

2. song.yaml

A short example (the keys shown are required unless noted):

format: fm1-song/1
slug: amazing-grace
title: Amazing Grace
category: Hymns
credits:
  music: Traditional
rights:
  composition: public domain
music:
  key: G
  time_signature: 3/4
  tempo_bpm: 84
  pickup_beats: 1
  style: waltz
form:
  - { section: Verse 1, bars: 1-16, chart: verse }
layers:
  melody: { channel: 1, program: 74 }
chart:
  pickup: "| N.C. |"
  verse: |
    | G | G7 | C | G | G | Em | D | D7 |
    | G | G7 | C | G | Em | D | G | G . D7 |

The chord chart

Bars are separated by |. Chords are a root A to G, an optional # or b, a quality, and an optional /bass note, up to 7 characters. Qualities: none, m, dim, aug, +, sus2, sus4, sus, 5, 6, m6, 7, maj7, m7, mmaj7, m7b5, dim7, 7sus4, 9, maj9, m9, add9.

| C G |   two chords share a 4/4 bar, two beats each
| G . D7 |  in 3/4: G for two beats, D7 on beat 3
| N.C. |   no chord

3. song.mid

4. Levels

Harmony has up to 5 levels, bass up to 4 and drums up to 3. Any level you do not supply is generated by the FM-1 from the chord chart and the style. Levels you do supply replace the generated ones. Each layer can also name a level to open at (start_level).

5. The compiled .fm1s file

All numbers are little-endian, and each chunk starts on a 4-byte boundary. The header is 32 bytes:

OffsetTypeFieldMeaning
0char[4]magicFM1S
4u8, u8versionmajor, minor: 2.0 to 2.2 for songs with a style; 1.0 to 1.3 for older ones
6u16chunk_count1 to 24
8u32file_sizethe file's length, at most 256 KiB
12u32crc32CRC-32 of the whole file, with these 4 bytes counted as zero
16u16ppqticks per beat (480 in 2.0)
18u8, u8beats_per_bar, beat_unit2 to 7, and 4
20u32tempo_usmicroseconds per beat (30 to 250 BPM)
24u32end_tickbar_count × beats_per_bar × ppq
28u16bar_count1 to 999, including the pickup bar
30u8pickup_beatsfewer than beats_per_bar
31u8flagsbit 0: swing

A directory follows the header: for each chunk, a 4-character id, an offset and a size. The chunks:

ChunkHolds
METAkey, slug, title, key name
CATGthe category (the list's folder)
SECTthe sections: first bar, length, lead-in, name
CHRDthe distinct chords: symbol, root, bass, pitch-class mask
CEVTevery chord change, with two keyboard voicings
BARSper bar: its chord event, section and flags
STYLthe style (waltz, ballad, shuffle, march, pop, train) and swing
LAYRper layer: channel, program, variants, volume, pan, stored-levels mask, start level (2.1)
FORM2.2 only: kind (song or backtrack), number, scale, numerals, each section's role and energy
INFOoptional: one line about the song's origin, up to 39 characters, shown on the SONG LEARN settings screen
NT + layer + levelstored notes for one level, e.g. NTH3 is harmony level 3: patterns of notes, one pattern per different bar

Stored notes use patterns: every bar that sounds the same shares one pattern, and each note is a start offset, a length, a pitch and a velocity, with the offsets and lengths stored as small variable-length numbers. The device refuses any file that is not exactly as described, so a damaged file cannot be written.

Versions

VersionWhat changed
1.0 to 1.3Notes stored as event streams; category added; up to 5 levels per layer
2.0The FM-1 generates the levels itself from the chart and a style; only the melody and your own parts are stored
2.1Adds a start level per layer. A song uses 2.1 only if it needs it
2.2Backtracks and the five newer styles: adds a FORM chunk (song or backtrack, its number, scale and numerals, and each section's role and energy)

6. Limits

7. Sending a song to the unit

Songs travel over USB as MIDI SysEx messages. A sender must check that the device's identity starts with FM-1_58 before sending anything, and must not retry after a disconnect. The commands are list, send, delete and wipe. Note that “list” shows only what is in the song store, never the built-in songs. The details are in the GitHub repository.

Be carefulWriting to the flash can leave a unit unusable if the sender is wrong. Use the reference tools, read the notes, and keep a backup of your own unit.