| Name | synth-mapping-helper JSON |
| Version |
1.5.18
JSON |
| download |
| home_page | None |
| Summary | Toolbox for manipulating the JSON-Format used by Synth Riders Beatmap Editor in the clipboard |
| upload_time | 2025-07-17 19:19:38 |
| maintainer | None |
| docs_url | None |
| author | adosikas |
| requires_python | >=3.11 |
| license | MIT License
Copyright (c) 2024 adosikas
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
|
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Synth Mapping Helper
Toolbox for manipulating the JSON-Format used by *Synth Riders Beatmap Editor* in the clipboard and `.synth` files.
# Installation
## Simple Installation (Windows)
Simply download the latest `.exe` from the [Release Page](https://github.com/adosikas/synth_mapping_helper/releases).
You can just place it anywhere and run it, no installation needed.
To update, simply download the latest file.
You can enable checks for updates in the *Version History* Tab.
## Advanced Installation
If you are unsure what any of the following means, you should go for the simple installation.
This is a PyPi package: `synth_mapping_helper`.
The main entry point for the GUI is `python3 -m synth_mapping_helper.gui` (or `smh-gui` if you got `$PATH` setup correctly).
If you want to implement highly custom stuff, you can interface with it directly, check out the [`example_scripts` directory](https://github.com/adosikas/synth_mapping_helper/tree/main/example_scripts) and the [Glossary on the wiki](https://github.com/adosikas/synth_mapping_helper/wiki/Glossary) to learn about how I represent positions, notes, rails and walls.
A virtual environment is recommended for the installation:
```sh
# Initial installation
python3 -m venv smh # create a virtual environment in a new "smh" directory
smh/bin/pip3 install synth_mapping_helper # install package and dependencies inside the venv
# Starting GUI
smh/bin/smh-gui
# Note that this calls smh-gui directly inside the venv, without entering it first.
# So, you can just make a shortcut or .desktop file for that command.
```
To update, either delete the venv and start over, or run `smh/bin/pip3 install --upgrade synth_mapping_helper`
# GUI Features
The GUI works like a website running on your local machine (accessible only to you), and accesses the clipboard.
If you are overwhelmed by the amount of buttons, start with one segment at a time.
You can hover your mouse over pretty much all buttons and input fields to get a short tooltip.
The following is a list of features broken down by GUI tab:
## Dashboard
* Filter for type, rail length, and more
* Switch between reference frames (absolute, relative to rail/wall or custom pivot)
* **Offsetting** in X/Y and time
* **Scaling** in X/Y and time
* Note that wall sizes cannot scale, only their positions
* Flattening in X/Y
* **Mirroring** across X/Y and time, or with custom angle
* Can optionally create a mirrored copy instead of replacing the original
* **Rotation** in XY-plane
* Walls also rotate as one would except (except crouch walls)
* Add **parallel/crossover** patterns
* **Merge and split rails**, even when there are gaps
* Turn **rails into notes**, and **notes into rails**
* Create **notestacks** or lightning rails
* Shorten or extend rails
* **Automatic rails smoothing**
* Change type of notes
* Add **spirals, zigzags or spikes** to any rail
* Remove time gaps in wallart, or adjust spacing to stay below game limits
## Stacking
* Quickly create complex geometric wall or note patterns
* Create spirals by using just pattern rotation and time offset
* Create vortices by adding scaling and in/outset to spirals
* Auto-Detection of parameters, which can then be iterated on
* Subdivision of parameters allows smoother transitions
* Optional randomisation for more organic patterns
* Fast iteration via the **integrated 3D-preview**
## Text
* Automatically create walls to show text
* Custom font support ([submissions welcome](https://github.com/adosikas/synth_mapping_helper/discussions/2))
* _Please_, don't overuse text. So e.g. don't add _all_ lyrics.
## Custom Wall Art Editor
* _Please_, read the **build-in controls / shortcuts popup**
* Fully 3D and using browser acceleration
* Walls render with **transparency**
* Highly customisable, with configurable snapping steps and custom color settings
* Supports symmetry in almost real time (rotational and mirror)
* **TurboStack**, for almost real time "drag and drop" stacking
* Overlay **reference image** to create accurate wall art
* **Compress wall-art** to remove time gaps
* **Blender** to blend between two wall art patterns
* Uses shortest rotation amount, taking into account symmetry
* Note: Patterns must match in type and timing, Example:
* First pattern: Square&Triangle at 10+0/64 and 10+1/64
* Second pattern: Square&Triangle at 20+0/64 and 20+1/64 (at different XY & rotation)
* Interpolate with interval 1/2 to create 19 intermediate patterns
## Commands
* Basic scripting support, replacing the legacy "drag and drop onto smh.bat" system
* Chaining operations
* Save frequently used operations as one-click **Quick run** button.
* See the [wiki for syntax](https://github.com/adosikas/synth_mapping_helper/wiki)
## File Utils
* **Create `.synth` from any audio file**
* While `.mp3`, etc are accepted, please prefer higher quality audio files
* Output can be saved/downloaded, instead of landing in some hard-to-find location
* Fix some common errors that can result in the editor refusing to open the file
* **Automatic BPM detection**
* Detection BPM & Offset can directly be applied to the file
* Plot error between detected BPM and onsets (peaks) in the audio
* Plot which shows when BPM drifts or changes throughout the song
* In that case manual action is still required, but now you know what's going on instead of just getting a few low-confidence guesses
* **Audio preview with beat ticks (metronome)** to check BPM / Offset
* Fine tune BPM/Offset with quick buttons
* **Adjust BPM/Offset without messing up existing content**
* Pad or trim audio to tweak silence at beginning or end
* **Merge files**, even when they have different BPM
* This is very useful when mapping parts of a map at different BPM
* Advanced statistics/analysis
* Plot hand movement, velocity/speed and acceleration/g-force
* Show various warnings
* Note at head position (**vision block**)
* Something to close to end of map
* Patterns will look messed or be unplayable in spiral, due to a bug in the game
* Plot nall density, and see if you reach the "**wireframe limit**"
* Plot note/rail density to identify potentially laggy sections
## AutoBackup
* Periodically checks `.synth` files in a certain directory for changes and creates **backups**
* Backups **never get deleted/overwritten**, so you can _always_ go back
* You should cleaned up old backups once you are done with that map, as that is _not_ done automatically
## Version History
* **Check for a new version**, either manually or on every start
* Show release notes, with **explaination of new features** (and typically a screenshot)
* Last few releases only, full list [here](https://github.com/adosikas/synth_mapping_helper/releases)
* Direct link to release for easy download (but no automatic download/install)
# Technical information
The GUI is built with [NiceGUI](https://nicegui.io/), allowing me to write a "frontend" with pure python. Even the wall art editor is created from python, which is why I am not currently able to make a "full editor" as that requires some fully clientside logic (ThreeJS in particular).
If you have experience there and would like to help me make a proper editor (with native intergration for SMH, please let me know).
In the "backend" everything is python and numpy arrays, and uses fairly modular functions for the various operations. Feel free to experiment with using the API to make custom python scripts, but that requires the advanced installation (see above).
# 100% LLM Free
This project (to the best of my knowledge) does not contain any LLM-Generated code.
Please do not suggest any features that involve what is called "AI" these days (aka LLM/GPT).
I am open to "normal" statistics (like the BPM detection).
Also, I _urge_ you not to use any of functionality provided here to make something resembling an "automapper", including (but not limited to) mass-parsing `.synth` files for AI-Training or exporting LLM-Output into a map.
This project is MIT-licensed, so I won't stop you, but please consider the implications of an auto-mapping, including:
* Rapid decrease of map quality, as LLMs will just go for what is "statistically likely", meaning boring, repetitive patterns and no "new" creative patterns
* Even further decrease, once training data includes automapped inputs
* Everyone can just get a mediocre map for whatever they want, leading to multiple maps for the same song (many of them similar)
* Just look at _other game_, where you have thousands of maps, but **need** curation to find the good ones.
* Currently, the majority is good, so you can just get all. With auto-mapped maps, that won't work, meaning multiplayer won't work as it does now.
* Dying out of the custom map community as it currently exists, as people won't have an incentive to learn mapping
* Insert more general talking points against LLMs here, e.g. energy usage, ethic training data, etc.
Raw data
{
"_id": null,
"home_page": null,
"name": "synth-mapping-helper",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": null,
"author": "adosikas",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/ce/e9/ed4e10f60cb33f32ae8d6eeb86398de2c7df59d1594659d3629058b5e512/synth_mapping_helper-1.5.18.tar.gz",
"platform": null,
"description": "# Synth Mapping Helper\n\nToolbox for manipulating the JSON-Format used by *Synth Riders Beatmap Editor* in the clipboard and `.synth` files.\n\n# Installation\n\n## Simple Installation (Windows)\n\nSimply download the latest `.exe` from the [Release Page](https://github.com/adosikas/synth_mapping_helper/releases).\n\nYou can just place it anywhere and run it, no installation needed.\n\nTo update, simply download the latest file. \nYou can enable checks for updates in the *Version History* Tab.\n\n## Advanced Installation\n\nIf you are unsure what any of the following means, you should go for the simple installation.\n\nThis is a PyPi package: `synth_mapping_helper`. \nThe main entry point for the GUI is `python3 -m synth_mapping_helper.gui` (or `smh-gui` if you got `$PATH` setup correctly).\n\nIf you want to implement highly custom stuff, you can interface with it directly, check out the [`example_scripts` directory](https://github.com/adosikas/synth_mapping_helper/tree/main/example_scripts) and the [Glossary on the wiki](https://github.com/adosikas/synth_mapping_helper/wiki/Glossary) to learn about how I represent positions, notes, rails and walls.\n\nA virtual environment is recommended for the installation:\n\n```sh\n# Initial installation\npython3 -m venv smh # create a virtual environment in a new \"smh\" directory\nsmh/bin/pip3 install synth_mapping_helper # install package and dependencies inside the venv\n# Starting GUI\nsmh/bin/smh-gui\n# Note that this calls smh-gui directly inside the venv, without entering it first.\n# So, you can just make a shortcut or .desktop file for that command.\n```\n\nTo update, either delete the venv and start over, or run `smh/bin/pip3 install --upgrade synth_mapping_helper`\n\n# GUI Features\n\n\nThe GUI works like a website running on your local machine (accessible only to you), and accesses the clipboard.\n\nIf you are overwhelmed by the amount of buttons, start with one segment at a time. \nYou can hover your mouse over pretty much all buttons and input fields to get a short tooltip.\n\nThe following is a list of features broken down by GUI tab:\n\n## Dashboard\n\n* Filter for type, rail length, and more\n* Switch between reference frames (absolute, relative to rail/wall or custom pivot)\n* **Offsetting** in X/Y and time\n* **Scaling** in X/Y and time\n * Note that wall sizes cannot scale, only their positions\n* Flattening in X/Y\n* **Mirroring** across X/Y and time, or with custom angle\n * Can optionally create a mirrored copy instead of replacing the original\n* **Rotation** in XY-plane\n * Walls also rotate as one would except (except crouch walls)\n* Add **parallel/crossover** patterns\n* **Merge and split rails**, even when there are gaps\n* Turn **rails into notes**, and **notes into rails**\n* Create **notestacks** or lightning rails\n* Shorten or extend rails\n* **Automatic rails smoothing**\n* Change type of notes\n* Add **spirals, zigzags or spikes** to any rail\n* Remove time gaps in wallart, or adjust spacing to stay below game limits\n\n## Stacking\n\n* Quickly create complex geometric wall or note patterns\n * Create spirals by using just pattern rotation and time offset\n * Create vortices by adding scaling and in/outset to spirals \n* Auto-Detection of parameters, which can then be iterated on\n* Subdivision of parameters allows smoother transitions\n* Optional randomisation for more organic patterns\n* Fast iteration via the **integrated 3D-preview**\n\n## Text\n\n* Automatically create walls to show text\n* Custom font support ([submissions welcome](https://github.com/adosikas/synth_mapping_helper/discussions/2))\n* _Please_, don't overuse text. So e.g. don't add _all_ lyrics.\n\n## Custom Wall Art Editor\n\n* _Please_, read the **build-in controls / shortcuts popup**\n* Fully 3D and using browser acceleration\n* Walls render with **transparency**\n* Highly customisable, with configurable snapping steps and custom color settings\n* Supports symmetry in almost real time (rotational and mirror)\n* **TurboStack**, for almost real time \"drag and drop\" stacking\n* Overlay **reference image** to create accurate wall art\n* **Compress wall-art** to remove time gaps\n* **Blender** to blend between two wall art patterns\n * Uses shortest rotation amount, taking into account symmetry\n * Note: Patterns must match in type and timing, Example:\n * First pattern: Square&Triangle at 10+0/64 and 10+1/64\n * Second pattern: Square&Triangle at 20+0/64 and 20+1/64 (at different XY & rotation)\n * Interpolate with interval 1/2 to create 19 intermediate patterns\n\n## Commands\n\n* Basic scripting support, replacing the legacy \"drag and drop onto smh.bat\" system\n* Chaining operations\n* Save frequently used operations as one-click **Quick run** button.\n* See the [wiki for syntax](https://github.com/adosikas/synth_mapping_helper/wiki)\n\n## File Utils\n\n* **Create `.synth` from any audio file**\n * While `.mp3`, etc are accepted, please prefer higher quality audio files\n* Output can be saved/downloaded, instead of landing in some hard-to-find location\n* Fix some common errors that can result in the editor refusing to open the file\n* **Automatic BPM detection**\n * Detection BPM & Offset can directly be applied to the file\n * Plot error between detected BPM and onsets (peaks) in the audio\n * Plot which shows when BPM drifts or changes throughout the song\n * In that case manual action is still required, but now you know what's going on instead of just getting a few low-confidence guesses\n* **Audio preview with beat ticks (metronome)** to check BPM / Offset\n* Fine tune BPM/Offset with quick buttons\n* **Adjust BPM/Offset without messing up existing content**\n* Pad or trim audio to tweak silence at beginning or end\n* **Merge files**, even when they have different BPM\n * This is very useful when mapping parts of a map at different BPM\n* Advanced statistics/analysis\n * Plot hand movement, velocity/speed and acceleration/g-force\n * Show various warnings\n * Note at head position (**vision block**)\n * Something to close to end of map\n * Patterns will look messed or be unplayable in spiral, due to a bug in the game\n * Plot nall density, and see if you reach the \"**wireframe limit**\"\n * Plot note/rail density to identify potentially laggy sections\n\n## AutoBackup\n\n* Periodically checks `.synth` files in a certain directory for changes and creates **backups**\n* Backups **never get deleted/overwritten**, so you can _always_ go back\n * You should cleaned up old backups once you are done with that map, as that is _not_ done automatically\n\n## Version History\n\n* **Check for a new version**, either manually or on every start\n* Show release notes, with **explaination of new features** (and typically a screenshot)\n * Last few releases only, full list [here](https://github.com/adosikas/synth_mapping_helper/releases)\n* Direct link to release for easy download (but no automatic download/install)\n\n# Technical information\n\nThe GUI is built with [NiceGUI](https://nicegui.io/), allowing me to write a \"frontend\" with pure python. Even the wall art editor is created from python, which is why I am not currently able to make a \"full editor\" as that requires some fully clientside logic (ThreeJS in particular). \nIf you have experience there and would like to help me make a proper editor (with native intergration for SMH, please let me know).\n\nIn the \"backend\" everything is python and numpy arrays, and uses fairly modular functions for the various operations. Feel free to experiment with using the API to make custom python scripts, but that requires the advanced installation (see above).\n\n# 100% LLM Free\n\nThis project (to the best of my knowledge) does not contain any LLM-Generated code.\n\nPlease do not suggest any features that involve what is called \"AI\" these days (aka LLM/GPT). \nI am open to \"normal\" statistics (like the BPM detection).\n\nAlso, I _urge_ you not to use any of functionality provided here to make something resembling an \"automapper\", including (but not limited to) mass-parsing `.synth` files for AI-Training or exporting LLM-Output into a map. \nThis project is MIT-licensed, so I won't stop you, but please consider the implications of an auto-mapping, including:\n\n* Rapid decrease of map quality, as LLMs will just go for what is \"statistically likely\", meaning boring, repetitive patterns and no \"new\" creative patterns\n* Even further decrease, once training data includes automapped inputs\n* Everyone can just get a mediocre map for whatever they want, leading to multiple maps for the same song (many of them similar)\n* Just look at _other game_, where you have thousands of maps, but **need** curation to find the good ones.\n* Currently, the majority is good, so you can just get all. With auto-mapped maps, that won't work, meaning multiplayer won't work as it does now.\n* Dying out of the custom map community as it currently exists, as people won't have an incentive to learn mapping\n* Insert more general talking points against LLMs here, e.g. energy usage, ethic training data, etc.\n",
"bugtrack_url": null,
"license": "MIT License\n \n Copyright (c) 2024 adosikas\n \n Permission is hereby granted, free of charge, to any person obtaining a copy\n of this software and associated documentation files (the \"Software\"), to deal\n in the Software without restriction, including without limitation the rights\n to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n copies of the Software, and to permit persons to whom the Software is\n furnished to do so, subject to the following conditions:\n \n The above copyright notice and this permission notice shall be included in all\n copies or substantial portions of the Software.\n \n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n SOFTWARE.\n ",
"summary": "Toolbox for manipulating the JSON-Format used by Synth Riders Beatmap Editor in the clipboard",
"version": "1.5.18",
"project_urls": {
"Bug Tracker": "https://github.com/adosikas/synth_mapping_helper/issues",
"Changelog": "https://github.com/adosikas/synth_mapping_helper/releases",
"Documentation": "https://github.com/adosikas/synth_mapping_helper/wiki",
"Homepage": "https://github.com/adosikas/synth_mapping_helper",
"Repository": "https://github.com/adosikas/synth_mapping_helper"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "7b25d7e462a3459c29d695ddf99229c5d28f60ec1a006856356559d06848c5d2",
"md5": "1f31e9a5ca810eed0ed01068e1c7095f",
"sha256": "356b1f3e2c03a4a156d6ed570eba7bb73a6bc01b465f6a2d55ccd655cb7405dd"
},
"downloads": -1,
"filename": "synth_mapping_helper-1.5.18-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1f31e9a5ca810eed0ed01068e1c7095f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 123491,
"upload_time": "2025-07-17T19:19:37",
"upload_time_iso_8601": "2025-07-17T19:19:37.257025Z",
"url": "https://files.pythonhosted.org/packages/7b/25/d7e462a3459c29d695ddf99229c5d28f60ec1a006856356559d06848c5d2/synth_mapping_helper-1.5.18-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "cee9ed4e10f60cb33f32ae8d6eeb86398de2c7df59d1594659d3629058b5e512",
"md5": "a9b34d4a5559a1a1b58427d51f889f6f",
"sha256": "f4d9f08854053b1f123a57796a47c179db499698982274e43ca618d7134847c3"
},
"downloads": -1,
"filename": "synth_mapping_helper-1.5.18.tar.gz",
"has_sig": false,
"md5_digest": "a9b34d4a5559a1a1b58427d51f889f6f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 114594,
"upload_time": "2025-07-17T19:19:38",
"upload_time_iso_8601": "2025-07-17T19:19:38.266794Z",
"url": "https://files.pythonhosted.org/packages/ce/e9/ed4e10f60cb33f32ae8d6eeb86398de2c7df59d1594659d3629058b5e512/synth_mapping_helper-1.5.18.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-17 19:19:38",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "adosikas",
"github_project": "synth_mapping_helper",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "synth-mapping-helper"
}
