How To Start Editing Duplex Files

satobox · January 13, 2011, 5:34am

[Intro]

Maybe there are some people who are interested in making their own Duplex files, but since it seems to be difficult, they cannot start editing. So I try to explain how to start editing Duplex files here. Actually, it is not so difficult as you’ve worried by the looks. Lua scripting skill is not necessary almost.

First of all, this explanation was made in order to supplement the Duplex manual. Many important things are described in the manual. So I strongly recommend referring to it. (Japanese is here)

[About directory of Duplex]

Basically, you need to make these files and folders like below. And the files and folders should be renamed to the name of your controller properly.

2772

YourControllerName (folder)

– Configrations (folder) — FunctionalName.lua (for configrations & application mappings)

– Controlmaps (folder) — YourControllerName.xml (for specifying the layout of knobs, buttons, and faders)

– YourControllerName.bmp (the thumbnail picture of your controller)

– YourControllerName.lua (for additional configrations, color code, etc)

Since it is difficult for a beginner to start making these from scratch, I prepared the files for a fictitious controller called “R-control” . If you want to make these files to be for your controller, please change the part described “R-control” in the files (and all file names too) to your controller name.

2817 R-control.zip
Download and unzip this file, and put the “R-control” folder to;

Windows: C:\Users\YourName\AppData\Roaming\Renoise\V?.?.?\Scripts\Tools\com.renoise.Duplex.xrnx\Duplex\Controllers

OSX: Macintosh HD\Users\YourName\Library\Preferences\Renoise\V?.?.?\Scripts\Tools\com.renoise.Duplex.xrnx\Duplex\Controllers

Linux: a hidden folder in the user’s home folder: ~YourName/.renoise/V?.?.?/Scripts/Tools/com.renoise.Duplex.xrnx/Duplex/Controllers

Also, you can open the Renoise Preferences folder by clicking Renoise’s main menu [Help] >> [Show the Preferences Folder…]. Then follow the path Scripts/Tools/com.renoise.Duplex.xrnx/Duplex/Controllers

then click the Renoise’s main menu [Tools] >> [Reload all Tools]. After that, you can find “R-control Mixer + Transport…” in the Duplex config list.

#########################################################################

To enable the Renoise’s Scripting Treminal & Editor, please read this page.

2775

#########################################################################

[Explanation of each file]

R-control.xml

This xml file is for specifying the layout of knobs, buttons, and faders. Making layout is not so difficult if you have an experience of making simple web layout etc.
However, only by making this xml file, you cannot open the Duplex’s Browser. In order to check the actual graphic interface, it is needed both “R-control.xml” and “R-control_MixerTransport.lua”.

1569

R-control_MixerTransport.lua

This lua file is for some configrations & application mappings. Here, you can map each application to the group of knobs and buttons which specified within the xml file above.

Also, if you want to add another new application mappings to your controller, you should make the same kind of this file separately (i.e. “R-control_Effect.lua”, for example).

[Note]: In some case of the controller with the buttons which change their color (for example Launchpad), it’s necessary to add some special code to the “R-control.lua” file. In such a case, since it is difficult for a beginner, please ask for advice in the forum.

1568

Application files

The application files are functional files equipped in Duplex by default. You do not need to edit those files at all.
Currently there are 7 applications (Effect, Matrix, Mixer, Navigator, Recorder, StepSequencer, Transport). Each app have some useful functional mappings. So you should open and see each file to know the mapping names which you want to use.

1570

[Let’s try]

Probably, in order to complete the layout which you desire, it will be required some trial and error like;

Edit xml & lua files for your controller
Save these files
Reload all Tools
Open Duplex Browser and check whether the layout/mapping works well or not
Edit again
…

When you are stuck, try to refer to the Duplex manual, seek and learn from the other Duplex files, or ask in the forum. Though you need perseverance a bit, when Duplex works as you thought, you will be impressed. Let’s try.

Safekeeping is recommended!!###############################

If you want to update Duplex itself, remember that all device configurations and settings are backed to default.
This means, your custom configuration maps are lost completely too.
Unfortunately, this is a Renoise script tool’s feature, so please don’t forget to copy your custom configuration files to another place always.

########################################################

P.S. I welcome the correction without notice if there is strange words or explanations.

Conner_Bw · January 13, 2011, 5:02pm

I’m not sure why, but the scrollbar disappears in my web-browser when reading this post. (Safari on OSX)

Edit: Nevermind, after replying it’s back to normal. Thanks Satobox!

eeter · January 13, 2011, 10:29pm

Great post Sato!! Much appreciated!

Cornbeast · March 2, 2011, 7:01am

Great post! Just what I needed to get started…

James_Britt · March 9, 2012, 7:58pm

The link to the Duplex manual ("First of all, this explanation was made in order to supplement the Duplex manual. ") just links back to this page.

danoise · March 9, 2012, 8:11pm

Hmm, works here. Your browser either does not accept downloads or you have no PDF reader installed?
You can right-click the link and save the file, right? Then get something like the Foxit PDF reader (Windows) if you don’t like bloated Adobe software

fuzzcreatorhasenpfef · June 19, 2014, 5:24am

Its a few years later but…just wanted to add my thanks and appreciation to all for this thread. Once I have the time to get into lua-scripting I know this will be helpful in getting organized and on the good foot!

danoise · June 19, 2014, 10:28am

Luckily the information is still largely relevant.

From my side, focus has however shifted toward documenting the project using comments within the code itself, and then creating HTML files from that (look inside the /Docs folder that come with Duplex).
Doing it like this makes the information more likely to be fully up to date, and closely tied to the actual source code instead of being spread all over the place.

But nevertheless, satobox did a very good job here. This article will probably survive, whereas the PDF manual will slowly go more and more out of date.

Alexander_M_Korn · May 21, 2016, 11:38am

can somebody confirm, that the application options overwrite in the controller configuration not working at all!

I tried everything … also deleting the Duplex preferences.xml and restarting Renoise and Duplex completely.

applications = {
 StepSequencer = {
 -- ORIENTATION.VERTICAL layout (default)
 mappings = {
 grid = {
 group_name = "Grid",
 orientation = ORIENTATION.HORIZONTAL,
 },
 },
 options = {
        ### NOT WORKING ###
 line_increment = 8,
 follow_track = 1,
 page_size = 5,
 }

danoise · May 21, 2016, 11:42am

can somebody confirm, that the application options overwrite in the controller configuration not working at all!

A device configuration is nothing but a starting point (acting as default settings).
Once you have launched Duplex it stores your settings - so you will need to delete the preferences.xml to revert back to the defaults.

To delete the settings you will need to disable the tool (Tool Browser), delete the file and restart the tool.

Alexander_M_Korn · May 21, 2016, 11:49am

Ok. Disabling the tool was the missing step! Thanks!

boonier · November 27, 2018, 10:07am

I’m making a new Duplex mapping for a new controller and using this R-control as a starting block for it.

When I try loading reloading the Duplex tool I get this error:

...-control/Configurations/R-control_MixerTransport.lua:22: variable 'DEVICE_MIDI_PROTOCOL' is not declared
stack traceback:
  [C]: in function '_error'
  [string "local mt = getmetatable(_G)..."]:29: in function <[string "local mt = getmetatable(_G)..."]:24>
  ...-control/Configurations/R-control_MixerTransport.lua:22: in main chunk
  [C]: in function 'require'
  ./Duplex.lua:103: in main chunk
  [C]: in function 'require'
  main.lua:7: in main chunk

I haven’t made any alterations - this is just the boilerplate out of the box.

Changes to the Lua version api since this was created, or something far simpler?

thanks

danoise · November 27, 2018, 10:49am

Uh, let me check this tonight. Indeed it might be slightly outdated information.

boonier · November 27, 2018, 11:27am

ah I think this might be the culprit:

DEVICE_MIDI_PROTOCOL

should be

DEVICE_PROTOCOL.MIDI

seems to work now

thanks @danoise