User Guide
Main Features
The tool reads the beatmap currently opened in the osu! editor and helps with repetitive editing and value-checking tasks.
01
Set SV and Volume using notes, barlines, BookMarks, BeatSnaps, existing green lines, and other targets.
Create gradients across a range, process specific object types, apply Relative Mode, and organize existing green lines.
02
Run non-SV edits for Offset, Hitsound, note positions, Metadata, and other beatmap settings.
It also supports tag editing across all difficulties, settings copying, and resnapping notes to a selected beat snap.
03
Check the Timing, BPM, SV, Volume, and Scroll Speed (BPM) applied at the current osu! editor position in real time.
04
Move the background image on screen and choose the BG Y coordinate saved to the beatmap.
Adjust the position visually instead of repeatedly entering numeric values.
Get Started
Open the target taiko beatmap in osu!stable, then launch the tool to get started.
Overview
osu!taiko Mapping Helper reads the taiko beatmap currently opened in the osu! editor and helps with SV editing and batch editing. The target is either the currently selected .osu file, or all difficulties in the same song folder depending on the feature.
The tool reads the running osu! process, the opened song folder, the .osu file name, playback position, metadata, and background image information. If the beatmap name appears in the tool, it has detected the target beatmap.
SV Editor, Utility, and BG Setter rewrite .osu files. After running a process, press Ctrl + L in the osu! editor to reload the file.
The tool can apply or delete SV lines, normalize hitsounds, change note coordinates, edit tags, copy settings, resnap notes, adjust background Y position, and manage backup retention.
Timing Property shows the Timing, BPM, SV, Volume, and Scroll Speed (BPM) at the current osu! playback position. It is useful for checking values while building SV effects.
The common flow is: open the target beatmap in osu!, enter conditions in the tool, execute the process, and then press Ctrl + L in osu!.
A success message means the file was written, but the osu! editor view is not refreshed until you reload it.
Start
This section covers the shared flow from launch to checking the result.
osu.taiko.Mapping.Helper.zip.osu!taiko Mapping Helper.exe.osu!taiko Mapping Helper.exe.SV Editor
The explanation follows the GUI order: Timing, SV, Volume, target options, and Execute.
Set the start and end of the processing range.
Inputs accept mm:ss:fff format or an integer millisecond value. For example, 01:23:456 and 83456 are both valid.
Set Start Timing and Set End Timing copy the current osu! playback position into the start or end field.
The ⇔ button swaps start and end. Execution fails if the start timing is later than the end timing.
When the SV checkbox is enabled, you can specify the SV value to add or update.
Enter a number greater than 0. Decimal values are allowed.
If the SV checkbox is disabled, the tool refers to the green line immediately before the processing point and does not explicitly change the SV value.
Linear mode changes the value by a constant difference from start to end.
Geometric mode changes the value by ratio.
SV(t) = SV_start + (SV_end - SV_start) * p
SV(t) = SV_start * (SV_end / SV_start) ^ p
p is the progress inside the range. It is 0 at the start and 1 at the end.
When the Volume checkbox is enabled, you can specify the volume of the green lines.
Enter an integer from 5 to 100. Decimal values are not accepted.
If the Volume checkbox is disabled, the tool refers to the volume of the red or green line immediately before the processing point. Disable Volume when you want to edit only SV without changing volume.
When Apply to Red Lines is enabled, red lines inside the selected range are also changed to the specified Volume.
Use this to prevent red lines and green lines at the same timing from ending up with different Volume values.
When this checkbox is disabled, red-line Volume values inside the range are left unchanged.
This is useful when you intentionally want the first red line and its green line to have different Volume values, so the area before that line uses the red-line Volume and the area after it uses the green-line Volume.
If disabled, an object exactly at the start timing is excluded from processing.
If disabled, an object exactly at the end timing is excluded from processing.
This option appears when AdvanceMode is enabled in Settings.
Normally, the entered SV is used as-is. In Relative Mode, the new SV is calculated based on the SV currently applied to the target object.
Multiply uses (current SV - BaseSV) * input SV + BaseSV.
Sum adds the input SV to the current SV.
Enable End Timing lets you specify separate relative values for the start and end of the range.
Adds green lines to target timings inside the selected range.
If SV or Volume is enabled, values are calculated according to the position between start and end.
When existing green lines overlap, the tool organizes existing green lines according to the target and offset.
Green lines between the target note and the next target note may be removed if they would duplicate the new line's effect. However, lines required to restore unselected objects, or to preserve kiai changes, are kept or have their values inherited.
After applying, sliderLength is corrected if needed so that sliders before or after the range do not visually break.
kiai state is inherited from the previous red or green line.
Deletes green lines inside the selected range. Red lines are not deleted.
After deletion, sliderLength is corrected if needed so that sliders before or after the range do not visually break.
When enabled, green lines placed by Only Objects are shifted slightly before the target note.
If the Settings offset type is...
1/16 (1/12) offset, the offset is calculated from BPM as a 1/16 note.
If the type is ms offset, the configured millisecond value is used.
When 1/12 inclusive is enabled, 1/12 offset is used if the range includes 1/12 snap HitObjects, so the SV line does not become too close to the previous HitObject. Otherwise, 1/16 is used.
This option is recommended when placing SV lines with Volume changes, because it helps prevent the player from hitting before the volume change is applied.
Press Execute to overwrite the .osu file using the current inputs and target options.
A backup is created before execution, and a success message is shown when writing is complete. Finally, press Ctrl + L in osu! to reload.
Utility
Utility is where non-SV batch editing features are grouped.
.osu files in the same song folder.For each red line, the tool calculates snap intervals from BPM, meter, and barLength.
Notes within half a snap before or after each snap position are moved to that snap position. If a red line exists inside the range, the next section is recalculated using the new BPM and meter.
Available intervals are 1/24, 1/36, 1/48, and 1/60. Choose the smallest unit that matches the beatmap's rhythm. A confirmation dialog appears before execution.
BG Setter
Shows the current beatmap background and adjusts the Y coordinate stored in the osu! background event line.
BG Setter rewrites the Y offset in the background line of the Events section. It does not edit the image file itself. Use it when you only want to change the displayed background position.
Timing Property
Timing Property is a reference screen, not an editing screen. It shows values corresponding to the current osu! playback position. It appears in the menu when AdvanceMode is enabled in Settings.
mm:ss:fff format.When you play or seek in the osu! editor, Timing Property values update.
Double-clicking each displayed value will copy it to the clipboard.
Settings
Settings controls the whole tool's display language, backup retention, offset type, and note coordinates.
Safety
This tool is convenient, but it rewrites .osu files during execution. It is safer to understand what changes before and after processing.
SV Editor, parts of Utility, and BG Setter copy the current .osu file to the Backup folder before overwriting.
Backup file names include the date and time. Old backups over the configured keep limit are deleted.
Large SV operations, copying to all difficulties, and Resnap can affect a wide range of the beatmap.
For published beatmaps or active worksets, copy the whole song folder somewhere else before testing.
Use this tool at your own risk. You are responsible for any issues that occur from using this tool or in connection with it.
The creators and distributors accept no responsibility or liability.
A success message means writing to the file is complete. The osu! editor view is not updated automatically.
Always reload with Ctrl + L and check Timing, HitObjects, and background coordinates.
Troubleshooting
Common symptoms and things to check.
Check that osu! is running and that a beatmap is open in the editor.
Detection can also fail if the song folder or .osu file was moved or deleted.
Press Ctrl + L in osu! to reload the beatmap.
Even if the tool rewrites the file, the editor view is not refreshed automatically.
Enter the value in mm:ss:fff format or as an integer millisecond value.
An error also occurs if the start timing is later than the end timing.
SV must be a positive number. Volume should be an integer from 5 to 100.
The BaseSV for Relative Mode must also be a positive value.
Change the backup keep limit in Settings and save it.
You can specify a value from 1 to 100, and old backups are cleaned up after saving.
osu!lazer is not supported.
The tool cannot read the currently opened beatmap or playback position from osu!lazer in real time.
In addition, osu!stable and osu!lazer use different osu! file formats, so writing to an osu!lazer .osu file may cause unexpected behavior.
Use this tool with osu!stable only.
If you encounter a bug in the tool, please report it in the bug-report channel on Discord.
If you have a request for a new feature or improvement, please post it in the request channel on Discord.
Project Members
People who contributed to development, feature ideas, guide writing, review, and testing for osu!taiko Mapping Helper.