> ## Documentation Index
> Fetch the complete documentation index at: https://chart-spec.enchor.us/llms.txt
> Use this file to discover all available pages before exploring further.

# [Song]

> The metadata and resolution in a .chart file's [Song] section.

`[Song]` is a `.chart` file's first section. It gives the chart's resolution, and may repeat metadata from `song.ini`, such as the song's name and artist:

```text theme={null}
[Song]
{
  Name = "Song Name"
  Artist = "Artist"
  Charter = "Charter"
  Year = "2002"
  Resolution = 192
}
```

Each line names one value, as [Named entries](/chart/syntax#named-entries) describes. Keys are case-sensitive.

## Resolution

`Resolution` is the number of ticks in a beat. **Required:** one `Resolution` line, whose value is a whole number from 1 up, written in digits without quotation marks.

## Metadata

`song.ini` holds the song's metadata. `[Song]` may repeat any of these keys:

| Key | Value | song.ini key |
| - | - | - |
| `Name` | The song's title | `name` |
| `Artist` | The song's artist(s) | `artist` |
| `Album` | The album the song is on | `album` |
| `Genre` | The song's genre | `genre` |
| `Year` | The year the song's album was released, or for a live recording the year it was performed. **Recommended:** the year alone, as in `Year = "2002"` | `year` |
| `Charter` | The names of the people who charted the song | `charter` |
| `Offset` | How far the chart is moved against the audio, in seconds. A higher value makes every note come later. **Recommended:** 0, or no line. See [Deprecated](#deprecated) | `delay`, in milliseconds |
| `PreviewStart` | Where the song list's preview starts, in seconds | `preview_start_time`, in milliseconds |
| `PreviewEnd` | Where the preview ends, in seconds | `preview_end_time`, in milliseconds |
| `Length` | The song's length, in seconds. No scanner reads it | `song_length`, in milliseconds |
| `Difficulty` | The difficulty of the whole song, a whole number. **Recommended:** from 0 to 6, or up to 10 for a very hard chart. `diff_band` is recommended only for a chart with more than one instrument part: see [Difficulties](/ini/metadata#difficulties) | `diff_band` |

* **Text** is written in quotation marks: `Name = "Song Name"`.
* **Times** are written in seconds, as digits with an optional `-` before them and an optional decimal part, without quotation marks: `PreviewStart = 45.5`. **Required:** this form. **Recommended:** at most three decimals.
* **Required:** a `Name` that is the song's title, not `TEMPO TRACK` or `midi_export`, which some converters wrote in its place.

**Edge case: times in milliseconds.** Scanners change a time to milliseconds differently, so it can differ by 1 millisecond between them. Clone Hero and scan-chart round up, and YARG rounds down. A decimal time isn't stored exactly, so `PreviewStart = 1.001` is 1,002 milliseconds in Clone Hero and 1,000 in YARG. The `song.ini` keys hold milliseconds, so they're exact.

**Edge case: `Year` after `, `.** Older charts, and charts Moonscraper saves, write `Year = ", 2002"`: the comma made the year look better in Guitar Hero III. A scanner removes a leading `, `, so it means the same as `Year = "2002"`. YARG also removes a leading `,` without the space. scan-chart's exporter writes `Year` without the `, `. When it saves an edited song, it keeps an existing line's form.

**Edge case: `PreviewEnd = 0`.** It means there's no preview end: a preview can't end at the start of the song. Moonscraper writes it in every chart.

## \[Song] and song.ini

A song folder holds a `song.ini` file. See [Files in a song folder](/song-folders). **Required:** when both `[Song]` and `song.ini` set a key from the table, the same value in both. Times are compared in milliseconds, and `Year` without its leading `, `.

A scanner reads the metadata from `song.ini`:

* It takes the name, artist, album, genre, year and charter from `song.ini` alone, even when `song.ini` leaves one of them out.
* It takes `Offset`, `PreviewStart` and `PreviewEnd` from `[Song]` only when `song.ini` doesn't set `delay`, `preview_start_time` or `preview_end_time`. A `delay` of 0 and a `preview_end_time` of 0 count as not set.
* It may ignore `Difficulty`, as Clone Hero and scan-chart do. YARG takes it as `diff_band` when `song.ini` doesn't set `diff_band`, or sets it to 0.

## Deprecated

* **An `Offset` other than 0.** Line the notes up with the tempo map and the audio's leading silence instead. A scanner still applies `Offset`, but only when `song.ini` doesn't set `delay`.

## Ignored

A scanner ignores every other key. An exporter may keep them as written. Older chart editors wrote some of them:

* **Audio file names,** such as `MusicStream` and `GuitarStream`. Games find the audio by file name instead. See [Audio](/song-folders#audio). A new chart leaves them out: a chart editor keeps a charter's choice of audio file in its own settings. Moonscraper still finds a `.chart`'s audio only through these keys.
* **`Player2`, `MediaType` and others,** which no game reads.

## Invalid forms

<Accordion title="No Resolution">
  A scanner reads a file with no `[Song]` section, or no `Resolution` in it, with a resolution of 192. scan-chart's saving adds `Resolution = 192`.
</Accordion>

<Accordion title="A Resolution that isn't a whole number from 1 up, in digits">
  A scanner reads the value's leading digits, so `Resolution = 480.5` reads as 480. YARG's chart loader reads every character as a digit, so `Resolution = 192.5` is 19185 there. A scanner refuses a file whose `Resolution` doesn't start with a digit, or is 0.
</Accordion>

<Accordion title="A Resolution in quotation marks">
  A scanner removes the quotation marks, so `Resolution = "480"` reads as 480. YARG's song list reads a quoted value as 0, and doesn't list the song. scan-chart saves the line as it is.
</Accordion>

<Accordion title="Resolution written more than once">
  A scanner uses the last one, as Clone Hero, scan-chart and YARG's song list do. YARG's chart loader uses the first.
</Accordion>

<Accordion title="A key written more than once">
  A scanner uses the first line of the key that has a value. YARG's song list uses the last line, even an empty one.
</Accordion>

<Accordion title="A time in another form, such as Offset = 1e-1 or Offset = &#x22;0.1&#x22;">
  Clone Hero and scan-chart read an exponent, a `+` and quotation marks around the number, so both of these are 0.1 seconds. YARG reads only a sign, digits and a decimal point, so it reads `1e-1` as 1 second, and a quoted time as 0. A decimal comma, such as `Offset = 0,1`, gives no time in Clone Hero and scan-chart. scan-chart saves the line as it is. See [Nonstandard files](/scan-chart/nonstandard-files#lines-read-as-written).
</Accordion>

<Accordion title="No song.ini">
  A scanner takes the metadata from the keys of the table in `[Song]`, except `Length`, and may ignore `Difficulty`: scan-chart reads it as `diff_band`, and Clone Hero ignores it. YARG doesn't list the song. See [Files in a song folder](/song-folders#invalid-forms).
</Accordion>

<Accordion title="[Song] and song.ini giving different values">
  A scanner uses `song.ini`, as described above. When scan-chart saves an edited song, `[Song]` takes `song.ini`'s values. A key that only `[Song]` sets is removed from it, except `Offset`, `PreviewStart` and `PreviewEnd`, which are copied into `song.ini`, since scanners read them when `song.ini` doesn't set them.
</Accordion>

<Accordion title="Name = &#x22;TEMPO TRACK&#x22; or Name = &#x22;midi_export&#x22;">
  Some converters wrote these instead of the song's name. A scanner ignores that line and every metadata line after it, as Clone Hero and scan-chart do. Clone Hero doesn't list such a song when its folder has no `song.ini`. YARG reads the line as the song's name. scan-chart saves the section as it is.
</Accordion>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.