How to Add Custom Charts to OpenTaiko: TJA Folder Setup

This guide explains how to add a .tja chart to OpenTaiko or TJAPlayer3: how to organize folders, how to set up categories, and what to check when songs don't appear or audio doesn't match.

1. Folder structure

Put each song in its own folder, then place that folder inside the simulator's Songs directory. In OpenTaiko and TJAPlayer3 the Songs directory is typically a folder named Songs inside the game folder; the exact location and whether it can be changed depends on the version and settings — refer to the documentation for the version you use.

Songs/
  MyCharts/
    box.def
    MySong/
      MySong.tja
      MySong.ogg

Here MyCharts is an optional category folder (see section 3) and MySong is the folder for this song. Different difficulties for the same song are written in a single .tja file separated by COURSE; multiple files are not needed.

For the meaning of COURSE and other header fields, see TJA format guide.

When you unzip a TaikoForge download, the .tja and audio file are at the same level. If they land scattered directly in the extraction location, create a folder, move them into it, then place the folder in the Songs directory.

2. Keep the .tja and audio file in the same folder

The WAVE field in the .tja specifies the audio filename. The simulator looks for that file in the same folder as the .tja. Both must be in the same folder, and the filename including extension must match exactly.

MySong/
  MySong.tja    ← WAVE:MySong.ogg
  MySong.ogg

The WAVE field is at the top of the .tja and can be checked or edited with any text editor. When switching to a different audio format, remember to update the WAVE filename as well. Supported formats depend on the simulator version; OGG is the most common choice.

3. Category folders: box.def and genre.ini

You can create subfolders inside the Songs directory to organize songs; the song select screen treats them as categories.

box.def is a plain-text config file placed inside a category folder. Commands starting with # configure the category, for example the category name:

#TITLE:My Charts

Available commands depend on the version. genre.ini is also a category-related config file; its purpose and syntax vary by simulator and version, and not every version reads it.

Neither file is required: without them, songs still load, just without custom category settings. For details, refer to the documentation bundled with the simulator you use.

4. Reload the song list

After placing the folder, the simulator needs to rescan for new songs to appear. From the song-select screen, reload the song list (the menu option name varies by version), or restart the game.

5. Song does not appear on the song select screen

• Wrong location: make sure the folder is inside the song directory the simulator actually reads, not somewhere else in the game folder.
• File still in the archive: unzip it first — the simulator does not read .tja files inside a zip.
• Wrong file extension: Windows hides extensions by default, so a file saved as MySong.tja.txt looks like MySong.tja. Open File Explorer's View settings to show extensions and confirm the file actually ends in .tja.
• Song list not reloaded yet: see the previous section.
• Garbled or missing title: the file's encoding may not match what the simulator expects — see the encoding section of TJA format guide.
• Chart content issue: if #START, #END or the BPM field is missing, the simulator may skip the whole file. Load it in Play TJA Charts Online first to confirm it can be read.

6. Audio doesn't match or there is no sound

• No audio at all: the filename in the WAVE field does not match the actual audio file, or that format is not supported by the version. The filename must match exactly, including the extension; on Linux, case also matters.
• Notes and music are offset by the same amount from start to finish: this is an OFFSET issue — see Adjust OFFSET and BPM.
• In sync at the start but drifting further off toward the end: this is a BPM issue — see Adjust OFFSET and BPM.
• Switched to a different audio version: different sources of the same song often have different intro lengths and may be trimmed differently at the start or end. After swapping audio, OFFSET usually needs to be adjusted for the chart to line up.