BeatSaberCinema

A Beat Saber plugin that allows you to sync up videos to play in the background of your maps, heavily inspired by MusicVideoPlayer. This plugin is currently only available for the PC version, there is no Quest release.

How to use

1. Installation

The simplest way to install Cinema is to download it from ModAssistant.

If you want to install Cinema manually, download the latest release from here and simply unzip all of it's contents into the Beat Saber folder. Make sure you don't skip the files in the Libs folder, as those are required, too.

Additionally, the following plugins are required for Cinema to work:

BSIPA
BeatSaberMarkupLanguage
BS Utils
SongCore

2. Download Preconfigured Maps (optional)

The plugin includes about 100 video configurations for custom maps for you to try, as well as a few configs for DLC and OST songs. Here are some examples:

The mod comes with a playlist of over 100 preconfigured maps, ready to play with a video. You can use a mod like PlaylistManager to access it in game.

To find a complete list of all maps that have a video ready to go, visit https://bsaber.org/?filter_mods=cinema&sort=uploaded_desc.

Please note that you yourself can add a video to any map you like.

3. Downloading Videos

Select a song in-game, look to your left to the panel labeled "Gameplay Setup" and press on the tab "Mods" and then on "Cinema", which should look like this:

Click download in the center of the menu and wait for the download to complete, then simply play the map. If the download takes too long for you, you can lower the video quality from the settings on the left side of the main menu.

You can of course add videos to any song you like, even if they are not preconfigured. The menu will in that case show you a button labeled "Search", which will lead you to the search results from YouTube. After you choose a video, you will have to adjust the video offset. To do so, simply click the "Preview" button to play the video, and use the "+" or "-" buttons to adjust the offset until the sound from both ears lines up. Sound from the video will play in your left ear, the map in your right ear. If the sound from the left ear is behind, use the "+" buttons, otherwise the "-" buttons. If you have trouble hearing which one is ahead, try stopping and restarting the preview and listen to which one starts earlier. The sync doesn't have to be exactly perfect though, in most cases you won't notice a slight error in either direction when playing the map.

Info for Mappers

This section is intended for mappers

If you want to add a video to your map, you can simply set it up in the game from the WIP maps section. Refer to the section Downloading Videos for details on how to do that. The video configuration will be stored in the same folder as the map itself, in a file called cinema-video.json. You can include the json file in the zip file you upload to BeatSaver. Please do not include the actual video file, the users will download that themselves from YouTube.

If you include a video config, please add "Cinema" as a suggestion in your map editor, same as you would do with Chroma. Don't set Cinema as a requirement though, since your map should always be playable without it.

You do not need to pay much attention to the environment your map uses. Cinema modifies some of the built-in environments (Big Mirror, Origins, KDA, Rocket, BTS, Dragons, Dragons2, Linkin Park, Kaleidoscope, Monstercat, Skrillex, Pyro/FOB, Weave, Lizzo) to make the video screen fit in seamlessly. If your chosen environment is not in this list of environments supported by Cinema, the mod will automatically load Big Mirror, which is one of the best looking ones with the video screen.

If you have any questions, please contact me on Discord (Dakari#0638).

JSON Format

This section is intended for mappers

Editing the json file by hand allows you to modify some settings that are not available in-game, for example to create a custom screen placement. Doing so is completely optional however, the default settings should give a good experience in most cases.

Cinema includes the ability to change any object in the game scene, to better fit the video screen in environments that are currently not supported by Cinema. When editing the json file by hand, consider using a json validator to check for errors afterwards.

The mod implements hot reloading the config file, so changes to the video config take effect immediately upon saving the file. This even applies while you are playing the map you are editing.

The following tables list the currently available configuration options:

Basic settings

These basic settings get set automatically when you add a video to your map.

| Property | Data Type | Default | Description | | --------------------------------- |:---------:|:---------------------:| ----------- | | videoID | string | none | The YouTube video ID from the part after the &v= in the URL, e.g.: youtube.com/watch?v=_qwnHeMKbVA | | videoUrl | string | none | Use this parameter instead of videoID if you want to use a video hoster other than YouTube. Provide the full video URL for this parameter. Currently supported are the following video sources: YouTube, Facebook, Dailymotion, Vimeo. | | title | string | Untitled Video | The title of the video. Will be shown to the user. | | author | string | Unknown Author | The name of the video's uploader. Will be shown to the user. | | videoFile | string | none | Name of the video file on the local file system. Path is not included, the file is assumed to be in the map's folder. Will be set automatically after downloading and set to the title of the video, with illegal characters replaced by _. | | duration | int | 0 | Video duration in seconds. Will be shown to the user, but has no other function than that. | | offset | int | 0 | The offset in milliseconds to align the video with the map. Use the video menu in-game to determine the offset. | | configByMapper | bool | false | Used to indicate whether the config was created by the mapper (as opposed to by the user). Changes the UI in various small ways. |

Advanced settings

Optional settings which you can set to fine tune the form and function of the video player. Please note that modifying screenHeight, screenPosition and/or using environment modifications makes the config specific to the environment that was selected by the mapper, since overriding the default means it can no longer be guaranteed that all supported environments look correctly.

| Property | Data Type | Default | Description | |----------------------------------------|:---------:|:-------------------------------------:|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | environmentName | string | none | The environment that is supposed to be loaded. This allows you to force a specific environment that is only used if the user has Cinema installed and the video downloaded. This also disables the user's choice in the Override Environment setting of the base game, so please only use it if you have a good reason to do so. The internal names of all the environments are listed as Info.dat Name here. | | playbackSpeed | float | 1.0 | Allows you to adjust the playback speed of the video. | | loop | bool |

BeatSaberCinema

Install / Use

README

BeatSaberCinema

How to use

1. Installation

2. Download Preconfigured Maps (optional)

3. Downloading Videos

Info for Mappers

JSON Format

Basic settings

Advanced settings