Skip to main content

​
Overview

The .SM (StepMania) format is the classic simfile format used by StepMania. It uses the MSD (Music Simulation Data) format with tags beginning with # and ending with ;.

​
Key Characteristics

  • Single timing data - All charts share the same BPM, stops, and delays
  • Wide compatibility - Supported by all StepMania versions
  • Simple structure - Easy to read and edit
  • Multiple difficulties - One file can contain all difficulty levels

​
File Structure

A .SM file consists of:
  1. Song metadata - Title, artist, media files
  2. Timing data - Offset, BPMs, stops, delays
  3. Display options - Sample preview, display BPM
  4. Notes sections - One per difficulty/style

​
Basic Template

#TITLE:Song Title;
#SUBTITLE:;
#ARTIST:Artist Name;
#TITLETRANSLIT:;
#SUBTITLETRANSLIT:;
#ARTISTTRANSLIT:;
#GENRE:;
#CREDIT:Charter Name;
#BANNER:banner.png;
#BACKGROUND:background.png;
#LYRICSPATH:;
#CDTITLE:;
#MUSIC:song.ogg;
#OFFSET:0.000;
#SAMPLESTART:45.000;
#SAMPLELENGTH:12.000;
#SELECTABLE:YES;
#BPMS:0.000=140.000;
#STOPS:;
#BGCHANGES:;

//---------------dance-single - ----------------
#NOTES:
     dance-single:
     :
     Beginner:
     1:
     0.105,0.105,0.105,0.105,0.105:
0000
0000
0000
0000
;

​
Song Metadata Tags

Format: #TITLE:text;The main title of the song.
#TITLE:MAX 300;
Format: #SUBTITLE:text;Subtitle or remix name. Often used for mix/version information.
#SUBTITLE:(Super-Max-Me Mix);
Format: #ARTIST:text;The song artist or composer.
#ARTIST:Omega;
Format: #TITLETRANSLIT:text;Romanized/transliterated version of the title for non-Latin scripts.
#TITLETRANSLIT:Sakura;
Format: #SUBTITLETRANSLIT:text;Romanized/transliterated subtitle.
Format: #ARTISTTRANSLIT:text;Romanized/transliterated artist name.
Format: #GENRE:text;Music genre for categorization.
#GENRE:Dance;
Format: #CREDIT:text;Chart author or credits.
#CREDIT:Stepped by Username;

​
Media File Tags

Format: #MUSIC:filename;Path to the audio file (MP3, OGG, WAV).
#MUSIC:song.ogg;
Path is relative to the simfile directory.
Format: #BACKGROUND:filename;Path to the background image.
#BACKGROUND:bg.jpg;
Format: #CDTITLE:filename;Path to CD title graphic (typically 64x40 pixels).
#CDTITLE:cdtitle.png;
Format: #LYRICSPATH:filename;Path to lyrics file (.LRC format).
#LYRICSPATH:song.lrc;

​
Timing Tags

Format: #OFFSET:seconds;The number of seconds to wait before the first beat. Can be negative.
#OFFSET:0.250;
#OFFSET:-0.500;  // Audio starts before beat 0
How to find the offset:
  1. Find when the first beat occurs in the audio file
  2. Use that time as the offset
  3. If the first beat is at 0.5 seconds, use #OFFSET:0.500;
Format: #BPMS:beat=bpm,beat=bpm,...;BPM (tempo) changes throughout the song.
#BPMS:0.000=140.000;  // Single BPM
#BPMS:0.000=120.000,64.000=180.000,128.000=120.000;  // Multiple changes
  • First value is always at beat 0.000
  • Beat numbers use decimal precision
  • BPM can be decimal (e.g., 128.500)
Format: #STOPS:beat=seconds,beat=seconds,...;Freezes/stops where scrolling pauses but music continues.
#STOPS:64.000=0.500,128.000=1.000;
This stops scrolling for 0.5 seconds at beat 64, and 1.0 seconds at beat 128.
#FREEZES is an alias for #STOPS - they work identically.
Format: #DELAYS:beat=seconds,beat=seconds,...;Delays where both scrolling and music pause.
#DELAYS:96.000=0.250;
Unlike stops, delays pause the music playback as well.
Format: #TIMESIGNATURES:beat=numerator=denominator,...;Time signature changes throughout the song.
#TIMESIGNATURES:0.000=4=4;  // 4/4 time
#TIMESIGNATURES:0.000=4=4,64.000=3=4,96.000=4=4;  // Multiple changes
Format: #TICKCOUNTS:beat=ticks,beat=ticks,...;Number of ticks per beat for hold notes.
#TICKCOUNTS:0.000=4;
Default is 4. Higher values make holds more precise.

​
Display Tags

Format: #DISPLAYBPM:value; or #DISPLAYBPM:min:max; or #DISPLAYBPM:*;How to display the BPM on the song selection screen.
#DISPLAYBPM:140.000;           // Show constant 140 BPM
#DISPLAYBPM:120.000:180.000;   // Show range 120-180
#DISPLAYBPM:*;                 // Show as random/variable
Format: #SAMPLESTART:seconds;Time in the song to start the preview on the song selection screen.
#SAMPLESTART:45.000;
Format: #SAMPLELENGTH:seconds;Length of the preview in seconds.
#SAMPLELENGTH:12.000;
Format: #SELECTABLE:YES; or #SELECTABLE:NO;Whether the song can be selected.
#SELECTABLE:YES;

​
Advanced Tags

Format: #BGCHANGES:beat=file=rate=transition=effect,...;Background changes/animations during gameplay.
#BGCHANGES:0.000=bg1.png=1.000=0=0,
64.000=bg2.png=1.000=1=StretchNoLoop;
Parameters:
  • beat - When to change
  • file - Image/video filename
  • rate - Animation rate multiplier
  • transition - Transition type (0-2)
  • effect - Effect name (StretchNoLoop, etc.)
Format: Same as #BGCHANGESForeground changes (displayed on top of gameplay).
Format: #KEYSOUNDS:file1,file2,...;List of keysound files to use with note keysounds.
#KEYSOUNDS:kick.ogg,snare.ogg,hat.ogg;
Format: #ATTACKS:TIME=time:LEN=length:MODS=modifiers,...;Course mode attacks/modifiers.
#ATTACKS:TIME=10.0:LEN=5.0:MODS=2x,TIME=20.0:LEN=3.0:MODS=Drunk;
Format: #INSTRUMENTTRACK:file1,file2,...;Additional instrument tracks for games like Guitar Hero.
#INSTRUMENTTRACK:guitar.ogg,bass.ogg;

​
#NOTES Section

Each chart is defined in a #NOTES: section with the following format: 
#NOTES:
     dance-single:           // Steps type
     Description:            // Chart description/author
     Beginner:               // Difficulty
     1:                      // Meter (difficulty rating)
     0.105,0.105,0.105,0.105,0.105:  // Radar values
// Note data follows
0000
1000
0100
0010
,
1001
0000
0110
0000
;

​
Notes Section Parameters

The game mode/style:
  • dance-single - 4-panel single
  • dance-double - 8-panel double
  • dance-couple - 8-panel couple (2 players)
  • dance-solo - 6-panel solo
  • pump-single - 5-panel single (Pump)
  • pump-double - 10-panel double (Pump)
  • pump-couple - 10-panel couple (Pump)
Chart description or author. Can be blank.
Chart by Username
Difficulty slot:
  • Beginner
  • Easy
  • Medium
  • Hard
  • Challenge
  • Edit
Numeric difficulty rating (1-20+).
1      // Beginner
5      // Easy
10     // Medium/Hard
15+    // Challenge
Five comma-separated values (stream, voltage, air, freeze, chaos).
0.105,0.105,0.105,0.105,0.105
StepMania calculates these automatically - usually left as defaults.

​
Note Data Format

​
Note Characters

For dance-single (4 columns: Left, Down, Up, Right):
  • 0 - No note
  • 1 - Normal note
  • 2 - Hold head (start of hold)
  • 3 - Hold/roll tail (end of hold)
  • 4 - Roll head (start of roll)
  • M - Mine (avoid this)
  • K - Keysound note (plays keysound)
  • L - Lift note (release foot)
  • F - Fake note (doesn’t judge)

​
Measure Structure

Notes are organized into measures, separated by commas: 
0000    // 4th note (quarter note)
1000
0100
0010
,       // Measure separator
0001
0000
1010
0101
;
  • Each line represents a subdivision of a measure
  • 4 lines = quarter notes (4ths)
  • 8 lines = 8th notes
  • 16 lines = 16th notes
  • 12 lines = 12th notes (triplets)
  • 24 lines = 24th notes
  • Can use any number of lines per measure

​
Examples

1000    // Left on beat 0
0100    // Down on beat 1
0010    // Up on beat 2
0001    // Right on beat 3

1000    // Left on beat 0
0000
0100    // Down on beat 0.5
0000
0010    // Up on beat 1
0000
0001    // Right on beat 1.5
0000

1010    // Left + Up jump
0000
0101    // Down + Right jump
0000

2000    // Hold head (Left)
0000
0000
3000    // Hold tail
,
0200    // Down hold head
0000
0300    // Down hold tail (2 beats)
0000

1000    // Left note
0M00    // Mine on Down (avoid it!)
0010    // Up note
00M0    // Mine on Right

​
Complete Example

Here’s a complete .SM file: 
#TITLE:Example Song;
#SUBTITLE:;
#ARTIST:Example Artist;
#TITLETRANSLIT:;
#SUBTITLETRANSLIT:;
#ARTISTTRANSLIT:;
#GENRE:Dance;
#CREDIT:Stepped by Charter;
#BANNER:banner.png;
#BACKGROUND:background.jpg;
#LYRICSPATH:;
#CDTITLE:;
#MUSIC:song.ogg;
#OFFSET:0.000;
#SAMPLESTART:45.000;
#SAMPLELENGTH:12.000;
#SELECTABLE:YES;
#BPMS:0.000=140.000;
#STOPS:;
#DELAYS:;
#BGCHANGES:0.000=background.jpg=1.000=0=0;

//---------------dance-single - Easy----------------
#NOTES:
     dance-single:
     :
     Easy:
     5:
     0.200,0.150,0.100,0.000,0.100:
1000
0000
0100
0000
,
0010
0000
0001
0000
,
1010
0000
0101
0000
;

//---------------dance-single - Medium----------------
#NOTES:
     dance-single:
     :
     Medium:
     10:
     0.300,0.250,0.150,0.000,0.200:
1000
0100
0010
0001
,
1000
0000
0100
0000
0010
0000
0001
0000
;

​
Tips and Best Practices

  • Use consistent indentation for readability
  • Add comments with // to label chart sections
  • Keep related songs in their own folders
  • Test charts in-game frequently
  • Use appropriate difficulty ratings
  • Don’t forget the semicolon (;) at the end of tags
  • Audio offset can be tricky - test thoroughly
  • BPM changes must be in chronological order
  • Ensure all referenced files exist

​
Next Steps

SSC Format

Learn about the modern .SSC format with advanced features

Other Formats

Explore legacy simfile formats

Build docs developers (and LLMs) love

Get started for freeTalk to us