The Ultimate Beat Saber Mapping Guide

A comprehensive guide regarding:

  • Setting up tracks
  • Avoiding common mapping mistakes
  • Advanced mapping techniques
  • And a list of mapping patterns and terminology


Table Of Contents

  1. Getting Started (3)
    1. Overview of Contents
    2. Supplemental Aid: Benny and Freeek
  2. Essential Tools (4-13)
    1. Audacity: Setting up your track
    2. Mediocre Mapper: Basic controls, BPM, and offset
      1. BPM calculators and BPM-to-second converters
  3. Supplemental Tools (14)
    1. Arrow Vortex
    2. Spawn Distance
    3. Lightmap
  4. Avoiding Common Beginner Pitfalls (15-16)
    1. Vision Notes
    2. Finding Rhythm
    3. Beat Saber’s Scoring System
  5. A Basic Guide to Note Placements (17-18)
    1. Flowing Notes
    2. Player Resets
    3. Notes Placements to be Wary of
  6. Lighting Guide (19-20)
    1. On, Off, Flash, Fade
    2. Light Speed
    3. Strobing
  7. Obstacles (21-22)
    1. Walls
    2. How 2 Bomb
  8. Comprehensive Note Pattern Guide (23-28)
  9. Mapping for Difficulty (29-30)
  10. JSON Edits (31)
    1. Note Jump Speed
    2. Start Beat Offset
    3. Custom Colors


Essential Tools: Audacity


Audacity is a free, open-source audio editing program. Beat Saber Mappers will primarily use Audacity for four things:

  1. Add silence to the beginning of a track
  2. Decrease the length of outros
  3. Increase audio volume
  4. Convert audio file type to .ogg

Audacity can be downloaded for free from here:

Audacity Download

To open a track in Audacity, you can do one of two things:

  1. Go to File > Open > [Your Song]
  2. Press the Hotkey combination, Ctrl + O

Once you have opened your song, we can begin editing it for use in Beat Saber.

Adding Silence:

To give players time to prepare for the Beat Saber map, it is often necessary to add silence to the beginning of a track to avoid a “hot start”.  To do this, select the beginning of the track and then Go to Generate > Silence.  A silence of 1-3 seconds is recommended.

Note:  Songs that already have a silent start, or do not have any notes within the first couple seconds may not require you to add silence to the track.

Decreasing Length of Outros + Fade Out:

After the last note is hit in-game (Beat Saber), the player will still be within the stage environment until the end of the audio.  If you wish to bring the player out of the game during a “boring” outro because you plan on having no notes within that section, you may decide to cut the end of the audio off.

Simply select the section you wish to remove in Audacity and press ‘Delete’ on your keyboard (above the arrow keys).  You may also choose to fade out the new ending so it does not stop abruptly.  To do this, select the part of the track where you would like the fade to start and to end.  Afterward, Go to Effect > Fade Out.

Increasing the Volume of the Audio:

There is no way to increase the volume of an individual track within Beat Saber without just increasing the master volume.  To make sure audio has a consistent volume level with other songs in-game, it might be necessary to amplify or normalize the audio.  Here are the steps to increasing/normalizing the audio:

  1. Select the entire audio track by using the hotkey combination, Ctrl + A
  2. Go to Effect > Normalize
  3. The box “Normalize maximum amplitude…” is set to 0.0dB by default.  This is recommended, however, if you wish to have the volume even louder, you must use Amplify instead of Normalize (you must also check ‘Allow Clipping’)
  4. When finished using Normalize or Amplify, press ‘OK’ and continue.  You should now notice an increasing volume within Audacity’s waveform.


Exporting Song File as .ogg:

Beat Saber’s song loader requires audio to be in the .ogg file format.  Most audio you acquire will most likely be in .mp3 format.  In order to convert .mp3 to .ogg, we must use Audacity’s Export feature.  In order to export, do the following:

  1. Go to File > Export > Export as .ogg
  2. Navigate to the folder of your Beat Saber song directory
  3. You may name the song file whatever you wish, but for ease of use it is highly recommended to name the song file ‘song’.
  4. We must maintain a file size less than 15mb so you can upload the song online, thus it is recommended to use anywhere between 4-8 quality
  5. Save when you have renamed the song file and chosen the audio quality

You will now be brought to a screen that may allow you to change the metadata of the song, it is up to you whether you decide to change it or not.

Mediocre Mapper

Mediocre Mapper is a Beat Saber mapping program created by squeaksies, which itself is a fork off of the original mapping program by ikeiwa, EditSaber.

You can download Mediocre Mapper from here:

Mediocre Mapper

Note:  Mediocre Mapper is a program made for personal-use by squeaksies, hence it is heavily “meme-d”.  We will still be using Mediocre Mapper for this guide because it is currently the most feature-rich map editor.

Upon installing Mediocre Mapper, it will ask you to locate the directory of your Custom Songs folder.  If you own Beat Saber, by default this will be located within the game’s directory.  If you do not own Beat Saber, you can still proceed but you must create your own Custom Songs directory.

Custom Song Folder Structure:

When creating a custom song, we must set up the layout of its folder.  Within our Custom Songs folder, we must create a folder for our custom song.  In this folder, we must put two files:

  • The .ogg song file (we created this in Audacity)
  • The cover art for the song (in .jpg or .jpeg format).  Originally, cover art had to be 256×256 pixels in size, now higher sizes can be used.


Setting up Song Parameters:

Once you have selected the song you would like to edit within Mediocre Mapper, we can start to fill out the parameters of the song that will show up in-game:

  • Song Name
  • Song SubName:A most people put the artist’s name here
  • Author Name:A most people put their own username here
  • BPM (we will find out how to calculate this shortly)
  • Preview Start Time/Duration:A an audio sample of the song that plays in-game
  • Cover Image Name:A the file name of your cover art (cover.jpg by default)
  • Environment Name:A allows you to change the stage for the song

Things to not worry about unless you’re SkyKiwi:

  • Single Saber
  • Chroma Toggle (leave off)

Now, you must add your intended difficulties on the right-side panel.

Remember to set the difficulty, the audio file name (it’s song.ogg by default), and then click “Apply Modifications”.  We will be leaving “Start Offset” alone for now until we calculate the BPM of the song.

Now we must get the BPM and offset for the song.

Calculating the BPM:

To calculate the BPM for a song, you can either search for it online, calculate it manually, or use a tool to calculate it for you.

Manual BPM Calculation:

To calculate a BPM manually, I highly recommend using a site like All8.

All8 BPM Calculator

or BeastSaber’s bpmSaber

While listening to the song, tap along to determine the BPM of the song.

Tool-Assisted BPM Calculation:

Sometimes, BPM’s are difficult to calculate manually because they are variable or because they aren’t a whole number.  In these cases, it may be preferable to use a tool to calculate the BPM for you.  I recommend Arrow Vortex:

Arrow Vortex

There is more detail on this tool within the “Supplemental Tools” section.  Note:  there are many other tools available to calculate BPM.

Variable BPM:

If you have determined that your song might have variable BPM, please see Benny’s guide for Variable BPM (good luck).

BennydaBeast’s Variable BPM Guide


Entering the Editor:

In order to find the offset, we must enter the editor for the first time.  First, make sure you have filled out all the song parameters and added a difficulty.  Once you have done so, select a difficulty and then select “Edit Level”.

Basic Controls:

  • Space Bar:  Play/pause the music and track
  • Scroll Wheel Up/Down:  Scroll through the track
  • Hold Right-Click + WASD:  Freely move the camera
  • Ctrl + Scroll Wheel:  Adjust cursor precision (track-scrolling increments)

More advanced controls for the editor can be found by pressing “Esc” on your keyboard or by clicking the overview/hamburger icon in the top-right corner.

Now that we are in the editor, we must check the waveform of the song to see if the beats of the music align with track.  The vast majority of songs will not be aligned by nature.

I recommend watching along with Freeek’s video about aligning the offset of a song while reading the next page of this guide.  Using the note hit sound effect in Mediocre Mapper will be especially helpful.

Freeek’s Offset Guide

Note:  Freeek is using an outdated editor in his video, some controls and visuals are different from Mediocre Mapper.

Calculating the Offset:

Now that we have the BPM, we must now find the offset.  You can use Arrow Vortex to find the offset, but Arrow Vortex has some issues regarding how it finds the offset.

What is the offset?  A positive offset value will pull the audio forward on the track in Mediocre Mapper, a negative offset value will push the audio back.  We require a proper offset to line the beat of the song to the track in Mediocre Mapper.  A proper offset will have the main beat of the song line up with the track.  You can visually see this using the waveform of the song.

To find the offset manually, we have two options; trial-and-error, or manipulating the “Cursor Precision”.


To use trial-and-error, change the offset we saw earlier; positive values pull the track forward, negative values push it back.  After setting an offset value, remember to click “Apply Modifications” and then “Edit Level” afterward.  Keep repeating this process until you see that you have a properly aligned offset.