Known properties

Known properties refer to properties of simfiles and their charts that the current stable version of StepMania actively uses. These are the properties that simfile exposes as attributes on simfile and chart objects. They are also the only properties that StepMania’s built-in editor will preserve when saving a simfile; unknown properties are liable to be deleted if saved by the StepMania editor.

When working with known properties, you should prefer to use attributes (e.g. sim.title, chart.stepstype) rather than indexing into the underlying dictionary (e.g. sim['TITLE'], chart['STEPSTYPE']). While these are functionally equivalent in many cases, attributes generally behave closer to how StepMania interprets simfiles:

• If a property is missing from the simfile, accessing the attribute returns None instead of throwing a KeyError. StepMania generally treats missing properties as if they had an empty or default value, so it’s nice to be able to handle this case without having to catch exceptions everywhere.

• StepMania supports a few legacy aliases for properties, and attributes make use of these aliases when present. For example, if a simfile contains a FREEZES property instead of the usual STOPS, sim.stops will use the alias in the backing dictionary (both for reads and writes!), whereas sim['STOPS'] will throw a KeyError. This lets you write cleaner code with fewer special cases for old simfiles.

• Attributes are implicitly spell-checked: misspelling a property like sim.artistranslit will consistently raise an AttributeError, and may even be flagged by your IDE depending on its Python type-checking capabilities. By contrast, reading from sim['ARTISTRANSLIT'] will generally raise the more vague KeyError exception, and writing to such a field would create a new, unknown property in the simfile, which is probably not what you wanted. Furthermore, your IDE would have no way to know the string property is misspelled.

With that said, there are legitimate use cases for indexing. String keys are easier when you need to operate on multiple properties generically, and they’re the only option for accessing “unknown properties” like numbered BGCHANGES and properties only used by derivatives of StepMania. When dealing with property string keys, consider using the .get method from the underlying dictionary to handle missing keys gracefully.

What are the known properties?

These are the known properties for simfiles:

String key	Attribute	SMSimfile	SSCSimfile
TITLE	title	✓	✓
SUBTITLE	subtitle	✓	✓
ARTIST	artist	✓	✓
TITLETRANSLIT	titletranslit	✓	✓
SUBTITLETRANSLIT	subtitletranslit	✓	✓
ARTISTTRANSLIT	artisttranslit	✓	✓
GENRE	genre	✓	✓
CREDIT	credit	✓	✓
BANNER	banner	✓	✓
BACKGROUND	background	✓	✓
LYRICSPATH	lyricspath	✓	✓
CDTITLE	cdtitle	✓	✓
MUSIC	music	✓	✓
OFFSET	offset	✓	✓
BPMS	bpms	✓	✓
STOPS	stops	✓	✓
FREEZES [1]	stops	✓
DELAYS	delays	✓	✓
TIMESIGNATURES	timesignatures	✓	✓
TICKCOUNTS	tickcounts	✓	✓
INSTRUMENTTRACK	instrumenttrack	✓	✓
SAMPLESTART	samplestart	✓	✓
SAMPLELENGTH	samplelength	✓	✓
DISPLAYBPM	displaybpm	✓	✓
SELECTABLE	selectable	✓	✓
BGCHANGES	bgchanges	✓	✓
ANIMATIONS [1]	bgchanges	✓	✓
FGCHANGES	fgchanges	✓	✓
KEYSOUNDS	keysounds	✓	✓
ATTACKS	attacks	✓	✓
VERSION	version		✓
ORIGIN	origin		✓
PREVIEWVID	previewvid		✓
JACKET	jacket		✓
CDIMAGE	cdimage		✓
DISCIMAGE	discimage		✓
PREVIEW	preview		✓
MUSICLENGTH	musiclength		✓
LASTSECONDHINT	lastsecondhint		✓
WARPS	warps		✓
LABELS	labels		✓
COMBOS	combos		✓
SPEEDS	speeds		✓
SCROLLS	scrolls		✓
FAKES	fakes		✓

And these are the known properties for charts:

String key	Attribute	SMChart	SSCChart
STEPSTYPE	stepstype	✓	✓
DESCRIPTION	description	✓	✓
DIFFICULTY	difficulty	✓	✓
METER	meter	✓	✓
RADARVALUES	radarvalues	✓	✓
NOTES	notes	✓	✓
NOTES2 [1]	notes		✓
CHARTNAME	chartname		✓
CHARTSTYLE	chartstyle		✓
CREDIT	credit		✓
MUSIC	music		✓
BPMS	bpms		✓
STOPS	stops		✓
DELAYS	delays		✓
TIMESIGNATURES	timesignatures		✓
TICKCOUNTS	tickcounts		✓
COMBOS	combos		✓
WARPS	warps		✓
SPEEDS	speeds		✓
SCROLLS	scrolls		✓
FAKES	fakes		✓
LABELS	labels		✓
ATTACKS	attacks		✓
OFFSET	offset		✓
DISPLAYBPM	displaybpm		✓

[1] (1,2,3)

These keys are aliases supported by StepMania. The attribute will only use the alias if it’s present in the backing dictionary and the standard name is not.

Known properties supported by both the SM and SSC formats are documented in BaseSimfile and BaseChart. These are exactly the known properties for SMSimfile and SMChart. The SSC format then adds additional known properties on top of the base set.

Here is all of the relevant documentation:

class simfile.base.BaseSimfile(*, file: TextIO | Iterator[str] | None = None, string: str | None = None, strict: bool = True)

A simfile, including its metadata (e.g. song title) and charts.

Metadata is stored directly on the simfile object through a dict-like interface. Keys are unique (if there are duplicates, the last value wins) and converted to uppercase.

Additionally, properties recognized by the current stable version of StepMania are exposed through lower-case properties on the object for easy (and implicitly spell-checked) access. The following known properties are defined:

• Metadata: title, subtitle, artist, titletranslit, subtitletranslit, artisttranslit, genre, credit, samplestart, samplelength, selectable, instrumenttrack, timesignatures

• File paths: banner, background, lyricspath, cdtitle, music

• Gameplay events: bgchanges, fgchanges, keysounds, attacks, tickcounts

• Timing data: offset, bpms, stops, delays

If a desired simfile property isn’t in this list, it can still be accessed as a dict item.

By default, the underlying parser will throw an exception if it finds any stray text between parameters. This behavior can be overridden by setting strict to False in the constructor.

class simfile.base.BaseChart

One chart from a simfile.

All charts have the following known properties: stepstype, description, difficulty, meter, radarvalues, and notes.

class simfile.ssc.SSCSimfile(*, file: TextIO | Iterator[str] | None = None, string: str | None = None, strict: bool = True)

SSC implementation of BaseSimfile.

Adds the following known properties:

• SSC version: version

• Metadata: origin, labels, musiclength, lastsecondhint

• File paths: previewvid, jacket, cdimage, discimage, preview

• Gameplay events: combos, speeds, scrolls, fakes

• Timing data: warps

class simfile.ssc.SSCChart

SSC implementation of BaseChart.

Unlike SMChart, SSC chart metadata is stored as key-value pairs, so this class allows full modification of its backing OrderedDict.

Adds the following known properties:

• Metadata: chartname, chartstyle, credit, timesignatures

• File paths: music

• Gameplay events: tickcounts, combos, speeds, scrolls, fakes, attacks

• Timing data: bpms, stops, delays, warps, labels, offset, displaybpm