rnsutils/README.rst

RnsUtils
========

RnsUtils is Renoise related library and companion utility.
It is meant for developers aiming to use generate renoise
file or renoise users wanting to convert SoundFont 2 to
renoise instruments

Installation
------------

RnsUtils is installable from PyPI with a single pip command::

    pip install rnsutils

Alternatively, RnsUtils can be run directly from sources after a git pull::

    git clone https://gitlab.com/zeograd/rnsutils.git
    cd rnsutils && python setup.py install


sf2toXrni
---------

**sf2toxrni** is a command line utility which convert SoundFont 2 instruments into renoise instruments (.xrni).
It parses a SoundFont 2 file instrument list and generate one .xnri file for each instrument using as much information
from the SoundFont 2 instrument properties (generators) as possible. All read properties will be injected in a template
renoise instrument.

::

    usage: sf2toxrni [-h] [-d] [-q] [-u] [--no-unused] [-o OUTPUT_DIR]
                     [-t TEMPLATE]
                     sf2_filename

    GPL v3+ 2016 Olivier Jolly

    positional arguments:
      sf2_filename          input file in SoundFont2 format

    optional arguments:
      -h, --help            show this help message and exit
      -d, --debug           debug parsing [default: False]
      -q, --quiet           quiet operation [default: False]
      -u, --unused          show unused generators [default: True]
      --no-unused
      -o OUTPUT_DIR, --ouput-dir OUTPUT_DIR
                            output directory [default: current directory]
      -t TEMPLATE           template filename [default: empty-31.xrni]

    Convert sf2 file into renoise instrument


Use the *-o* option to specify a destination directory and *--no-unused* if you don't want to see the list of generators
which are present in the SoundFont 2 file but were not used in generating the .xnri.

*-t* allows to change the template .xnri, one is provided by default and works with renoise 3.1 at least. If you want
different default settings or generate instruments for a different version, you can provide a template of your own
and specify its filename. If the filename is not found on the filesystem, it will be looked up in the default
data patch for the python package.
If you want to provide your own template, it must follow the recommendations of the following section.

template
........

A template .xnri file will be used to have Soundfont 2 properties injected to produce a final, customized .xnri file.
It must contains at least one sample. The first sample will be used as template for all samples, others will be discarded.
The first sample must have an ADHSR modulation on volume and the filter set to a Low pass filter.
SoundFont 2 reverb and chorus effects will be mapped respectively on macro 1 and macro 2, so you may want to map those macros
on input of DSP chains to control the dry/wet amount of those effects.
You may use macro 3 and up to your liking.

compliance and limitations
..........................

The set of features found in a SoundFont 2 and .xnri doesn't fully overlap, hence this converter won't produce
a bit wise exact instrument.
First, SoundFont 2 files contains presets, which are mapped to one or more instruments. Those presets might alter how
the instruments sound, but it's a bad practice and usually only map keys range to instruments. This converter works
from SoundFont 2 instruments only.

**sf2toxrni** supports :
    * envelope volume release
    * sample panning
    * sample looping
    * sample tuning (base note, fine and coarse tuning)
    * key mapping
    * velocity mapping
    * low pass filter cutoff
    * chorus amount
    * reverb amount

**sf2toxrni** does not support :
    * vibrato
    * initial volume attenuation (always minus infinite in result, it seems like it'd be a pita to support otherwise)

Library use
-----------

Current, only renoise instrument API is available.
A renoise instrument is represented by the **RenoiseInstrument** class and can be loaded that way::

    from rnsutils.instrument import RenoiseInstrument
    # load an instrument from an existing xnri
    inst = RenoiseInstrument('existing.xrni')
    # now, inst.root is an objectified xml tree you can access and alter
    # inst.sample_data is a mutable list of audio files content
    inst.save('new.xrni')