Skip to content

Overview

song.ini files are used for storing song metadata. Originally they were used for .mid, but they have been extended to .chart files as well.

Basic Structure

A song.ini file starts off with a [song]/[Song] section header. Following this header are the song.ini's tags.

Tags

Tags are a key-value pair that store each metadata entry, stored in this general format:

<Key> = <Value>

  • Key is the name of the value.
  • Value is the stored value. The data type depends on the key. Some tags may contain multiple values.

The equals sign may, but is not required to be, padded by a space on each side, but it is recommended to pad it as not all games/programs support song.ini files without the padding.

Tags can be listed in any order, and might have inconsistent capitalization to the tag names listed below.

Various value types are specified in this document:

  • number fields are whole numbers typically written in base 10.
  • A value of -1 may be used in some number fields to indicate that there is no value set.
  • float fields allow decimal places and are also written in base 10.
  • string fields typically don't include quotes. Strings that require use quotes will be marked as such.
  • Note that there may be formatting tags present in these tags, such as <color=#00FF00>. When parsing, make sure to trim these out if you don't use them.
  • boolean fields can be either True/False (or true/false), or 0/1 (only a couple booelan tags do this, but simplest to specify it for all).
  • file name fields specify a file to be loaded for some purpose.
  • MIDI note/MIDI velocity - Any MIDI note/velocity number. Notes go from 0 to 127, velocities go from 1 to 127 (0 is equivalent to a Note Off, and so is not valid in these values).

Any additional formats needed are specified where relevant.

Comments

Comments are typically delimited using either a semicolon ; or a hash #. Usually they are only found in song.ini files generated by a tool.

Some .ini parsers only support one symbol or the other. Additionally, they might only support comments that are a line of their own, while others may allow trailing comments. Usually song.ini comments are on a line of their own, but being an easily editable text file, it's better to be safe than sorry.