A novice‘s supplement to the WALTER Themer’s Guide

[Dyl]

Resources:
https://www.reaper.fm/sdk/walter/walter.php#elements

http://www.houseofwhitetie.com/reape...mers_guide.pdf

In this primer I’ve detailed some common tasks that are essential to get right before you can begin with WALTER. The Themer’s Guide, quite rightly, focuses on WALTER. However, coming from a non-coding background I found I could not get started even on the basic tasks laid out in part one. So, I’ve pulled together stuff from across the Reaper forums and combined it with some of my own ideas to enable anyone to get ready for WALTER. I’m not laying claim to any of this information and much of it is on the forums. Unfortunately, for a novice, it’s really hard to draw it all together and make sense of things when you have no real idea how it all works. I spent days just trying to figure out how to save my own Reaper theme, for example.
So, if you want to get started with WALTER please read on, these notes should help you.

Bullet points highlight the key steps, dialogue offers additional detail. Please try this and feedback any errors or omissions.
main points covered:

1/ unpacking an existing theme.
2/ clearing the WALTER code out of an existing theme to get an empty Track Control Panel (TCP).
3/ testing progress and my mistakes.
4/ packing up a theme and saving it under a new name.
5/ cleaning up the ColorThemes folder and more progress testing.
6/ adding elements to your theme’s TCP and the 8 number system.
7/ opening your theme for editing.

Basic computer skills are assumed, opening/saving, zipping/unzipping and renaming files/folders, that sort of thing. I had my wife play test this stuff and she unravelled with zip folders and text editors. Everything else worked so as long as you can zip and edit text you will be fine.

1/ unpacking an existing theme
The WALTER Themer’s Guide says find a WALTERless theme or create a new one from scratch. This seemed unrealistic for a novice. Instead of worrying how to do either task I figured out how to open an existing theme, clean it out and save it under a new name. The first steps...

• watch this video it’s really clear:
http://www.houseofwhitetie.com/reape...dit_def_5.html

or

• Open Reaper Options menu > show REAPER resource path in explorer/finder.
• Open the ColorThemes folder
• Rename the Reaper theme called Default_4.0.ReaperThemeZip to
Default_4.0.ReaperTheme.Zip.
Note the “.” between “Theme” and “Zip”. That’s all it needs.
This changes the theme file to a zipped folder, still in the ColorThemes
folder.
• Unzip this folder into the ColorThemes folder (important to get right, or it
won’t work).



Check for a Default_4.0_unpacked folder and Default_4.0_unpacked.ReaperTheme file in the ColorThemes folder. If your unzipping process placed them in a new folder in the ColorThemes folder (or anywhere else) you will need to put them directly in the ColorThemes folder.

That’s it. You can check your work by opening the Reaper Options menu > Themes. If you’ve done things correctly you should see a theme called Default_4.0_unpacked. Opening this in Reaper looks exactly the same as the default 4 theme. You’ve not made any changes yet, you have just unpacked a theme though.

2/ clearing the WALTER code out of an existing theme to get an empty TCP panel
The WALTER Themer's guide clearly shows how this is done. However, the rtconfig.txt is way more complex looking compared to the guide pdf examples. Rather than work through code I couldn’t understand I just cleaned it all out. Glancing back at the WALTER commands I now see only a few key words to look for. When you are just starting out this can seem pretty daunting. So, try the method below and go back to the WALTER reference after a few runs at this. It will look easier...

• Open the Default_4.0_unpacked folder created in section one (above).
• Search the folder for the rtconfig.txt file.
• Open this file in a text editor (Notepad++ is really good, allows highlighting and line numbering).
• Scroll down the rtconfig.txt file to find the line that looks like ;-----WALTER------.
• Keep the two lines under this, i.e., “clear tcp.*” and “set tcp.size [400 100 160]”.
• Delete all lines down to “Layout Tracking” (keep this one, delete up to, not including).
• Save the rtconfig.txt file.

At this stage you’ve cleared out all the WALTER commands (well, those for the task in hand) that will allow you to see an empty TCP panel (coming up). In the SDK page (link above) you will see examples of the code you’ve just cleared out of the rtconfig.txt file. This was pretty advanced code but it is all built up from the basic format of a command and an expression. The commands are listed on the online reference page along with a useful list of elements to add to your TCP; remember this it will be helpful later. The WALTER Themer's guide discusses commenting out code on page 8 but because the deleted code was quite complex it just seemed easier to cut it and start from scratch.
Notepad++ allows you to keep the edited rtconfig file open. As long as you save it Reaper won’t have any problem running it. I cannot say how other text editors behave, you may need to close the file and reopen it after you’ve checked your work in Reaper.

3/ testing progress and my mistakes
You can test progress in a couple of ways. First, look at…

• Options > Themes menu and check for the Default_4.0_ unpacked theme.

If you don’t see this theme go back to section 1 and double check your steps. Make sure you have both the unpacked folder and ReaperTheme listed in the ColorThemes folder. Several times I unzipped into another folder. I also unzipped into AppData\ROAMING\Reaper location (where??). Default_4.0 is not it, it’s got to be the unpacked version. If you haven’t got the unpacked version you’ve missed something. Go back, try again.

This next step was the trickiest for me, I regularly failed to refresh the Reaper theme and this hides any changes you might have made. If you were looking at the unpacked theme and then made changes to the rtconfig file you won’t see the changes unless you recycle the theme you are working on.

• Switch to another Reaper theme (from Options > Themes menu) and then switch back to the unpacked theme.

I also found I could open a theme by double clicking the ReaperThemes files in the ColorThemes folder.

When you now look at the Default_4.0_unpacked theme (refreshed as described above) you should see nothing at all in your TCP in the Reaper project. Don’t forget to have a project open or at least one track open in the TCP. I forgot many times and it’s not helpful.

4/ packing up a theme and saving it under a new name (your choice)
This step is crucial if you want to save your own theme. There are some quirks that occur during this process but it’s straightforward when you think about what you are trying to achieve.
You are basically looking to repack everything and call it something new and relevant to you.
The following steps are the easiest way I found of carrying out the task…

• Open the ColorThemes folder
• Create a new zip folder and give it a name like this example:
Dyl.ReaperThemeZip.zip
The “.zip” part will be added when you create the zip folder (I didn’t know this!). Just make sure it ends Zip.zip when you’ve saved it
• Cut and paste the Default_4.0_unpacked folder into your new zipped folder
• Cut and paste the Default_4.0_unpacked.ReaperTheme file into the zipped folder
• Rename the zipped folder removing the “.zip” from the name. eg, Dyl.ReaperThemeZip.zip
would become Dyl.ReaperThemeZip.

Now the zip folder icon should change to the reaper theme icon. If you still see the unpacked files/folders in the ColorThemes folder, you can delete these.

The quirks? Well, I couldn’t change the name of the unpacked folder or file so that Reaper made the links. In other words it failed to open correctly when I changed the unpacked file names to match my theme’s name.
Also, when I came to reopen my theme it opened the renamed files as Default_4.0_unpacked regardless of what I renamed them. Also, when I looked at the listed themes in the Options > Themes menu the Default_4.0_unpacked theme showed up regardless of what I renamed it in the ColorThemes folder. You may come across these issues and that’s the only reason I’m describing them. I don’t know how to fix them but I know the bullet-pointed steps work.

5/ cleaning up the themes folder (if required) and more progress testing
If you’ve managed section 4 you probably don’t need to read this section but you will need to change the Default_4.0.ReaperTheme.Zip folder back to a ReaperTheme file. To do this…

• Rename the Default_4.0.ReaperTheme.Zip as Default_4.0.ReaperThemeZip.

You should have previously cut and paste two unpacked folders/files into a zipped file of your choosing. If you copied these instead you can delete them from the ColorThemes folder (after you’ve checked they are copied in your theme zip folder).

To check everything is fine, look through the ColorThemes folder. There should be no “unpacked” files or folders. There shouldn’t be any zipped folders in ColorThemes either.
Check Reaper menu > Options > Themes. The listed themes should not include unpacked themes and your named theme should be listed, in my example, Dyl.

Select your theme and it should display a TCP with no elements in it. If you have a display of very old looking graphics in your TCP then you’ve probably not packed up/zipped up your theme correctly. This is really old Reaper code showing as the default, apparently. By now you know what to do.



part 2 to follow...

[Dyl]

following on from part 1...



6.1/ adding elements to your theme’s TCP and the 8 number system
Now to play with some WALTER. Refer to section 1, this is the same process applied to your own theme rather than Default_4.0…

• Open Reaper Options menu > show REAPER resource path in explorer/finder.
• Open the ColorThemes folder and prepare to unpack your own theme.
• Rename the Reaper theme, e.g., Dyl.ReaperThemeZip to Dyl.ReaperTheme.Zip.
Note the “.” between “Theme” and “Zip”.
This changes the theme file to a zipped folder, still in the ColorThemes folder.
• Unzip this folder into the ColorThemes folder.

If you read the quirks in section 4 here’s a couple more that cause head scratch…

Do the bullet point but be aware of the naming because you’ll be using these unpacked files/folders.

• Check for a Default_4.0_unpacked folder and Default_4.0_unpacked.ReaperTheme file in the ColorThemes folder. If your unzipping process placed them in a new folder in the ColorThemes folder (or anywhere else) you will need to put them directly in the ColorThemes folder.

Looks familiar? Remember the process? But note for whatever reason the files/folders you packed into your theme will not work if you try to rename them according to your theme. I don’t understand why not but found it best to roll with it. It works, so…

Just like in section 1, the Reaper Options > Themes menu will show Default_4.0_unpacked. This is the theme you are working on. Don’t worry it doesn’t have a name relating to your theme. You will pack it all away nicely at the end leaving a finished named ReaperTheme file.

Here’s the new stuff…

• Find the rtconfig.txt file in the Default_4.0_unpacked folder.
• Open this file in a text editor (Notepad++ is good for highlighting and line numbering).
• Scroll down the rtconfig.txt file to find the line that looks like ;-----WALTER------ .
• Scroll past the two lines of WALTER you left behind earlier and prepare to type.
• Open the SDK WALTER reference webpage listed in the Themer’s Guide page 4.
• Use the menu to jump to UI Elements and consider the TCP elements listed.
• For now, use the Themer’s Guide example of the solo button
• Type the following line into your rtconfig file just below your existing two lines of WALTER:

set tcp.solo [10 3 20 20 0 0 0 0]

• Save the rtconfig file and switch to Reaper.
• Open a new theme (Options > Themes menu)
• Switch back to Default_4.0_unpacked theme.

Right now you should be looking at a TCP with a solo button in the top left of each track. See the Themer’s Guide page 9’s “Show A Single Button” image. That’s what you should see. If you don’t, assuming you’ve got to the Default_4.0_unpacked theme, then you’ve probably mistyped the line you’ve just added to the rtconfig file.

The fun really starts now. Add as many elements as you like to your rtconfig file and check the results in Reaper. You will come across placement issues but focus on the first four digits in the 8 digit expressions bracket only. The first two digits move the element/button and the second two size the element. For that reason it’s good to focus on the elements listed as buttons in the WALTER reference webpage. The description of the basic numbers system is covered very well in the Themer’s guide and also on the SDK WALTER reference webpage. Check these out to figure out position and sizing; if you’ve got this far that’s an easy step to take. It’s easier to focus on moving elements around without having to think of more complicated expression techniques. The Themer’s guide is pretty clear about this but it is not particularly clear (in this first part) about the alternative expression methods. Colouring, for example, changes the numbering convention. Make it easier for yourself and stick to uncoloured buttons for now.
I also recommend adding one line of code at a time to your rtconfig file. Test that by refreshing your Reaper theme (remember, switch to a new theme and switch back, or double-click a theme in the ColorThemes folder). When you are sure about that element move on and add another element. Don’t expect a great theme first time, just get used to placing UI elements in your code and Reaper theme.
If you run into positional problems, maybe not seeing any change to your TCP then two methods can really help you problem solve. The first is to comment out all the elements of your rtconfig file that you know are definitely working. A semi-colon “;” placed at the beginning of a line of text will comment it out (see page 8 WALTER Themer’s guide). This leaves only the bug visible but saves time by hiding all the good stuff. You can work out what to do from there and uncomment your code when you’ve fixed things. The second method is to make the element larger, so large it becomes obvious above the other elements. From there you can work out a better position. Obviously, you need to resize your element once the issue is resolved.

At this stage you are ready to really get stuck into WALTER and work with the Themer’s Guide part two. But don’t forget to save your work...

6.2/ Save your newly altered theme
This process is similar to section 4 except you will already have a zip folder, e.g., Dyl.ReaperTheme.Zip. (see section 6.1 bullet points).

• Cut and paste the Default_4.0_unpacked folder into your theme zipped folder
• Cut and paste the Default_4.0_unpacked.ReaperTheme file into the zipped folder

I ran into problems with existing files in the zip folder. My quick and dirty method to overcome this was to first empty the zip folder. Then I cut and pasted the unpacked file and folder from the ColorThemes folder into my theme’s zip folder.

• Rename the zipped folder removing the “.” from the name. e.g, Dyl.ReaperTheme.Zip
becomes Dyl.ReaperThemeZip.

Like before, the zipped folder symbol should change to a ReaperTheme file symbol. Now you should be able to open your theme in Reaper. Make sure you clean out any unpacked stuff left behind in the ColorThemes folder. If you’ve been following closely that won’t be an issue.
Don’t worry that the unpacked files are Default 4.0 types, when you pack/zip up your theme it all works out.
To double check you’ve got it right open Reaper’s Options > Themes menu and check there are no unpacked themes listed and your theme is listed too. Yes? Success.

7/ Opening your theme for editing
No problem:
• Open Reaper Options menu > show REAPER resource path in explorer/finder.
• Open the ColorThemes folder
• Rename YourTheme.ReaperThemeZip to YourTheme.ReaperTheme.Zip.
Note the “.” between “Theme” and “Zip”.
• Unzip this folder into the ColorThemes folder.
• Get ready for more advanced WALTERing in part 2 of the WALTER Themer’s Guide.

I hope this guide will help some users unravel the challenges of starting WALTER. I am having fun now I’ve cracked these tasks. Hopefully other newbies will too.

[MaXyM]

There is no need to switch between themes any more in order to reload a theme you are working on. It can be done by one of following ways:
1. select your theme again from Options/Themes menu
2. double click in ReaperTheme or ReaperThemeZip (considering those file types are associated with Reaper)
3. Press "Reload images" button in Theme tweaker window - it reloads whole theme, not only images
4. Use Lokasenna script - it executes option #1, but being a script it can be executed by a hot-key which gives the fastest (most time) way to do that.


Regarding your findings, I have to admit that materials intended to be a guide for theming beginners, are too scattered, inconsistent, incomplete and outdated. I'm a programmer, so it was easier for me to get grasp on it (especially on file structures, WALTER language), but of course I was struggling to find particular information when needed. Especially when some inconsistencies inside theming engine played a role.

On the other side, I would avoid creating an guide in step-by-step format (like suggested by your proposal). Such way leads often to copy-paste workflow without understanding what happens under the hood.
For example, renaming ReaperThemeZip to ReaperTheme.Zip*) in order to unzip files is not the only way. Unzipping the package in order to get access to files inside is not always needed too. It depends on tools you have.
That's why I would suggest to describe wisely what ReaperThemeZip is, including file structure inside, making a theme maker to understand that, allowing him to chose tools he feels most comfy/familiar with.

PS1 why to start with default theme v4 instead of v5 which is likely more up-to-date?

PS2 ReaperTheme.Zip is not a "zipped folder". I think some people might understand it this way, but this it is not, so I would stick to the facts.

[Dyl]

Thanks for going through this.
Point 1/ That is great, just tested it.
Point 2/ Is half way included in my text. But after testing, yes they both work.Good stuff.
These 2 points make things a little easier. I will try and edit them into the guide.
Point 3/ I don't know to avoid creating a new step by step list to access the SWS stash, locate the script you mention and then add it to Reaper. I certainly couldn't find that now. I'd have to document my steps in order to get there.
Can you say what it's called and which repository it is in. I'm not keen on downloading the whole stash.

Weirdly, when I clicked the "quote" button on your post a whole new paragraph appeared that isn't displaying on the main forum post. Not sure whether you intended I see that.
Just to reiterate, I've no intention of doing any more than I've done here. My purpose in doing this was to get past the hurdles that blocked me from starting to learn WALTER. I think there are plenty of challenges ahead with WALTER.
EDIT point:
Posted this reply and your full post came up. Odd behaviour!
The quote addition had your Lokasana point 4 as point 3 and the theme tweaker point didn't appear at all.
Sorry this is a bit messy as a reply.
Ok, your points are valid and maybe they are the very thing you are talking about. This process was a guide not a definitve text. You are talking about alterative ways to do things, which is good and helps me learn more. This is perfect and stretches my knowledge base out. I wouldn't want to create a text that covers every possibility or else I am indeed doing the thing you said I shouldn't.
Why default 4 and not 5?
Well, apart from the Themer's guide telling me to do so?
But seriously, if you look at the rtconfig.txt file for 5, it is structured very differently from 4, for which the themer's guide was created. In 5 there is the additional Flow stuff. Too much for me to tackle, I'm afraid.

[White Tie]

Originally Posted by Dyl

Why default 4 and not 5?
Well, apart from the Themer's guide telling me to do so?

Well, actually no it doesn't, but looking at it again I can see why you might think it did because I veer off on a silly tangent. Oops, sorry.

From the guide, p6:

I strongly recommend that you do not start learning WALTER by trying to edit an existing theme with complex WALTER - and the default theme has some very complex WALTER.

...

Find the ColorThemes folder in your REAPER path, as described above, and unpack the Default_4.0.ReaperThemeZip. You will have a new theme available called “Default_4.0_unpacked” and you can edit its WALTER by finding its rtconfig.txt file within the “Default_4.0_unpacked” folder.

...

Make a new theme, or open an existing theme that has no WALTER. The first thing we need to do is tell WALTER to override the standard layout. In this tutorial we will be working on the TCP, so we need the command to clear the TCP elements.

Me going off on a tangent about how to unpack the default theme in the middle of that was foolish, I apologise for it leading you astray.

My advice to not edit the default theme is doubly so for the V5 due to me making the default 5 very easy for a beginner to mod, at the cost of making it an absolute nightmare for a beginner to deep edit.

If you're looking to learn, start with a blank theme. And absolutely definitely not a default theme!

A blank theme is an empty text file. You can then edit that using the theme tweaker to give it values. You can then assign it a resource folder (an empty folder). In that you can put an rtconfig.txt, also a blank file. You now have a fully functional (but crap) theme ready to have stuff optionally added to it.

[Dyl]

Originally Posted by White Tie

Well, actually no it doesn't, but looking at it again I can see why you might think it did because I veer off on a silly tangent. Oops, sorry.

From the guide, p6:


Me going off on a tangent about how to unpack the default theme in the middle of that was foolish, I apologise for it leading you astray.

My advice to not edit the default theme is doubly so for the V5 due to me making the default 5 very easy for a beginner to mod, at the cost of making it an absolute nightmare for a beginner to deep edit.

If you're looking to learn, start with a blank theme. And absolutely definitely not a default theme!

A blank theme is an empty text file. You can then edit that using the theme tweaker to give it values. You can then assign it a resource folder (an empty folder). In that you can put an rtconfig.txt, also a blank file. You now have a fully functional (but crap) theme ready to have stuff optionally added to it.

Thanks for the clarification, totally see where I went wrong with that default 4 thing.

Now I'm struggling with the last paragraph.
I've created a theme from here: Actions > Theme Development: Show theme tweak/configuration window? Called it chuff.
I've also created a folder in the ColorThemes folder where my new theme resides. It's got the same name as my theme. I've dropped a blank text file in the folder called rtconfig.txt but the process doesn't seem right.
I've missed something here surely, do I need to do something specific to make the folder an assigned folder?
The chuff theme has an icon like all the other themes I have except they end in Zip. My chuff.ReaperTheme does not have Zip on the end.
I've tried renaming it to end in Zip and .Zip but things start going wrong there. I even created a chuff.txt file but the above theme tweaking actions window cannot see it in the list of themes if I try loading it???

What am I missing?