ReaScript: Wiki API Pages

[MikeLacey]

The ReaScript API Wiki pages are now in some sort of shape, each API function has a page with a standard layout which should hopefully make it easy to update as we find out more about the API in general. There's also an Examples section on the ReaScript page.

I'm now working through each function, getting it to work (Hmm :)) and documenting in a little more detail with an example.

I've put together some scripts which I use to regenerate the API list, so (hopefully) I won't miss shiny new functions arriving or old, slightly dusty and unloved functions being retired.

Please, have a look at some of the function pages, find an error maybe :o and put a quick description in a function or two if you have the time. If you happen to have a script which demonstrates the use of an API function then it would be excellent if you could slide that into the blank bit of the page just waiting for it.

On each ReaScript page there's space for an example in each language supported by that function - take a minute, if you can, and contribute an example or two. Don't hesitate to create the section for that language if it's been missed in that function - and don't worry about making it look good.

http://www.cockos.com/wiki/index.php/ReaScript_API

Mike

[Shan]

WOW! What a great contribution to the REAPER developer community Mike! Well done!

We'll definitely need some Python examples etc. Thanks for starting this!

Shane

[Jeffos]

did I already said "hats off" !? I think I did!
This thread looks like a good sticky candidate...

[sfzgeek]

I've put together some scripts which I use to regenerate the API list
No... surely not?! Scripts? For repetitive tasks?! ;)

In all serious, the ReaScript section of the wiki is off to a great start thanks to your hard work. I've bookmarked it and have started using it as an alternative reference to the API listing that Reaper generates.

Thanks for putting this together Mike.

Regards,
Dale

[MikeLacey]

"Scripts? For repetitive tasks?"

Yeah - I heard about that being a good idea; now if I could only find someone who knew *something* about Perl... :)


Oh - and it's my pleasure. So thank me by filling out an API Wiki page a bit :P !! (you have to keep on top of these Ozzies you know...)

[schwa]

Fabulous job! Thanks!

[yhertogh]

Mike, amazing work!

Would it be a lot of work to perhaps also add a header for C++ examples where other people could contribute to ?

Yves

[MikeLacey]

I've been thinking along those lines but I don't know what wiki pages there are for the wider api. I'm on my phone atm and can't check.

At first glance there's a lot to be said for including C++ examples on the pages already done and adding more pages for those functions not available to ReaScript.

Mike

[liteon]

nice work mr. mike,

i will see if i have some time to write a couple of examples in there.

[MikeLacey]

Ok, have started to think about and define an overlapping structure, so that the REAPER and ReaScript APIs can share documentation as much as is possible.

http://www.cockos.com/wiki/index.php/REAPER_API

and http://www.cockos.com/wiki/index.php/REAPER_API_Functions

I'll make some space on the existing ReaScript API Wiki pages for a C++ example and create the stubs for REAPER API Wiki pages tomorrow or early next week.

[semiquaver]

thanks! so helpful for an inexperienced scripter such as me!

[sfzgeek]

For my own edification I wrote a little GetTrackState example script. Have inserted it as an example on the wiki: http://www.cockos.com/wiki/index.php/RPR_GetTrackState

[MikeLacey]

Neat...

[MikeLacey]

Liteon's quietly added Python & Perl examples to about a dozen ReaScript API Wiki pages...

:)

[liteon]

Liteon's quietly added Python & Perl examples to about a dozen ReaScript API Wiki pages...

:)

heh, mostly copy pasting-from perl -> python. :)

some notes:
- AddTakeToMediaItem seems to crash reaper.
- spam bots are spamming a lot with antibiotics in the wiki!

[MikeLacey]

AddTakeToMediaItem seems to crash reaper
Does seem to yes...

spam bots
Hmmm

[MikeLacey]

liteon...

http://forum.cockos.com/project.php?issueid=1735

[liteon]

liteon...

http://forum.cockos.com/project.php?issueid=1735

cool...will be adding more examples in the wiki when time permits to do so.

[liteon]

mike,

looking at the wiki entries, i wonder if it would have been better to just write a "pseudo-code" piece for each api function, instead of separate, yet quite similar snippets...i.e. a test of some 'raw pseudo-code porting skills' for users. :)

[MikeLacey]

Hey liteon,

I *do* know what you mean...

However - my thought is that the way to attract people who are finding macros a bit limiting but who don't yet have any experience of scripting is to provide as precise instructions as possible with lots of examples. You'll see that some of the Perl examples are the same, quite lengthy, Perl script for several functions. It's used as an example for each of the API calls it uses.

You, me, sfzgeek, EvilDragon etc. are not the people I want to be hooked into ReaScript by the Wiki - these people are already hooked (some of them on Python, but you can't have everything I guess)

I think that the people who're going to really attracted to this aren't REAPER users at the moment - and they won't care that all of the documentation is user contributed - they're just going to want to know how to use it all. If it doesn't work, or doesn't work as documented, they'll (quite rightly) think "flaky" and move on.

I do have a (cunning) plan you see. :) Of course, it might be wrong...

[MikeLacey]

Oh, have another go at AddTakeToMediaItem() -- it's fixed, it says here *grin*

[liteon]

wiki has needs:

Fatal error: Allowed memory size of 20971520 bytes exhausted
(tried to allocate 83 bytes) in /var/www/cockos/wiki/includes/SpecialPage.php
on line 906.

[sfzgeek]

I do have a (cunning) plan you see. :)
I love watching cunning plans play out...

[EvilDragon]

Mike, please activate

$wgUseTeX = true;

in LocalSettings.php, so that <math> tags can work! :)

[MikeLacey]

Hi Dragon,

I don't have that kind of access, I've asked the man who does though.

Mike

[EvilDragon]

Oh, ok. Just saw on GetSetItemState page that you have some <math> tags which aren't rendered well.

How do you like my edits on that page? :)


BTW I'm having no luck with "Set" portion of GetSetItemState, I tried converting your Perl example of changing MIDI item length... no dice.

[MikeLacey]

Dragon,

That is an awesome update to Midi Item State Chunk in GetSetItemState()

Mike

[MikeLacey]

I didn't look at the page until after my post :) It's really good.

[MikeLacey]

BTW I'm having no luck with "Set" portion of GetSetItemState, I tried converting your Perl example of changing MIDI item length... no dice.

Post your code... It's bound to be something simple, I've not had any trouble with it at all.

[EvilDragon]

Thanks :D

I wanted to test tokens 1, 3, 7, and 9, but the above mentioned problem imposed on me :(

I tried something like this:
import re

item = RPR_GetSelectedMediaItem(0,0)
chunk = ""
maxlen = 16384
result = "...fail :("

(bool, item, chunk, maxlen) = RPR_GetSetItemState(item, chunk, maxlen)

p = re.search('LENGTH\s(.*)', chunk)
cfg = p.group(1)#.split()

RPR_ShowConsoleMsg("The value of LENGTH:\n%s\n\n" % cfg)

p = re.sub('LENGTH\s5.00000000000000', 'LENGTH\s(.*)', chunk)

(bool, item, chunk, maxlen) = RPR_GetSetItemState(item, p, maxlen)

RPR_ShowConsoleMsg("The value of LENGTH:\n%s\n\n" % p)

[MikeLacey]

Thx. I'm being reminded it's midnight... Will try out first thing and post back.

Mike

[EvilDragon]

I must've gotten logic wrong... RegExp in Python isn't as easy as in Perl...

That, and writing back into the chunk is getting me confused as hell.

[MikeLacey]

(See? Perl good, Python bad...)

I think you're right. Something's not quite right about the chunk as given to GetSetItemState() for the update and it's getting rejected.

If you ShowConsoleMsg() the chunk before you give it to GetSetItemState() for the update - does it look reasonble?

[Jeffos]

Great update ED!! (I wonder how you get this CFGEDIT idea ;))
a short post about "writing" chunks back: as I said in that other thread, be very *very* carefull with that. Perhaps you just have a coding issue in your script, but I know this stuff can be dangerous (user project corruption, crash, ..), tricky (depencies, updates not taken into account, ..). Things are not clear about that.

Also, I like your straight to the point parsing (i.e. search for "LENGTH" !) but for the record, you can have many "LENGTH" (or "VOL" or "PAN", ..), also, cockos may change/add things at any time: so when we parse, we usually at least check the depth in the chunk (i.e. each "<" => depth++, each ">" => depth--) and the parent (i.e. "<PARENT"). You can also check the number of tokens, etc.. all of that ensures something more reliable and better ascendant compatibility. Also, about "CFGEDIT", it can be present in several takes in the same item, so re.search() probably returns the 1st one it founds, not necessary the active one... well, you see what I mean..


[edit] about you're issue, try to call UpdateItemInProject(MediaItem* item) after the chunk update, if it stills KO, try to call UpdateTimeline(), if it stills KO.. hummm.. this is a secret ;)

[EvilDragon]

Yeah, I see there's a helluva lot of job with these chunks...

Mike, yeah, I tried outputting console message to see how the chunk looks before writing back... it does look reasonable (I wanted to change length of the item, it worked... but when I wanted to change the tokens that aren't yet described in CFGEDIT, that didn't work, as I didn't see anything changed).

Jeffos, actually I haven't run into multiple LENTGH properties in chunks... it's only at the beginning of the item section of the chunk... And it shows in SOURCE section only when we modify the source length in item properties... this is easily avoided with RegExp, from my understanding, by just adding <SOURCE to the RegExp, or something.

[EvilDragon]

This line confuses me the most:

(bool, item, chunk, maxlen) = RPR_GetSetItemState(item, chunk, maxlen)

What is going where, here? Are we writing from the left side into the right, or...?

The weird thing is: this is working for audio files - I tried changing loop source and take name with this, and it works... like this, for example:

import re

item = RPR_GetSelectedMediaItem(0,0)
chunk = ""
maxlen = -1

(bool, item, chunk, maxlen) = RPR_GetSetItemState(item, chunk, maxlen)

p = re.search('NAME\s+(.*)', chunk)
cfg = p.group()

RPR_ShowConsoleMsg("Item chunk:\n%s\n\n" % cfg)

chunk = chunk.replace(cfg, 'NAME "1"')

RPR_GetSetItemState(item, chunk, maxlen)

RPR_UpdateItemInProject(item)
RPR_UpdateTimeline()

RPR_ShowConsoleMsg("Item chunk update:\n%s\n\n" % chunk1)

It just doesn't work or refresh well in MIDI items if I replace the CFGEDIT tokens (or anything else in the SOURCE MIDI section)... Trying this code:

import re

item = RPR_GetSelectedMediaItem(0,0)
chunk = ""
resch = ""
maxlen = -1

(bool, item, chunk, maxlen) = RPR_GetSetItemState(item, chunk, maxlen)

p = re.search('CFGEDIT\s+(..........)', chunk)
cfg = p.group()

RPR_ShowConsoleMsg("Item chunk:\n%s\n\n" % cfg)

chunk = chunk.replace(cfg, 'CFGEDIT 1 1 0 0 1')

RPR_GetSetItemState(item, chunk, maxlen)

RPR_UpdateItemInProject(item)
RPR_UpdateTimeline()

(bool, item, resch, maxlen) = RPR_GetSetItemState(item, resch, maxlen)

RPR_ShowConsoleMsg("Item chunk update:\n%s\n\n" % resch)

you can see that I tried to change the 4th and 5th token, the string gets replaced, but after taking chunk info the second time in new variable (resch), nothing changed, even after updates... Could it be that CFGEDIT tokens are flags only and are not possible to change via GetSetItemState? This seems like the most likely thing. I tried changing VELLANE, IGNTEMPO, EVTFILTER... they all WORK!


I hope the devs see this, because I'm mildly getting depressed :(

[Jeffos]

not sure we're in the good thread for that discussion, sorry Mike..

"depressed" !?? perharps a bit strong? Look at all that new things you can at least -read- now... isn't it great? isn't reaScript another silent revolution !???
Your issue: I've never patched the ME config yet, i'll (perharps) try it later.. but i think I know what happens: as I already said it, it can be tricky, risky, I repeat be carefull with chunk patching ! I REALLY INSIST. e.g. in this patching failure case: is the ME opened when your script fails? if you run it with closed ME and then open it, is it taken into account? Well, some examples, there're many different type of issues I already faced with chunk patching..
about the parsing approach: I was talking more generally and not only about the "LENGTH" case.. and even with that "LENGTH": sure, it's ok today but what tells you there'll not be another "LENGTH" in REAPER v14.7 ? well, you see..

[EvilDragon]

Yup, I understand what you say about parsing :) And yes, it's great to understand what chunks are about, now.


Also, yes, when I ran the script ME was closed. When I opened it and pulled out the chunk again, the values turned back to default.

I even tried manually changing values in RPP file (this is for CFGEDIT 1st, 3rd, 7th, 9th token) - they all got restored when I opened the MIDI editor, with no seeming change in anything.

However, what bothers me the most, with my way of setting the CFGEDIT chunk, it won't refresh, for example, if I change the view mode! I really don't know what I'm doing wrong, script-wise. When I change the tokens manually in RPP, stuff is changed. When I set the CFGEDIT chunk, they're not. I'm appalled.

[MikeLacey]

Hey Dragon,

What is a Slip Offset? I thought SOFFS was Start Offset, shows how much *I* know...

[MikeLacey]

However, what bothers me the most, with my way of setting the CFGEDIT chunk, it won't refresh, for example, if I change the view mode! I really don't know what I'm doing wrong, script-wise. When I change the tokens manually in RPP, stuff is changed. When I set the CFGEDIT chunk, they're not.

I've had similar experiences to that, sometimes down to me formating data slightly differently when writing a chunk and REAPER just deciding to have nothing to do witgh *that*... 1.23456 instead of 1.234567890 for instance. The length of float numbers seems to matter when you're writing stuff with GetSetThingyState(). Other times it's been a "temporary feature" :) which I've pointed out to Mr Schwa. Have a real close look at your formatting. I don't know how easy it is to use the Windows Clipboard in Python but I use it a lot to examine chunks in notepad etc.

[EvilDragon]

Hey Dragon,

What is a Slip Offset? I thought SOFFS was Start Offset, shows how much *I* know...

It's when you're holding Alt and dragging the item, it's not the item which moves, but the source. Try it ;)

Oh yes, I'm writing floats with correct number of decimals, to the tee.

[Jeffos]

Last OT post here. ED, I did the test.. confirmed: I'm unable to validate the updated CFGEDIT as well (although I also tried to pass by the window but all the tricks I usually do to force the refresh also fail!). Tho, I know it's OK for some other take properties..

Patching chunks is touchy stuff I told you!
(but it's cool here: no crash)

[MikeLacey]

Thx Dragon :)

[Malevol3nt]

Edit: Wrong thread :)

[Andrej88]

Hi,

It seems Reaper is generating a faulty HTML <br> tag when using the ReaScript: open ReaScript help(html) action, as seen here:

http://i48.tinypic.com/2jahz5x.jpg

I've tried using the action in Reaper 3.161, 3.2 and 3.21pre3, with the same effect.

I was using a Python script to parse the html file, and ran into the error. Just thought I'd let you know about it.

[schwa]

Fixing! Thanks.

[EvilDragon]

Why doesn't my Color Toolbar page show images, but only links to them? When I first posted that wiki page, the images all showed up...

I hope it's not only my PC here.


P.S.: it's not, I asked a couple of my friends to open the page, and they all got the same thing.


:(

[MikeLacey]

Hi Dragon,

I'm not sure why it worked for you before to be honest but I fixed it, hope you don't mind.

[EvilDragon]

I don't mind at all, thanks Mike!

Did you have to reupload all the pics? It might've been a better idea to use thumbnails for the big ones ^^'

[Andrej88]

Also noticed this small typo in 3.21pre5, API HTML:


# function returning information in the first parameter:<br>
str = RPR_GetProjectPath(str, 256)[1]<br>


The first parameter is [0], not [1].

[MikeLacey]

I don't mind at all, thanks Mike!

Did you have to reupload all the pics? It might've been a better idea to use thumbnails for the big ones ^^'

Had the pictures been uploaded before?

I would have used thumbnails but that's broken in the wiki at the moment. I've got a list of pages to revisit when it's fixed & this page is on it.

[EvilDragon]

IIRC; my first version of that wiki page had thumbnails linking to the big pictures...

[MikeLacey]

? which version? http://www.cockos.com/wiki/index.php?title=EvilDragon's_Color_Toolbar_v2.0&action=history

[EvilDragon]

O.o'

I could've sworn I had thumbnails there!

My memory is obviously getting flaky. I need more RAM :P

[MikeLacey]

You're getting old Dragon :) Not as old as me mind...