Building Beat Saber Playlists — Editing .bplist Files
Once a few hundred custom songs have piled up in Beat Saber, finding the one you want gets difficult. Grouping them into playlists makes life much easier, and the file that holds one is a .bplist.
The Beat Saber list editor opens that file in your browser, lets you edit it, and saves it back out.
What a .bplist is
The name is unfamiliar but the contents are JSON: a playlist title, an author, a cover image, and a list of songs.
The values that identify an individual song are:
| Value | Description |
|---|---|
songName | The song title shown on screen |
levelAuthorName | Who made the map (the uploader) |
key | The BeatSaver map number |
hash | The 40-character SHA-1 hash of the map files |
levelId | custom_level_ followed by the hash |
The hash is what matters. The game looks songs up by hash rather than by name, so if the hash is wrong the song simply will not appear in the playlist.
Editing
- Drop a
.bplistfile onto the editor - Edit the title and author
- Arrange the song list
- Use
Save modified fileto download it and overwrite the original
Playlist files usually live in the Playlists folder inside your Beat Saber installation.
Two ways to add songs
By folder — recommended
Point at a folder of custom songs and the editor reads each song's info.dat for its title and difficulty information, and calculates the hash itself.
The hash is produced by concatenating info.dat with each difficulty file in order and taking the SHA-1 — the same rule Beat Saber uses. The correct value goes in without you typing anything.
If a folder has no info.dat, the editor tells you it is not a song folder. That usually means you picked the parent folder rather than an individual song folder.
Manually
Copy the values across from BeatSaver by hand. Use this when you do not have the song files themselves.
- The song title is required
- The hash is a 40-character SHA-1. It has to be exact or the game will not find the song
- The key is the number at the end of the BeatSaver address
Reordering and tidying
- Drag song entries to reorder them
- Sort alphabetically to arrange everything at once
- Song titles can be edited straight from the list. The original files are untouched — only the name shown in the playlist changes
Cover images
A cover is what makes a playlist stand out in the list.
Choose a file — use an image you already have.
Image search — enter a search term and it finds album art. For a playlist with a clear theme, such as a K-pop collection, searching by artist name is the quickest route.
Cover text — composites text over the image. Useful for telling several playlists apart when their album art looks similar.
Cover image search goes through an external service (the Apple iTunes Search API). Only the search term is sent; the playlist file and song information are not.
Viewing the raw JSON
Press View JSON to see the file's actual contents. Use it to work out which field is missing when a playlist produced by some other tool behaves strangely.
Common problems
The playlist shows up but contains no songs Either the hashes are wrong, or those songs are not actually installed. Rebuilding the playlist by adding songs from folders makes hash problems go away.
Only some songs are missing Those particular hashes are wrong. A map's hash changes when it is updated, so if you re-downloaded a song you need to rebuild the playlist too.
The game does not recognise the file I saved Check that it is in the Playlists folder and that the extension is .bplist. Your browser may have saved it as .json.
Summary
- Songs are identified by hash, not by name
- Adding by folder calculates hashes automatically, so there is nothing to get wrong
- Hashes change when maps are updated, so playlists need updating too
- Files are processed entirely in your browser and never uploaded