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.


Calculating the Offset:

Cursor Precision:

Another way to find the offset is to set the “Cursor Precision” within Mediocre Mapper to a low value such as 1/32nd or 1/64th and then scrolling through the track to see how far away the beat of a song is from the beat on the editor’s track.  Keep note of how many times you had to scroll at a given precision to calculate the distance from the beat to the track.  Now we can use this value to calculate the distance in milliseconds using a calculation tool:

BPM to Milliseconds Calculator

To use this calculator, enter the BPM of the song and then press “Convert BPM”.


My song is 120 BPM.  I had to scroll 10 times backwards at cursor precision 1/32nd from the beat of the song to the beat on the track.

Using the BPM to Milliseconds calculator, I found that a 1/32 note interval at 120 BPM is equivalent to 15.6 milliseconds.  Because I had to scroll 10 times backwards at cursor precision 1/32nd, I can calculate this time by multiplying 15.6 by 10.  Thus, the offset for my song is 156 milliseconds.


Supplemental Tools

Arrow Vortex

A editing program used for charting rhythm games.  Arrow Vortex has the ability to calculate the BPM of a song as well as assist in finding a rough offset.  To use this feature, first open your .ogg song file and then use the hotkey combination, Shift + S.  From here you can calculate the BPM and offset.

Spawn Distance  (mirror link)

SpawnDis.exe is a program created by kyle1413 that allows more advanced mappers to calculate how far away notes will spawn from the player at a given BPM and note jump speed.

Lightmap v2.0

Lightmap is a tool made in collaboration from Freeek, ndepoel, and recrudesce.  It allows mapper to automatically generate lighting for maps based on note placements.  This can be used if the mapper does not wish to manually light their map.

BPM to Milliseconds Calculator

This tool is important if you wish to find your offset using Cursor Precision.

Avoiding Common Beginner Pitfalls


Many newer mappers often come across the same mistakes.

Vision Notes:

Vision notes are any notes placed within the middle section of the second row.  Vision notes obscure the player’s vision and makes it difficult to sight-read a map, leading to an overall negative experience.  It is recommended for newer mappers to stick to the bottom row.

Finding Rhythm:

Many newer mappers create maps with sporadic rhythms that do not feel intuitive.  When creating a map, consider adding placeholder notes before creating your patterns.  You shouldn’t have to use cursor precision at 1/8th for about 95% of songs that you work on, almost all notes should be placed on a 1/4th, 1/2nd, or the whole beat.  Your primary goal is to put notes on the main instruments of a song; the drum beat, the lead instrument, or even the bass.  It is generally inadvisable to map to the vocals because vocals are usually more of an improvised rhythm.  For an example of a map with good rhythm, check the following video:

Ghosts n Stuff


Learn the Scoring System:

Beat Saber has a scoring system that allows up to 110 points per block.  100 points can simply be attained by using a wide swing arc when hitting the block.  The remaining 10 points can be attained by accuracy; slicing closer to the center of the block’s edge will allow up to 10 extra points.

Scoring System Video

Good mappers will use patterns that allow the player to consistently hit 100+ per block without resorting to uncomfortable movements.  This is often known as flow.  Later in the guide (A Basic Guide to Note Placements), you will learn how to create maps with good flow.

Get Good (dot note overcompensation):

By understanding how the scoring mechanic works, you may now learn how to make flowing maps that players can enjoy.  However, to truly understand flow, it is important that the Beat Saber mapper can play the game at a competent level.  Newer mappers are sometimes also new to Beat Saber overall, but wish to make maps for their skill level.  In order for these low-skill mappers to make ‘Expert’ level maps that they can play, they often resort to using an overabundance of dot notes.  Dot notes, in excess, are unfun to the majority of players.  Before making Expert level maps, I recommend that newer mappers should be able to complete the OST track, Angel Voices, on Expert with at least an ‘A’ rating before making more difficult tracks.  Practicing this will improve your own maps considerably.

A Basic Guide to Note Placements



Flow is the concept of allowing the player to consistently hit 100+ points per block without uncomfortable motions.  Here are some very basic patterns with good flow:

You may notice that most patterns with good flow involve starting with a down-note, followed by either an up-note or a left/right-note.  This is the bread and butter of most mapping patterns.

Note:  It is good practice to start most patterns with a down-note.

Player Resets:

Not all notes have to flow together.  If you place a down-note, but then 5 seconds of time pass before the next notes, it is possibly preferable to place another down note (or even a left/right) rather than an up-note.  This is because when long periods of time pass between notes, the player will “reset” their arms’ positions.  In “gray areas” of time, like 3 seconds without notes, it is up to the mapper to reset the player, or continue the flow.


Note Placements to be Wary of:

There are some patterns that exist that flow together, but only in some scenarios.  There are also some patterns that may require lots of effort from the player.