> ## 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.

# Files in a song folder

> The files a song folder holds, their names and formats, and which one a scanner uses when there are several.

A song folder holds one song. **Required:** no song folder inside another. A scanner finds each of its files by name. A song folder in the recommended form:

```
My Song/
  notes.chart
  song.ini
  song.opus
  guitar.opus
  album.png
  background.jpg
  video.webm
```

A whole song folder can also be packed into one file. See [.sng files](/sng).

## Files

| File | Holds | |
| - | - | - |
| `notes.chart` or `notes.mid` | The chart: the gameplay data, such as notes and lyrics | **Required**: one of the two |
| `song.ini` | The song's metadata and parsing settings | **Required** |
| Audio files, such as `song.opus` | The song's audio, whole or in stems | **Required**: at least one. See [Audio](#audio) |
| `album.png` | The song's album art | **Recommended**. See [Art and video](#art-and-video) |
| `background.jpg` | An image shown behind the highway | See [Art and video](#art-and-video) |
| `video.webm` | A video shown behind the highway | See [Art and video](#art-and-video) |

A song folder should hold only files a game reads. Backups, editor projects and files the operating system adds, such as `desktop.ini`, `Thumbs.db` and `__MACOSX`, make the folder larger and do nothing. Some games read files this page doesn't name, such as YARG's `.aiff` audio, and its `_clean` and `_explicit` versions of some stems, such as `vocals_clean` and `vocals_1_explicit`; those are allowed.

### File names

**Required:** each file name in lowercase, as written on this page.

## The chart

The chart is `notes.chart` or `notes.mid`. [Syntax](/chart/syntax) gives the structure of a `.chart` file.

A song folder should hold only one chart.

**Edge case:** a scanner that finds both uses `notes.mid`.

## song.ini

**Required:** a `song.ini` file. It gives the song's metadata, such as its name and artist, and settings that change how the chart plays.

* A scanner reads only `song.ini`, and ignores any other `.ini` file.
* [song.ini syntax](/ini/reading-rules) gives the file's syntax and encoding. **Recommended:** UTF-8.

## Audio

A song's audio is one file, or several files called stems that are combined while playing. Each file's name says what it holds:

| Name | Holds |
| - | - |
| `song` | The audio that no other file holds, or the whole song when it's the only file. **Recommended** for a song without stems |
| `guitar` | Lead guitar |
| `rhythm` | Rhythm guitar, or the bass when there's no `bass` file |
| `bass` | Bass guitar |
| `keys` | Keys |
| `drums` | All of the drums |
| `drums_1` | The kick, and the snare, toms and cymbals when `drums_2` to `drums_4` don't hold them |
| `drums_2` | The snare, and the toms and cymbals when `drums_3` and `drums_4` don't hold them |
| `drums_3` | The toms, and the cymbals when there's no `drums_4` |
| `drums_4` | The cymbals |
| `vocals` | All of the vocals |
| `vocals_1` | The lead vocals |
| `vocals_2` | The second vocals |

* **Required:** at least one of these files.
* Each file is one of these names with the extension `.opus`, `.ogg`, `.mp3` or `.wav`. **Recommended:** `.opus`, at about 80 kbps: it's the smallest at the same quality. An `.ogg` file should be between 192 and 320 kbps.
* YARG also plays these names with the extension `.aiff`. Clone Hero doesn't, so a `.aiff` file isn't one of the song's audio files, though a folder may hold one: see [Files](#files).
* **Required:** at most one file for each name.
* A scanner plays every audio file it finds together at the same time. So a folder should not hold `drums` with the numbered `drums_` files, or `vocals` with the numbered `vocals_` files.

**Edge case: the whole song in `guitar`.** A common convention is to name a song's only audio file `guitar`. Alone, it plays as `song` does. Once any other stem is added, a full mix in `guitar` drops to 50% volume each time the player misses a guitar note, so the full mix belongs in `song`.

## Art and video

* **Album art:** `album.png`, `album.jpg` or `album.jpeg`, 512x512 pixels. **Recommended:** `.png`. Art that started as a JPEG, such as one downloaded from a store, stays `album.jpg`: converting it to PNG makes it larger without making it better. A file's extension should match its content.
* **Background images:** `.png`, `.jpg` or `.jpeg` images whose names start with `background`, such as `background.jpg` and `background2.png`, at least 1280x720 pixels. A folder may hold several. A scanner shows one of them, picked at random, each time the chart is played.
* **Background video:** `video.webm` is strongly **recommended**, with the VP8 codec: Clone Hero plays video through Unity, which decodes only VP8 in a `.webm` file on desktop platforms. A scanner also plays a video with another extension, such as `video.mp4`, where it can, but `.webm` is the only format every game plays on every platform. A scanner shows the video instead of the background image when a folder holds both.

**Edge case: album art size.** Clone Hero shows album art at 512x512, and resizes art of any other size when it loads it. 500x500, the size previously recommended, is still common.

**Edge case: several album art files.** A folder should hold only one. A scanner that finds several uses the first of `album.png`, `album.jpg` and `album.jpeg`.

**Edge case: a video in a subfolder.** When a song is played, Clone Hero also looks for the video in the song folder's subfolders, and plays the first one it finds. YARG, and scan-chart's video checks, look only in the song folder itself.

## Deprecated

* **`crowd` audio:** crowd noise and singing. Games supply their own crowd.
* **`preview` audio:** the excerpt the song list plays, which a scanner plays whole. Set `preview_start_time` and `preview_end_time` in `song.ini` instead.

## Invalid forms

<Accordion title="Two audio files with one name, such as guitar.ogg and guitar.opus">
  Games choose differently between them: YARG plays the first of `.opus`, `.ogg`, `.mp3` and `.wav`, and Clone Hero the last one in the folder listing. Every scanner then plays a different file. scan-chart reports it as `multipleAudio`, and the folder should keep one.
</Accordion>

<Accordion title="No audio file">
  A folder whose only audio is `preview`, `crowd` or `.aiff` files has no audio. Clone Hero loads the song without sound. From its code, it still plays `crowd` audio if there is one. YARG doesn't load the song, unless the folder has `crowd` audio or a stem in `.aiff`, such as `song.aiff`, which YARG counts as the song's audio. scan-chart reports it as `noAudio`.
</Accordion>

<Accordion title="A chart file with another name, such as song.mid">
  Clone Hero and YARG don't read it, so a folder with no `notes.chart` or `notes.mid` isn't a song there. YARG also reads `notes.midi` as a `.mid` chart. A scanner that reads such a file reads it as the chart only when the folder has no `notes.chart` or `notes.mid`, and prefers a `.mid` file, as scan-chart does, which reports `invalidChart`.
</Accordion>

<Accordion title="No song.ini">
  A scanner takes a `.chart` song's metadata from its [\[Song\] section](/chart/song), and hashes a `.mid` song's metadata as unset, as Clone Hero's HashScanTool and scan-chart do: see [SongHash](/hashes/songhash#metadata). Clone Hero loads a `.chart` folder without `song.ini`, and writes a `song.ini` into the folder. It doesn't load a `.mid` folder without one. YARG loads neither. scan-chart reports `noMetadata`.
</Accordion>

<Accordion title="A file name in another letter case, such as Song.ini">
  A scanner reads `song.ini` and the chart in any letter case, as scan-chart does. Clone Hero finds the chart only with a lowercase extension: it finds `Notes.mid`, but not `notes.MID`. It opens `song.ini`, album art and audio by their lowercase names. So on Windows, whose file system ignores letter case, it finds them in any letter case, and on other systems only in lowercase. YARG finds a file in any letter case when it scans. From its code, on a file system that doesn't ignore letter case, YARG then loads the chart only by its lowercase name. scan-chart reports the chart and `song.ini` as `invalidChart` and `invalidIni`. It doesn't read audio, album art or video in another letter case: it reports audio as `invalidAudio`, and album art, background images and video as `fileNameCase`. `fixIssues` renames a file it reports as `fileNameCase` in lowercase.
</Accordion>

<Accordion title="Two names that differ only in letter case">
  On Windows, the two can't exist in one folder at all. On other systems, a scanner reads the one in lowercase, as scan-chart does, and as Clone Hero does for `song.ini`. Which chart Clone Hero reads depends on the order the file system lists them in. YARG skips every file whose name is the same as another's in lowercase, so `song.ini` and `Song.ini` together hide both.
</Accordion>

<Accordion title="A song folder inside a song folder">
  Clone Hero loads both songs. YARG doesn't look inside a song folder, so it doesn't list the inner song.
</Accordion>


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