Help & Documentation

How to add songs, create sync points, and use the visualization

Adding Songs (MIDI + Audio)

File Structure

public/
└── songs/
    └── my_song/              ← Folder name = Song ID
        ├── my_song.mid       ← MIDI file (same name as folder)
        ├── my_song.mp3       ← Audio file (same name as folder)
        └── config.json       ← Created automatically when you Save

Important Notes

  • Folder name becomes the Song ID (use underscores, no spaces)
  • MIDI and MP3 files should match the folder name (e.g., volver/volver.mid)
  • Supported audio: .mp3, .wav, .ogg
  • Supported MIDI: .mid, .midi

Step-by-Step

  1. Create a folder in public/songs/ with your song ID
  2. Copy your MIDI file into the folder, rename to match folder name
  3. Copy your MP3 file into the folder, rename to match folder name
  4. Refresh the Catalog page - your song should appear
  5. Click Edit to create sync points

Terminal Commands

mkdir -p public/songs/my_song
cp ~/Downloads/song.mid public/songs/my_song/my_song.mid
cp ~/Downloads/song.mp3 public/songs/my_song/my_song.mp3

Using the Editor

Creating Sync Points

Sync points map MIDI time to audio time, allowing the visualization to stay in sync with the recording despite tempo variations.

  1. Switch to Sync Points mode (green button)
  2. Click on the audio waveform to mark an audio time
  3. Click on the MIDI piano roll to mark the matching MIDI time
  4. Click Link Points to create the sync point
  5. Add more sync points at key moments (start, tempo changes, phrases)
  6. Click Save to save your work

Navigation Controls

Audio Waveform
  • Click - Select audio time
  • Alt + Drag - Scroll through audio
  • Zoom slider - Zoom in/out
  • Position bar - Click to seek
MIDI Piano Roll
  • Click - Select MIDI time
  • Alt + Drag - Scroll through MIDI
  • Scroll wheel - Scroll horizontally
  • Ctrl + Scroll - Zoom in/out

Sync Zoom

Enable "Sync zoom with MIDI/Audio" to keep both views at the same pixels-per-second, making it easier to align sync points.

Play Modes

Standard Play

Horizontal piano roll with notes scrolling left-to-right.

  • • Audio or MIDI playback modes
  • • Track solo/mute controls
  • • Adjustable zoom and note size

Cinema Mode

Full-screen vertical visualization like movie credits.

  • • Notes scroll top-to-bottom
  • • Instruments in vertical columns
  • • Track solo/mute panel
  • • Fullscreen support

Cinema Mode Keyboard Shortcuts

Space Play/Pause←/→ Seek 5sH Hide controlsEsc Exit

Troubleshooting

Song doesn't appear in Catalog

  • Make sure the folder is directly inside public/songs/
  • Check that you have both a MIDI and an audio file
  • Refresh the page (the API reads the filesystem)

Audio/MIDI doesn't load

  • Files should be named songId.mid and songId.mp3
  • Or create a config.json with custom filenames
  • Check browser console for errors (F12)

Sync points not saving

  • Make sure you click Save after creating sync points
  • Check browser console for save errors
  • The server needs write permission to public/songs/