JBT File Format Specification v1.0

JBT File Format Specification v1.0
by Jeffrey Paine

The JBT file format is a standard for jubeat simulation files. This document contains information on the file format, for those wanting to create their own JBT files, and details on how jubeat simulators should read JBT files, for jubeat simulator authors.

This document details version 1.0 of the JBT file format.

A JBT file is a standard ANSI-encoded text file. The lines can be placed in any order, and any lines that can't be read by the simulator will be ignored, to allow for commenting or meta-tags. All valid lines must have no extra space at the beginning or end of the line.

Required information

The following lines are required for a jubeat simulator to open a JBT file:

VER:1.0
This line declares the version of the JBT file format this file was written for. If you're following this document, the version number should always be 1.0. The version number can contain up to 2147483643 characters. If this limit is exceeded, the extra characters will be truncated. If this line is declared more than once, only the first declaration will be acknowledged.

LENGTH:113192
This line declares the length of the song in milliseconds, minus the offset. Once this length has been reached, the simulator will stop playing the song and display the results screen. In this example, the song will end 113,192 milliseconds after the first measure begins. The length can range from 1 millisecond to 2147483647 milliseconds. If this limit is exceeded, the line will be ignored. If this line is declared more than once, only the first declaration will be acknowledged.

SONG:4x4.mp3
This line declares the audio file containing the song to be played. The path is relative to the directory the JBT file is stored in. In this example, the simulator will load the file 4x4.mp3 in the same directory as the JBT file. The song file can contain up to 2147483642 characters. If this limit is exceeded, the extra characters will be truncated. If the file does not exist, this line will be ignored. If this line is declared more than once, only the first declaration will be acknowledged.

In addition to the above lines, at least one difficulty must be declared, and at least one BPM must be declared. See below for more information.

Optional information

The following lines include optional additional information for the jubeat simulator:

TITLE:4x4
This line declares the title of the song. In this example, the title of the song is 4x4. The song title can contain up to 2147483641 characters. If this limit is exceeded, the extra characters will be truncated. If this line is omitted, the song title will default to a blank string. If this line is declared more than once, only the first declaration will be acknowledged.

ARTIST:Jeffrey Paine
This line declares the artist of the song. In this example, the artist of the song is Jeffrey Paine. The artist name can contain up to 2147483640 characters. If this limit is exceeded, the extra characters will be truncated. If this line is omitted, the artist name will default to a blank string. If this line is declared more than once, only the first declaration will be acknowledged.

OFFSET:101
This line declares how long into the song, in milliseconds, the first measure begins. In this example, the first measure begins 101 milliseconds after the song begins. The offset can be negative, in which case the first measure will begin before the song starts playing. The offset can range from -2147483648 milliseconds to 2147483647 milliseconds. If this limit is exceeded, the line will be ignored. If this line is omitted, the offset will default to 0 milliseconds. If this line is declared more than once, only the first declaration will be acknowledged.

COVER:4x4.bmp
This line declares the image file containing the cover image of the song. The path is relative to the directory the JBT file is stored in. In this example, the simulator will load the file 4x4.bmp in the same directory as the JBT file. The cover file can contain up to 2147483641 characters. If this limit is exceeded, the extra characters will be truncated. If this line is omitted, the cover file will default to a generic image. If the file does not exist, this line will be ignored. If this line is declared more than once, only the first declaration will be acknowledged.

PREVIEW:4x4 preview.mp3
This line declares the audio file containing the preview of the song. The path is relative to the directory the JBT file is stored in. In this example, the simulator will load the file 4x4 preview.mp3 in the same directory as the JBT file. The preview file can contain up to 2147483639 characters. If this limit is exceeded, the extra characters will be truncated. If this line is omitted, the preview will not play. If the file does not exist, this line will be ignored. If this line is declared more than once, only the first declaration will be acknowledged.

In addition to the above lines, you can also optionally declare additional BPMs for BPM changes, or stop lengths for stops in the song. See below for more information.

Note structure

Before you can start adding notes to your song, you must first declare a difficulty to place the notes in:
BASIC:1
The tag must be one of three difficulties, BASIC, ADVANCED, or EXTREME, and the value is the displayed difficulty level. The difficulty level can range from 1 to 2147483647. If this limit is exceeded, the line will be ignored. After a difficulty has been declared, all notes you add will be assigned to that difficulty, until you declare a new difficulty. If you declare a difficulty multiple times, the first declared difficulty level will be acknowledged, but all notes declared under all duplicate difficulties will be acknowledged.

Once you have declared a difficulty, you can start adding notes:
1:01020304
The tag corresponds to the measure in which the notes will be played. In this example, the notes will be played in measure 1. The measure can range from 1 to 2147483647. If this limit is exceeded, the line will be ignored.

Let's break down the value of the line:
01020304
This corresponds to four notes in the measure, each one with a two-digit code:
01 02 03 04
Each code corresponds to a position on the jubeat board:

01 02 03 04

05 06 07 08

09 10 11 12

13 14 15 16

The notes will be spread evenly throughout the measure. In this example, there are four notes, so each note will correspond to a quarter note. The first note will play at the beginning of the measure, the second note will play 1/4 into the measure, the third note will play 1/2 into the measure, and the fourth note will play 3/4 into the measure. The notes that play correspond to the two-digit code assigned to them. If an invalid code is used (such as 00), no note will play. For instance:
01 00 00 04
In this example, the first note will play at the beginning of the measure, no note will be played 1/4 into the measure, no note will be played 1/2 into the measure, and the fourth note will play 3/4 into the measure.

If a measure is declared incorrectly, so that there's an odd number of digits in the value, an extra zero will be added to the end of the line and the line should be processed as normal. For instance:
1:0120304
The above line contains only 7 digits in the value. The line will be treated as such:
1:01203040
The line still contains invalid values, but it can now be properly processed.

The number of notes in a measure must be a factor of 192 (1, 2, 3, 4, 6, 8, 12, 16, 24, 32, 48, 64, 96, or 192). If a measure contains over 192 notes, it will be truncated to contain only 192 notes. If a measure does not contain a valid number of notes, extra 00 notes will be added until the measure contains a valid number of notes. For instance:
1:01020304050607
This example only contains 7 notes. The line will be treated as such:
1:0102030405060700
The timing may not be what the author of the file intended, but the line can now be properly processed.

A measure can be declared up to 16 times, to allow for chords. For instance:
1:01020304
1:0507
This example will play notes 01 and 05 at the beginning of the measure, note 02 1/4 into the measure, notes 03 and 07 1/2 into the measure, and note 04 3/4 into the measure. If a measure is declared more than 16 times in a single difficulty, all subsequent declarations will be ignored. If a measure is declared in such a way that the same note is declared at the same time multiple times in the measure, the simulator will read it as multiple notes and the player will have to hit all of the notes declared.

BPM changes

Before you can declare any BPM changes, you must first declare BPMs:
BPM01:140
This will assign the BPM with the two-digit code 01 a value of 140. The BPM can range from over 0 to 1.79769313486231570E+308, and the two-digit code can range from 01 to 99. If these limits are exceeded, the line will be ignored. If a BPM is declared more than once, only the first declaration will be acknowledged. You must declare at least one BPM for the JBT file to be valid. The initial BPM of the song will be the BPM with the lowest two-digit code. BPMs do not have to be whole numbers; for instance, you can declare a BPM with a value of 140.5.

Once your BPMs have been declared, you can add BPM changes. BPM changes are declared inside difficulties like notes:
1BPM:0102
BPM changes are spaced evenly, just like notes. In this example, in measure 1, the BPM will change to BPM 01 at the beginning of the measure, and BPM 02 1/2 into the measure. All rules for declaring notes also apply to declaring BPM changes. If an invalid two-digit code is used, no BPM change will occur.

Stops

Stops must be declared like BPMs:
STOP01:1000
This will assign the stop with the two-digit code 01 a value of 1000 milliseconds. The length of the stop can range from over 0 to 1.79769313486231570E+308, and the two-digit code can range from 01 to 99. If these limits are exceeded, the line will be ignored. If a stop is declared more than once, only the first declaration will be acknowledged. Stop lengths do not have to be whole numbers; for instance, you can declare a stop with a length of 1000.5.

Once your stops have been declared, you can add stops into your song. Stops are declared inside difficulties like notes:
1STOP:0102
Stops are spaced evenly, like notes and BPMs. In this example, in measure 1, the song will stop for the length of time declared in stop 01 once the beginning of the measure has been reached, and for the length of time declared in stop 02 1/2 into the measure. All rules for declaring notes and BPM changes also apply to stops. If an invalid two-digit code is used, no stop will occur.

Home