Skip to main content
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:
A whole song folder can also be packed into one file. See .sng files.

​
Files

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 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 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:
  • 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.
  • 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

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.
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.
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.
A scanner takes a .chart song’s metadata from its [Song] section, and hashes a .mid song’s metadata as unset, as Clone Hero’s HashScanTool and scan-chart do: see SongHash. 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.
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.
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.
Clone Hero loads both songs. YARG doesn’t look inside a song folder, so it doesn’t list the inner song.