Info
The Info.dat file is the main entry point for your Beat Saber map. It describes basic metadata about your song, as well as point to other files such as beatmaps, lightshows, cover art, audio data, and other references.
Sample Data
{
"_version": "2.0.0",
"_songName": "Magic",
"_songSubName": "ft. Meredith Bull",
"_songAuthorName": "Jaroslav Beck",
"_levelAuthorName": "Freeek",
"_beatsPerMinute": 208,
"_songTimeOffset": 0,
"_shuffle": 0,
"_shufflePeriod": 0,
"_previewStartTime": 0,
"_previewDuration": 0,
"_songFilename": "Magic.wav",
"_coverImageFilename": "cover.png",
"_environmentName": "WeaveEnvironment",
"_allDirectionsEnvironmentName": "GlassDesertEnvironment",
"_difficultyBeatmapSets": [
{
"_beatmapCharacteristicName": "Standard",
"_difficultyBeatmaps": [
{
"_difficulty": "Easy",
"_difficultyRank": 1,
"_beatmapFilename": "Easy.dat",
"_noteJumpMovementSpeed": 10,
"_noteJumpStartBeatOffset": 0
},
{
"_difficulty": "Normal",
"_difficultyRank": 3,
"_beatmapFilename": "Normal.dat",
"_noteJumpMovementSpeed": 10,
"_noteJumpStartBeatOffset": 0
},
{
"_difficulty": "Hard",
"_difficultyRank": 5,
"_beatmapFilename": "Hard.dat",
"_noteJumpMovementSpeed": 10,
"_noteJumpStartBeatOffset": 0
},
{
"_difficulty": "Expert",
"_difficultyRank": 7,
"_beatmapFilename": "Expert.dat",
"_noteJumpMovementSpeed": 16,
"_noteJumpStartBeatOffset": 1
},
{
"_difficulty": "ExpertPlus",
"_difficultyRank": 9,
"_beatmapFilename": "ExpertPlus.dat",
"_noteJumpMovementSpeed": 18,
"_noteJumpStartBeatOffset": 0.5
}
]
}
]
}{
"_version": "2.1.0",
"_songName": "Magic",
"_songSubName": "ft. Meredith Bull",
"_songAuthorName": "Jaroslav Beck",
"_levelAuthorName": "Freeek",
"_beatsPerMinute": 208,
"_songTimeOffset": 0,
"_shuffle": 0,
"_shufflePeriod": 0,
"_previewStartTime": 0,
"_previewDuration": 0,
"_songFilename": "Magic.wav",
"_coverImageFilename": "cover.png",
"_environmentName": "WeaveEnvironment",
"_allDirectionsEnvironmentName": "GlassDesertEnvironment",
"_environmentNames": [
"WeaveEnvironment",
"GlassDesertEnvironment"
],
"_colorSchemes": [
{
"useOverride": true,
"colorScheme": {
"colorSchemeId": "Weave",
"saberAColor": {
"r": 0.7843137,
"g": 0.07843138,
"b": 0.07843138,
"a": 1
},
"saberBColor": {
"r": 0.1568627,
"g": 0.5568627,
"b": 0.8235294,
"a": 1
},
"environmentColor0": {
"r": 0.85,
"g": 0.08499997,
"b": 0.08499997,
"a": 1
},
"environmentColor1": {
"r": 0.1882353,
"g": 0.675294,
"b": 1,
"a": 1
},
"obstaclesColor": {
"r": 1,
"g": 0.1882353,
"b": 0.1882353,
"a": 1
},
"environmentColor0Boost": {
"r": 0.8218409,
"g": 0.08627451,
"b": 0.8509804,
"a": 1
},
"environmentColor1Boost": {
"r": 0.5320754,
"g": 0.5320754,
"b": 0.5320754,
"a": 1
}
}
}
],
"_difficultyBeatmapSets": [
{
"_beatmapCharacteristicName": "Standard",
"_difficultyBeatmaps": [
{
"_difficulty": "Easy",
"_difficultyRank": 1,
"_beatmapFilename": "Easy.dat",
"_noteJumpMovementSpeed": 10,
"_noteJumpStartBeatOffset": 0,
"_beatmapColorSchemeIdx": 0,
"_environmentNameIdx": 0
},
{
"_difficulty": "Normal",
"_difficultyRank": 3,
"_beatmapFilename": "Normal.dat",
"_noteJumpMovementSpeed": 10,
"_noteJumpStartBeatOffset": 0,
"_beatmapColorSchemeIdx": 0,
"_environmentNameIdx": 0
},
{
"_difficulty": "Hard",
"_difficultyRank": 5,
"_beatmapFilename": "Hard.dat",
"_noteJumpMovementSpeed": 10,
"_noteJumpStartBeatOffset": 0,
"_beatmapColorSchemeIdx": 0,
"_environmentNameIdx": 0
},
{
"_difficulty": "Expert",
"_difficultyRank": 7,
"_beatmapFilename": "Expert.dat",
"_noteJumpMovementSpeed": 16,
"_noteJumpStartBeatOffset": 1,
"_beatmapColorSchemeIdx": 0,
"_environmentNameIdx": 0
},
{
"_difficulty": "ExpertPlus",
"_difficultyRank": 9,
"_beatmapFilename": "ExpertPlus.dat",
"_noteJumpMovementSpeed": 18,
"_noteJumpStartBeatOffset": 0.5,
"_beatmapColorSchemeIdx": 0,
"_environmentNameIdx": 0
}
]
}
]
}{
"version": "4.0.0",
"song": {
"title": "Magic",
"subTitle": "ft. Meredith Bull",
"author": "Jaroslav Beck"
},
"audio": {
"songFilename": "song.ogg",
"songDuration": 202,
"audioDataFilename": "BPMInfo.dat",
"bpm": 208,
"lufs": 0,
"previewStartTime": 0,
"previewDuration": 0
},
"songPreviewFilename": "song.ogg",
"coverImageFilename": "cover.png",
"environmentNames": [
"WeaveEnvironment",
"GlassDesertEnvironment"
],
"colorSchemes": [
{
"useOverride": true,
"colorSchemeName": "Weave",
"saberAColor": "#C81414FF",
"saberBColor": "#288ED2FF",
"obstaclesColor": "#FF3030FF",
"environmentColor0": "#D91616FF",
"environmentColor1": "#30ACFFFF",
"environmentColor0Boost": "#D216D9FF",
"environmentColor1Boost": "#00FFA5FF"
}
],
"difficultyBeatmaps": [
{
"characteristic": "Standard",
"difficulty": "Easy",
"beatmapAuthors": {
"mappers": [
"Freeek"
],
"lighters": [
"Freeek"
]
},
"environmentNameIdx": 0,
"beatmapColorSchemeIdx": 0,
"noteJumpMovementSpeed": 10,
"noteJumpStartBeatOffset": 0,
"beatmapDataFilename": "Easy.dat",
"lightshowDataFilename": "Lightshow.dat"
},
{
"characteristic": "Standard",
"difficulty": "Normal",
"beatmapAuthors": {
"mappers": [
"Freeek"
],
"lighters": [
"Freeek"
]
},
"environmentNameIdx": 0,
"beatmapColorSchemeIdx": 0,
"noteJumpMovementSpeed": 10,
"noteJumpStartBeatOffset": 0,
"beatmapDataFilename": "Normal.dat",
"lightshowDataFilename": "Lightshow.dat"
},
{
"characteristic": "Standard",
"difficulty": "Hard",
"beatmapAuthors": {
"mappers": [
"Freeek"
],
"lighters": [
"Freeek"
]
},
"environmentNameIdx": 0,
"beatmapColorSchemeIdx": 0,
"noteJumpMovementSpeed": 10,
"noteJumpStartBeatOffset": 0,
"beatmapDataFilename": "Hard.dat",
"lightshowDataFilename": "Lightshow.dat"
},
{
"characteristic": "Standard",
"difficulty": "Expert",
"beatmapAuthors": {
"mappers": [
"Freeek"
],
"lighters": [
"Freeek"
]
},
"environmentNameIdx": 0,
"beatmapColorSchemeIdx": 0,
"noteJumpMovementSpeed": 16,
"noteJumpStartBeatOffset": 1,
"beatmapDataFilename": "Expert.dat",
"lightshowDataFilename": "Lightshow.dat"
},
{
"characteristic": "Standard",
"difficulty": "ExpertPlus",
"beatmapAuthors": {
"mappers": [
"Freeek"
],
"lighters": [
"Freeek"
]
},
"environmentNameIdx": 0,
"beatmapColorSchemeIdx": 0,
"noteJumpMovementSpeed": 18,
"noteJumpStartBeatOffset": 0.5,
"beatmapDataFilename": "ExpertPlus.dat",
"lightshowDataFilename": "LightshowPlus.dat"
}
]
}Summary
Introduced in 1.0.0
- A field is available to credit the level designer for the map.
- The audio path is assigned at the top level, and applies for all difficulties.
- All beatmaps are organized into "sets", which allow for parent-level assignment of characteristic metadata.
Song Metadata
Song Title
The title of your song.
{
"_songName": "Example",
}{
"song": {
"title": "Example",
},
}Song Subtitle
The subtitle of your song, which may indicate any additional collaborators or alternative arrangements.
{
"_songSubName": "Example",
}{
"song": {
"subTitle": "Example",
},
}Song Author
The artist(s) of your song.
{
"_songAuthorName": "Example",
}{
"song": {
"author": "Example",
},
}Related Files
INFO
All filename references are assumed to be located in the same relative directory as the info file.
Audio Filename(s)
The audio file(s) associated with your map.
While wav files are technically supported in the Official Editor, ogg files are generally recommended for uploading to BeatSaver.
TIP
For v4, two separate files are explicitly defined:
- The "primary" file, which is used when playing your song and processing BPM and LUFS data.
- The "preview" file, which is used for the in-game preview when selecting your song.
While the base game parses two separate audio files for all OST and DLC levels, these two files will more often point to the same file in the context of custom levels.
{
"_songFilename": "song.ogg",
}{
"audio": {
"songFilename": "song.ogg",
},
"songPreviewFilename": "song.ogg",
}Cover Image Filename
A cover image that displays alongside the song metadata in the selection menu.
All cover images should be in png, jpeg, or jpg format. When uploading to BeatSaver, it is advised to set your cover image to a square aspect ratio and a width/height no smaller than 256px.
{
"_coverImageFilename": "cover.png",
}{
"coverImageFilename": "cover.png",
}Audio Metadata
BPM
A value which dictates how the grid will align with your audio file.
{
"_beatsPerMinute": 120.0,
}{
"audio": {
"bpm": 120.0,
},
}Integrated LUFS
A value which controls the overall loudness of the audio file.
{
"audio": {
"lufs": 0.0,
},
}Song Duration
A value (in seconds) which caches the length of the audio file.
This is used to properly display the duration of the song on the selection screen on un-modded instances.
INFO
For v3 and earlier, modded instances will display the duration of the song on the selection menu, despite not being explicitly defined anywhere in the metadata. This behavior is exclusively provided by SongCore/PinkCore, and will not work properly on un-modded instances.
{
"audio": {
"songDuration": 202.0,
},
}Song Time Offset
A value (in seconds) that delays when the audio starts in relation to the beatmap.
WARNING
These fields are deprecated due to unstable behavior in recent versions of the game, and are unsupported starting from v4.
{
"_songTimeOffset": 0.0,
}Shuffle
Allows you to define "swing" timings across all beatmaps while preserving the natural timings in-editor.
WARNING
These fields are deprecated due to unstable behavior in recent versions of the game, and are unsupported starting from v4.
{
"_shuffle": 0.0,
"_shufflePeriod": 0.0,
}Song Preview
Allows you to define a shortened version of your audio track, which will play when selecting your map in-game.
{
"_previewStartTime": 10.0,
"_previewDuration": 12.0,
}{
"audio": {
"previewStartTime": 10.0,
"previewDuration": 12.0,
},
}Environments
The surrounding world that a player is within when playing a map, which can be defined on a global level or per-beatmap basis.
- In v4 and later, all environments should be defined using a template-like syntax, where each beatmap will pull its corresponding environment from the "collection" array at the specified "index".
- For v2, if the template-like syntax is used, it will take priority over the top-level environment definition.
{
"_environmentName": "DefaultEnvironment",
"_allDirectionsEnvironmentName": "GlassDesertEnvironment",
}{
"_environmentName": "DefaultEnvironment",
"_allDirectionsEnvironmentName": "GlassDesertEnvironment",
"_environmentNames": ["DefaultEnvironment", "GlassDesertEnvironment"], // Collection
"_difficultyBeatmapSets": [
{
"_difficultyBeatmaps": [
{
"_environmentNameIdx": 0, // Index
},
],
},
],
}{
"environmentNames": ["DefaultEnvironment", "GlassDesertEnvironment"], // Collection
"difficultyBeatmaps": [
{
"environmentNameIdx": 0, // Index
},
],
}Color Schemes
The color palette used across in-game objects, which can be defined on a per-beatmap level using the same template-like index as defined for the environments.
- In v2, colors are represented in object notation, where each color channel is normalized to a range of
0-1. - In v4, colors are represented in hex notation.
If no color schemes are defined or you prefer inheriting the color scheme of the selected environment, you'll want to set the index to -1.
WARNING
Any colors in a scheme that are not defined will appear as a null color in-game, and may cause unintended effects.
{
"_colorSchemes": [
{
"useOverride": true,
"colorScheme": {
"colorSchemeId": "Weave",
"saberAColor": {
"r": 0.7843137,
"g": 0.07843138,
"b": 0.07843138,
"a": 1,
},
"saberBColor": {
"r": 0.1568627,
"g": 0.5568627,
"b": 0.8235294,
"a": 1,
},
"environmentColor0": {
"r": 0.85,
"g": 0.08499997,
"b": 0.08499997,
"a": 1,
},
"environmentColor1": {
"r": 0.1882353,
"g": 0.675294,
"b": 1,
"a": 1,
},
"obstaclesColor": {
"r": 1,
"g": 0.1882353,
"b": 0.1882353,
"a": 1,
},
"environmentColor0Boost": {
"r": 0.8218409,
"g": 0.08627451,
"b": 0.8509804,
"a": 1,
},
"environmentColor1Boost": {
"r": 0.5320754,
"g": 0.5320754,
"b": 0.5320754,
"a": 1,
},
},
},
],
"_difficultyBeatmapSets": [
{
"_difficultyBeatmaps": [
{
"_beatmapColorSchemeIdx": 0,
},
],
},
],
}{
"colorSchemes": [
{
"useOverride": true,
"colorSchemeName": "Weave",
"saberAColor": "#C81414FF",
"saberBColor": "#288ED2FF",
"obstaclesColor": "#FF3030FF",
"environmentColor0": "#D91616FF",
"environmentColor1": "#30ACFFFF",
"environmentColor0Boost": "#D216D9FF",
"environmentColor1Boost": "#00FFA5FF",
},
],
"difficultyBeatmaps": [
{
"beatmapColorSchemeIdx": 0,
},
],
}TIP
For 2.0.0 format, additional support for per-beatmap color schemes and "white" color overrides are provided by the SongCore and PinkCore mods respectively. You can refer to their documentation for more details.
Beatmap Metadata
A "beatmap" refers to the individual levels associated with a map, organized by their characteristic and difficulty.
Beatmap Sets
For v2, all beatmaps are grouped into "sets", which dictate corresponding behaviors to apply at a higher level to all beatmaps located within that set.
Support for beatmap sets was subsequently removed in v4, due to set-specific behaviors being exclusively controlled by the defined characteristic and no additional fields being introduced for beatmap sets throughout the lifetime of the schema.
{
"_difficultyBeatmapSets": [
{
"_difficultyBeatmaps": [...],
},
],
}{
"difficultyBeatmaps": [...],
}Beatmap Filename
The level file associated with your map. Must point to a valid JSON file.
INFO
Starting from v4, all corresponding beatmap data will be divided into two separate files:
INFO
If a v2 or v3 beatmap file is defined, the lightshow file will subsequently be ignored, since v2 and v3 beatmap files already contain the relevant lighting objects for the beatmap.
{
"_difficultyBeatmapSets": [
{
"_difficultyBeatmaps": [
{
"_beatmapFilename": "Easy.dat",
},
],
},
],
}{
"difficultyBeatmaps": [
{
"beatmapDataFilename": "Easy.dat",
"lightshowDataFilename": "Lightshow.dat",
},
],
}Characteristic
A value which groups beatmaps into unique categories and applies specialized behaviors to those affected beatmaps.
The list of acceptable values and their corresponding behaviors are listed below:
| Name | Behavior |
|---|---|
Standard | No special behavior. |
NoArrows | No special behavior. |
OneSaber | Disables the Left (Red) saber. |
360Degree | Uses rotation behaviors. |
90Degree | Uses rotation behaviors. |
Legacy | No special behavior. |
DANGER
Some mods may add additional characteristics that are not supported within the base game, such as SongCore's Lightshow and Lawless characteristics.
When loading maps with these characteristics on un-modded versions of the game, affected maps will not be compatible with the Official Editor, and affected beatmaps may be filtered out of the available difficulties for the player to select in-game or fail to load correctly on un-modded instances.
{
"_difficultyBeatmapSets": [
{
"_beatmapCharacteristicName": "Standard",
},
],
}{
"difficultyBeatmaps": [
{
"characteristic": "Standard",
},
],
}Difficulty
A cosmetic label to indicate the overall difficulty of the beatmap, relative to its characteristic.
If a "rank" is needed, the rank will determine how the difficulties are sorted on the selection menu. These ranks are usually invisible to the player and hardcoded or autopopulated by most editors or future schemas.
The list of acceptable values and their corresponding ranks are listed below:
| Name | Rank |
|---|---|
Easy | 1 |
Normal | 3 |
Hard | 5 |
Expert | 7 |
Expert+ | 9 |
{
"_difficultyBeatmapSets": [
{
"_difficultyBeatmaps": [
{
"_difficulty": "Easy",
"_difficultyRank": 1,
},
],
},
],
}{
"difficultyBeatmaps": [
{
"difficulty": "Easy",
},
],
}Beatmap Authors
The designer(s) of the beatmap, including any contributing mappers and lighters.
Starting from v4, this field is no longer defined on a global level, and you can explicitly credit the individual mappers and lighters for your map on a per-beatmap basis.
{
"_levelAuthorName": "Freeek",
}{
"difficultyBeatmaps": [
{
"beatmapAuthors": {
"mappers": ["Freeek"],
"lighters": ["Freeek"],
},
},
],
}Note Jump Metadata
A series of parameters that determine how interactable objects in the beatmap will move towards the player.
For more detailed explanations of how these values affect gameplay, you can refer to the Basic and Intermediate mapping pages.
{
"_difficultyBeatmapSets": [
{
"_difficultyBeatmaps": [
{
"_noteJumpMovementSpeed": 18.0,
"_noteJumpStartBeatOffset": 0.5,
},
],
},
],
}{
"difficultyBeatmaps": [
{
"noteJumpMovementSpeed": 18.0,
"noteJumpStartBeatOffset": 0.5,
},
],
}