From 06a625d678b78238d9f6d831d8ac7678b665ffc9 Mon Sep 17 00:00:00 2001 From: Olivier Jolly Date: Wed, 27 Jan 2016 23:52:41 +0100 Subject: [PATCH] Complete basic documentation --- README.rst | 84 ++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 81 insertions(+), 3 deletions(-) diff --git a/README.rst b/README.rst index 6fbb7c6..42e01a6 100644 --- a/README.rst +++ b/README.rst @@ -3,7 +3,7 @@ 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 +file or renoise users wanting to convert SoundFont 2 to renoise instruments Installation @@ -22,9 +22,87 @@ Alternatively, RnsUtils can be run directly from sources after a git pull:: sf2toXrni --------- -Describe *sf2toxrni* here +**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 ----------- -Describe library usage +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')