# nbswave
A Python package to render note block songs to a variety of audio formats.
## Overview
nbswave is a Python package aimed at rendering note block songs from [Open Note Block Studio](https://opennbs.org/) to audio tracks. Supports many common audio formats, both for loading custom sounds as well as exporting tracks.
## Setup
The package can be installed with `pip`.
```shell
$ pip install nbswave
```
In order to use the package, [FFmpeg](https://www.ffmpeg.org/) must be available:
1. Download precompiled binaries for `ffmpeg` and `ffprobe` [here](https://ffbinaries.com/downloads).
2. Add the destination folder to your `PATH`, or, alternatively, place both executables in the root folder of the project.
## Usage
```python
from nbswave import *
render_audio("song.nbs", "output.mp3")
```
The output format will be detected automatically based on the file extension. You can still specify it explicitly if you'd like:
```python
from nbswave import *
render_audio("song.nbs", "output", format='wav')
```
> [!NOTE]
> Compatibility with audio formats depends on your FFmpeg configuration.
### Custom instruments
In order to render songs with custom instruments, you have a few options:
1. Copy the sounds manually to the `sounds` folder
2. Pass the path to a folder (or ZIP file) containing custom sounds:
```python
from pathlib import Path
nbs_sounds_folder = Path.home() / "Minecraft Note Block Studio" / "Data" / "Sounds"
render_audio("song.nbs", "output.mp3", custom_sound_path=nbs_sounds_folder)
```
If any sound file used in the song is not found in that location, a `MissingInstrumentException` will be raised. This behavior can be suppressed with the following argument:
```python
render_audio("song.nbs", "output.mp3", ignore_missing_instruments=True)
```
### Advanced usage
For more advanced use cases where you might need more control over the export process, it's possible to use the `SongRenderer` class. This will allow you to load custom instruments from multiple sources, as well as query which instruments are still missing:
```python
from nbswave import *
renderer = SongRenderer("song.nbs")
renderer.load_instruments(nbs_sounds_folder)
renderer.load_instruments("some_more_instruments.zip")
renderer.missing_instruments()
track = renderer.mix_song()
track.save("song.mp3")
```
> [!TIP]
> For additional parameters, check out the source code!
## Contributing
Contributions are welcome! Make sure to open an issue discussing the problem or feature suggestion before creating a pull request.
This project uses [poetry](https://python-poetry.org/) for managing dependencies. Make sure to install it, and run:
```shell
$ poetry install
```
This project follows the [black](https://github.com/psf/black) code style. Import statements are sorted with [isort](https://pycqa.github.io/isort/).
```shell
$ poetry run isort nbswave
$ poetry run black nbswave
$ poetry run black --check nbswave
```
---
License - [MIT](https://github.com/Bentroen/nbswave/blob/main/LICENSE)
Raw data
{
"_id": null,
"home_page": "https://github.com/Bentroen/nbswave",
"name": "nbswave",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.13,>=3.8",
"maintainer_email": null,
"keywords": "minecraft, note-block-studio, noteblock, nbs, audio",
"author": "Bentroen",
"author_email": "bemcdc@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/8c/ad/a5e4d0ba18f53b091118b36b90529d6cfc4aba8f1b55f6eba29c9779d6c6/nbswave-0.4.0.tar.gz",
"platform": null,
"description": "# nbswave\n\nA Python package to render note block songs to a variety of audio formats.\n\n## Overview\n\nnbswave is a Python package aimed at rendering note block songs from [Open Note Block Studio](https://opennbs.org/) to audio tracks. Supports many common audio formats, both for loading custom sounds as well as exporting tracks.\n\n## Setup\n\nThe package can be installed with `pip`.\n\n```shell\n$ pip install nbswave\n```\n\nIn order to use the package, [FFmpeg](https://www.ffmpeg.org/) must be available:\n\n1. Download precompiled binaries for `ffmpeg` and `ffprobe` [here](https://ffbinaries.com/downloads).\n2. Add the destination folder to your `PATH`, or, alternatively, place both executables in the root folder of the project.\n\n## Usage\n\n```python\nfrom nbswave import *\n\nrender_audio(\"song.nbs\", \"output.mp3\")\n```\n\nThe output format will be detected automatically based on the file extension. You can still specify it explicitly if you'd like:\n\n```python\nfrom nbswave import *\n\nrender_audio(\"song.nbs\", \"output\", format='wav')\n```\n\n> [!NOTE]\n> Compatibility with audio formats depends on your FFmpeg configuration.\n\n### Custom instruments\n\nIn order to render songs with custom instruments, you have a few options:\n\n1. Copy the sounds manually to the `sounds` folder\n\n2. Pass the path to a folder (or ZIP file) containing custom sounds:\n\n```python\nfrom pathlib import Path\n\nnbs_sounds_folder = Path.home() / \"Minecraft Note Block Studio\" / \"Data\" / \"Sounds\"\nrender_audio(\"song.nbs\", \"output.mp3\", custom_sound_path=nbs_sounds_folder)\n```\n\nIf any sound file used in the song is not found in that location, a `MissingInstrumentException` will be raised. This behavior can be suppressed with the following argument:\n\n```python\nrender_audio(\"song.nbs\", \"output.mp3\", ignore_missing_instruments=True)\n```\n\n### Advanced usage\n\nFor more advanced use cases where you might need more control over the export process, it's possible to use the `SongRenderer` class. This will allow you to load custom instruments from multiple sources, as well as query which instruments are still missing:\n\n```python\nfrom nbswave import *\n\nrenderer = SongRenderer(\"song.nbs\")\n\nrenderer.load_instruments(nbs_sounds_folder)\nrenderer.load_instruments(\"some_more_instruments.zip\")\n\nrenderer.missing_instruments()\n\ntrack = renderer.mix_song()\n\ntrack.save(\"song.mp3\")\n```\n\n> [!TIP]\n> For additional parameters, check out the source code!\n\n## Contributing\n\nContributions are welcome! Make sure to open an issue discussing the problem or feature suggestion before creating a pull request.\n\nThis project uses [poetry](https://python-poetry.org/) for managing dependencies. Make sure to install it, and run:\n\n```shell\n$ poetry install\n```\n\nThis project follows the [black](https://github.com/psf/black) code style. Import statements are sorted with [isort](https://pycqa.github.io/isort/).\n\n```shell\n$ poetry run isort nbswave\n$ poetry run black nbswave\n$ poetry run black --check nbswave\n```\n\n---\n\nLicense - [MIT](https://github.com/Bentroen/nbswave/blob/main/LICENSE)\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "An utility to render note block songs to a variety of audio formats",
"version": "0.4.0",
"project_urls": {
"Homepage": "https://github.com/Bentroen/nbswave",
"Repository": "https://github.com/Bentroen/nbswave"
},
"split_keywords": [
"minecraft",
" note-block-studio",
" noteblock",
" nbs",
" audio"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "fe4b0ff33812780b29c56de1148c2ab2b0530676cf9ebe15eea35f5626b882c2",
"md5": "2e96d2f712202dc561f75ca652f912ad",
"sha256": "d0a583cbb0c6406e62ca82a6caeb499731c6a59d2765a9bc803a82b3ec9334d0"
},
"downloads": -1,
"filename": "nbswave-0.4.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2e96d2f712202dc561f75ca652f912ad",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.13,>=3.8",
"size": 10862,
"upload_time": "2024-07-09T23:42:08",
"upload_time_iso_8601": "2024-07-09T23:42:08.489501Z",
"url": "https://files.pythonhosted.org/packages/fe/4b/0ff33812780b29c56de1148c2ab2b0530676cf9ebe15eea35f5626b882c2/nbswave-0.4.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "8cada5e4d0ba18f53b091118b36b90529d6cfc4aba8f1b55f6eba29c9779d6c6",
"md5": "99d8825084f1ddeb6d42f6722deae0a9",
"sha256": "dbac8353cfa8603356ad3ec41d2ba0247cb6530a36fd076d503c67bff9056fa5"
},
"downloads": -1,
"filename": "nbswave-0.4.0.tar.gz",
"has_sig": false,
"md5_digest": "99d8825084f1ddeb6d42f6722deae0a9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.13,>=3.8",
"size": 9179,
"upload_time": "2024-07-09T23:42:10",
"upload_time_iso_8601": "2024-07-09T23:42:10.092653Z",
"url": "https://files.pythonhosted.org/packages/8c/ad/a5e4d0ba18f53b091118b36b90529d6cfc4aba8f1b55f6eba29c9779d6c6/nbswave-0.4.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-07-09 23:42:10",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Bentroen",
"github_project": "nbswave",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "nbswave"
}
JSON
