ReaScript: Template Script, Header and Loops & ReaScript Updater Idea (step 1)

[X-Raym]

Hi !

I want to share with you a script template file I coded for scripting in REAPER. I build this for two main reasons:

• Helping beginners with a script model they can duplicate and easily use. It has a lot of comments that maybe for newbies, and for people who will look at your code.
• Being able to create scripts quickly. Indeed, the script contains the most common loops (selected items, takes, tracks...), I need, already in place with indispensable functions (updateArrange, undo blocks...) and integration with my debug console script, very handy for creating scripts.

Propose a standardized header, with all the scripts infos, to allow possible future great things, such as an automatic script updater extension (I have thinking a lot about how it would be possible and I will share you the results of my research on that very soon - note: there is hope, and have some concrete ideas about it).

My template code part (below the header) is defined by:

• Tabulation indentation (i find them more convenient to use)
• variables_with_underscores, to be quickly identify variables and functions (reaper functions are CamelCasedBased).

You may not agree with this conventions, that's ok, we all have our code habits, I will not tell you how to code. But if all of us could use a common header, it could open doors of a eventual script updated extension.

The header is based on the normalized WordPress (most used CMS in the world) plugin header, and contains international ISO 8601 standard date format, which is very easily scannable by regex, for any eventual ReaScript updater extensions. This is basically how WordPress works for telling you that a installed plugin need an updated: just scanning the header regulary and compare it to a database. This is a trusting working model of header. :P

Because script are individuals files, they must contain all infos that will be potentially needed for scanning, so I added even more infos that there is in a WordPress plugin header. This is how it look like with my personal infos for example.

/**
 * ReaScript Name: Template (match file name without extension and author)
 * Description: A template script for REAPER ReaScript.
 * Instructions: Here how to use it.
 * Screenshot: Here is a link.
 * Notes: Here some infos.
 * Category: Here some infos.
 * Author: X-Raym
 * Author URl: http://extremraym.com
 * Repository: GitHub > X-Raym > EEL Scripts for Cockos REAPER
 * Repository URl: https://github.com/X-Raym/REAPER-EEL-Scripts
 * File URl: https://github.com/X-Raym/REAPER-EEL-Scripts/scriptName.eel
 * Licence: GPL v3
 * Forum Thread: 
 * Forum Thread URl: http://forum.cockos.com/***.html
 * Version: 1.0
 * REAPER: 4.76
 * Extensions: SWS/S&M 2.6.0
 */

EDIT 2015-12-08 : minimum fileds are ReaScript Name, Author, and Version
This will be used by the script downloader by cfillion
Q about Cockos politics to third-party libraries - Cockos Confederated Forums

I think it is pretty complete, most of software extensions manager don't have all that fields.
We could easily imagine this infos parsed by a local script manager. There is all what is needed for auto-update the script (name, version checker, url...).
Script format could be determined by file extension.

Below that, I also added the changelog part. This way, we could imagine that an updater script extension could display changelog as well. I used standard changelog symbols (+, -, #).

/**
 * Changelog:
 * v1.2 (2015-02-13)
    + Items, Takes, Tracks, Regions and FX loops
    # Underscore variables
 * v1.1 (2015-02-13)
    + Basic scripts actions template
 * v1.0 (2015-01-29)
    + Initial Release
    + New functions
    - Deleted functions
    # Updated functions
 */

My template is EEL only for now, it will be converted to LUA for v5, just as my console plugin.

As I already said, this could be the first and indispensable steps for building a powerful ReaScript Updater (more on this later). Indeed, from all resources that we can share for REAPER, scripts are what are the most commonly updated (except some themes). All REAPER users could benefit of it, and it could democratize scripts, and scripting.

I hope you will like the concept, and that you will be interested by following my call. Building a more interactive, modern and easy way to download scripts within REAPER start from the way we all wrote scripts. A common header structure may be all we need

In a future post, I will talk about the second step :P
Meanwhile, you may just find useful to have a header full of pre-filled metadatas, and basics functions already in place! This script updated thing is just a (non-negligible) bonus :P

I know it is ambitious, but with a common effort, I have the feeling that it could be possible, in a way or another.

Ideas are meant to be shared.
And so are ReaScripts !

Download links :

• See my signature!
  The script is in folder Templates.

If you like it, it will probably be updated with more "basic loops" or "often used" functions.

Cheers !

[heda]

I was already using some sort of your template
I like the idea of the basic loops template functions too.

[X-Raym]

@heda
Yeah, I noticed that
And you can see know that it is not just convenient, it can also become useful :P

We think about all sort of other basic loops: selected point envelope, trackFX etc...
I haven't prepare it yet, I will add things if requested :P

[X-Raym]

Any volunteer to convert it to convert it in Lua ? I don't know the basic loops in this language.
Could help every Lua learners :P

EDIT: @heda, I added your trackFX loop !

[X-Raym]

 * Changelog:
 * v1.3 (2015-02-19)
    + Instructions header field
    + Get and Set parameters for items
    + Get and Set parameters for takes

If you find this get set useful, I will prepare them for tracks.

Instructions in header came from Heda's idea; nice one :P

[X-Raym]

Thanks to heda and benf, I manage to transpose all functions to a LUA version of the template, for users who use REAPER v5 pre-releases.
It also uses the console debug functions which has been transposed to LUA too.
The download links are updated in the first post.

Cheers

[benf]

In lua, you can use :

reaper.ShowConsoleMsg(tostring(variable))

instead of :

str = string.format("%d", variable)
reaper.ShowConsoleMsg(str)

[airon]

Great stuff. This will certainly help with any script I'll be writing.

Thanks for the effort!

[X-Raym]

@benf
You are right, It may be more efficient, but I keep it that ways for consistency with the EEL version, and I used %f and %X at some other part of the script.
But I may updated it if there is performance issue.

@airon
Thanks to you
You have some pretty advanced scripts already, it will be an honored if you used my template as base for some of them!

--
It is my second attempt in LUA, it could probably be optimized, but I try to make the thing right, using some LUA coding conventions I read in the official doc.

[X-Raym]

I added some useful functions and code references for the LUA version.

 * Changelog:
 * v1.4.1 (2015-03-03)
     # EnumProjectMarkers3 for regions loop
 * v1.4 (2015-03-02)
     + Infos for track, take and items values
     + Restore view, loop, edit cursor and UI

Note: These restore functions need SWS.

[musicbynumbers]

Thanks!

[EpicSounds]

Page Not found on all 4 links in OP.

[mim]

Nice Idea!
Useful stuff for newbz!

Originally Posted by EpicSounds

Page Not found on all 4 links in OP.

One can find it,in the archive here :
http://extremraym.com/en/my-reaper-scripts/

[X-Raym]

@EpicSounds
Hi!

The link is in my signature!
I decided to change the way I share scripts. Individual links for every script is hard to manage, especially if the host/folder change, so now, they are all at the same place, and the link is no dependent of the post: it is simply my script link in my signature!

@mim
Thanks!
I'm about to make a video tutorial on how to use it!

[heda]

in template.lua
use this for the RestoreCursorPos()
It doesn't move the view.

-- RESTORE INITIAL CURSOR POS
function RestoreCursorPos()
	reaper.SetEditCurPos(init_cursor_pos, false, false)
end

[jrp]

Hey X-Raym,

Big thank you for all the effort!
Scripting is such a nice hobby, isn´t it? The article on your HP covering the new possibilities with v5 is also very nice!
So now let´s immagine something - and code it!

[X-Raym]

@heda
Oh yes, it is not supposed to.
It just does cursor

Restore view is another module.
We have to use SWS REAPER action save/restore view for that now, but I plan to integrate a Lua version with future SWS API functions. (SaveView and RestoreView in the file doesn't work yet).

[X-Raym]

@jrp
Many, thanks More articles will come soon ! Can't wait for v5 to come out.
Scripting is funny, totally ! It is like doing puzzle games, that are useful to solve :P

Do you have any script ideas you want to share ?

[heda]

@X-Raym, Sorry I didn't explain it well. I changed the code of that function. I mean, if you replace the function with the one I posted, it will work better by not moving the view.

[X-Raym]

@heda
How could I missed this function.
I know I was looking for "Cursor" not for "Cur". !!

Thanks, it will be easier that way

[X-Raym]

Thanks to the last SWS pre release 2.7.1 (and Breeder's work), I am happy to show my last Lua template version

 * Changelog:
 * v1.7 (2015-05-18)
     + Save/Restore view without calling the SWS "slot" functions.
 * v1.6 (2015-04-15)
     + Save/Restore functions without calling the SWS "slot" functions.
     # thanks to heda for the edit cursor restore

There is now functions to call/recall certain initial states (item selection, track selection, view, edit cursor, loop and time selection), without using the SWS actions, and so, without using your slots. It is now all integrated in the scripts...
... and in all my other scripts

Cheers !

[X-Raym]

One of the most time consuming part of scripting is the sharing part of the process (at least for me).

To manage my script pack on my website (with content displayed in a sortable responsibe table with lighbox for screenshot, and updates are displayed with a RSS file embed right in the page and triggered by any update in this table), I have to maintain a spreadsheet online, with all infos about scripts update.

Of course all infos came from the script header, but it is a bit boring to copy paste all this fields...

... So here it is, a script header parser !



It is still a long run before a script updater but it is a first step. A small one, but a step anyway :P

[X-Raym]

Templates have moved from my repo and can now be found on the ReaTeam-Templates repository.

I will soon create a template for each common cases (regions, markers, etc...) rather than a all purpose template, because I found it pretty confusing to have to delete all unnecessary code each times. Especially for beginners.

Meanwhile...

• Basic template : a all purpose template

Hope it can be useful !

[airon]

Thanks X-Raym. The template was a big help in getting me up and running.

[heda]

the function UnselectAllTracks()

Maybe better just to use the action like this
reaper.Main_OnCommand("40297",0)

not really important

[X-Raym]

@heda
I think it was to avoid creating unwanted undo points. I did that long time ago and I didn't need to use it very often.

But sure, it can work with reaper.Main_OnCommand("40297",0) !