A simple python library to read and write .nbs files from Note Block Studio
Project description
# pynbs
[![PyPI](https://img.shields.io/pypi/v/pynbs.svg)](https://pypi.org/project/pynbs/)
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/pynbs.svg)](https://pypi.org/project/pynbs/)
> A simple python library to read and write [.nbs files](http://www.stuffbydavid.com/mcnbs/format)
from [Note Block Studio](http://www.stuffbydavid.com/mcnbs). Compatible with
python 2 and 3.
`pynbs` makes it possible to easily iterate over Note Block Studio songs.
```python
import pynbs
for tick, chord in pynbs.read('demo_song.nbs'):
print(tick, [note.key for note in chord])
```
You can also use `pynbs` to generate new songs programmatically.
```python
import pynbs
new_file = pynbs.new_file(song_name='Hello world')
new_file.notes.extend([
pynbs.Note(tick=i, layer=0, instrument=0, key=i + 35) for i in range(10)
])
new_file.save('new_file.nbs')
```
## Basic usage
### Reading files
You can use the `read()` function to read and parse a specific nbs file.
```python
demo_song = pynbs.read('demo_song.nbs')
```
The `read()` function returns a `pynbs` file object. These objects have several
attributes that mirror the binary structure of nbs files.
#### Header
The first attribute is `header`, the file header. It contains information about
the file.
```python
header = demo_song.header
```
Attribute | Type | Details
:---------------------------|:--------|:------------------------------------------------
`header.song_length` | `int` | The length of the song, measured in ticks.
`header.song_layers` | `int` | The id of the last layer with at least one note block in it.
`header.song_name` | `str` | The name of the song.
`header.song_author` | `str` | The author of the song.
`header.original_author` | `str` | The original song author of the song.
`header.description` | `str` | The description of the song.
`header.tempo` | `float` | The tempo of the song.
`header.auto_save` | `bool` | Whether auto-saving has been enabled.
`header.auto_save_duration` | `int` | The amount of minutes between each auto-save.
`header.time_signature` | `int` | The time signature of the song.
`header.minutes_spent` | `int` | The amount of minutes spent on the project.
`header.left_clicks` | `int` | The amount of times the user have left clicked.
`header.right_clicks` | `int` | The amount of times the user have right clicked.
`header.blocks_added` | `int` | The amount of times the user have added a block.
`header.blocks_removed` | `int` | The amount of times the user have removed a block.
`header.song_origin` | `str` | The file name of the original midi or schematic.
> For more information about all these fields, check out the [official specification](http://www.stuffbydavid.com/mcnbs/format).
#### Notes
The `notes` attribute holds a list of all the notes of the song in order.
```python
first_note = demo_song.notes[0]
```
Attribute | Type | Details
:---------------- |:------|:------------------------------------------------
`note.tick` | `int` | The tick at which the note plays.
`note.layer` | `int` | The id of the layer in which the note is placed.
`note.instrument` | `int` | The id of the instrument.
`note.key` | `int` | The key of the note. (between 0 and 87)
#### Layers
The `layers` attribute holds a list of all the layers of the song in order.
```python
first_layer = demo_song.layers[0]
```
Attribute | Type | Details
:-----------------|:------|:------------------------
`layer.id` | `int` | The id of the layer.
`layer.name` | `str` | The name of the layer.
`layer.volume` | `int` | The volume of the layer.
#### Instruments
The `instruments` attribute holds a list of all the custom instruments of the
song in order.
```python
first_custom_instrument = demo_song.instruments[0]
```
Attribute | Type | Details
:----------------------|:-------|:----------------------------------------------------------
`instrument.id` | `int` | The id of the instrument.
`instrument.name` | `str` | The name of the instrument.
`instrument.file` | `str` | The name of the sound file of the instrument.
`instrument.pitch` | `int` | The pitch of the instrument. (between 0 and 87)
`instrument.press_key` | `bool` | Whether the piano should automatically press keys with the instrument when the marker passes them.
### Iterating over songs
Iterating over a `pynbs` file object yields consecutively all the chords of the song with
the associated tick.
```python
for tick, chord in demo_song:
...
```
`chord` is a list of all the notes that play during the tick `tick`.
### Creating new files
You can create new files using the `new_file()` function. The function lets
you specify header attributes with keyword arguments.
```python
new_file = pynbs.new_file(song_name='Hello world')
```
The function returns a new `pynbs` file object that you can now edit
programmatically.
### Saving files
You can use the `save()` method to encode and write the file to a specified
location.
```python
new_file.save('new_file.nbs')
```
---
License - [MIT](https://github.com/vberlier/pynbs/blob/master/LICENSE)
[![PyPI](https://img.shields.io/pypi/v/pynbs.svg)](https://pypi.org/project/pynbs/)
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/pynbs.svg)](https://pypi.org/project/pynbs/)
> A simple python library to read and write [.nbs files](http://www.stuffbydavid.com/mcnbs/format)
from [Note Block Studio](http://www.stuffbydavid.com/mcnbs). Compatible with
python 2 and 3.
`pynbs` makes it possible to easily iterate over Note Block Studio songs.
```python
import pynbs
for tick, chord in pynbs.read('demo_song.nbs'):
print(tick, [note.key for note in chord])
```
You can also use `pynbs` to generate new songs programmatically.
```python
import pynbs
new_file = pynbs.new_file(song_name='Hello world')
new_file.notes.extend([
pynbs.Note(tick=i, layer=0, instrument=0, key=i + 35) for i in range(10)
])
new_file.save('new_file.nbs')
```
## Basic usage
### Reading files
You can use the `read()` function to read and parse a specific nbs file.
```python
demo_song = pynbs.read('demo_song.nbs')
```
The `read()` function returns a `pynbs` file object. These objects have several
attributes that mirror the binary structure of nbs files.
#### Header
The first attribute is `header`, the file header. It contains information about
the file.
```python
header = demo_song.header
```
Attribute | Type | Details
:---------------------------|:--------|:------------------------------------------------
`header.song_length` | `int` | The length of the song, measured in ticks.
`header.song_layers` | `int` | The id of the last layer with at least one note block in it.
`header.song_name` | `str` | The name of the song.
`header.song_author` | `str` | The author of the song.
`header.original_author` | `str` | The original song author of the song.
`header.description` | `str` | The description of the song.
`header.tempo` | `float` | The tempo of the song.
`header.auto_save` | `bool` | Whether auto-saving has been enabled.
`header.auto_save_duration` | `int` | The amount of minutes between each auto-save.
`header.time_signature` | `int` | The time signature of the song.
`header.minutes_spent` | `int` | The amount of minutes spent on the project.
`header.left_clicks` | `int` | The amount of times the user have left clicked.
`header.right_clicks` | `int` | The amount of times the user have right clicked.
`header.blocks_added` | `int` | The amount of times the user have added a block.
`header.blocks_removed` | `int` | The amount of times the user have removed a block.
`header.song_origin` | `str` | The file name of the original midi or schematic.
> For more information about all these fields, check out the [official specification](http://www.stuffbydavid.com/mcnbs/format).
#### Notes
The `notes` attribute holds a list of all the notes of the song in order.
```python
first_note = demo_song.notes[0]
```
Attribute | Type | Details
:---------------- |:------|:------------------------------------------------
`note.tick` | `int` | The tick at which the note plays.
`note.layer` | `int` | The id of the layer in which the note is placed.
`note.instrument` | `int` | The id of the instrument.
`note.key` | `int` | The key of the note. (between 0 and 87)
#### Layers
The `layers` attribute holds a list of all the layers of the song in order.
```python
first_layer = demo_song.layers[0]
```
Attribute | Type | Details
:-----------------|:------|:------------------------
`layer.id` | `int` | The id of the layer.
`layer.name` | `str` | The name of the layer.
`layer.volume` | `int` | The volume of the layer.
#### Instruments
The `instruments` attribute holds a list of all the custom instruments of the
song in order.
```python
first_custom_instrument = demo_song.instruments[0]
```
Attribute | Type | Details
:----------------------|:-------|:----------------------------------------------------------
`instrument.id` | `int` | The id of the instrument.
`instrument.name` | `str` | The name of the instrument.
`instrument.file` | `str` | The name of the sound file of the instrument.
`instrument.pitch` | `int` | The pitch of the instrument. (between 0 and 87)
`instrument.press_key` | `bool` | Whether the piano should automatically press keys with the instrument when the marker passes them.
### Iterating over songs
Iterating over a `pynbs` file object yields consecutively all the chords of the song with
the associated tick.
```python
for tick, chord in demo_song:
...
```
`chord` is a list of all the notes that play during the tick `tick`.
### Creating new files
You can create new files using the `new_file()` function. The function lets
you specify header attributes with keyword arguments.
```python
new_file = pynbs.new_file(song_name='Hello world')
```
The function returns a new `pynbs` file object that you can now edit
programmatically.
### Saving files
You can use the `save()` method to encode and write the file to a specified
location.
```python
new_file.save('new_file.nbs')
```
---
License - [MIT](https://github.com/vberlier/pynbs/blob/master/LICENSE)
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distributions
No source distribution files available for this release.See tutorial on generating distribution archives.
Built Distribution
Close
Hashes for pynbs-0.2.2-py2.py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 27d7a77729a5ab0bbce32782064a9912ff8f82d3effb1b695dc86e9534e8e54f |
|
MD5 | 8efcdc8184c511b399347dd4f2435de0 |
|
BLAKE2b-256 | f7615d075c0d4fece0add02808325ad278abc45016bf8dcc6feab07b9610b024 |