Lua Scripting with REAPER 5 - Part. 3: Get/Set First Selected Items Properties

In this tutorial, you will learn how to get and set properties of the first selected items.

Source Article :
http://extremraym.com/reascript-video-getset/

Any feedback would be really appreciated ! :)

Hello everyone, this is X-Raym,
for the third part of the tutorial

about Lua coding for
REAPER ReaScript.

Today, we will work on Items.

We will get infos of first selected items,

and then, we will learn
how to modify them.

We will start by the script
we wrote last time.

I will set Notepad++ this way
so that it stay in foreground.

Imagine that I want to get
the infos of that items.

First, I have to return this item
in a variable.

I check the API Doc,
and I write "Selected Item"

We see that there are some
functions about Item Selection

The function that we want
is this one.

"GetSelectedMedialtem"

If we add a project number ID
and an integer

we get an Item.

Project ID is 0 for current project.

And the integer is the place
of the item in selection.

If it is the first item,
the integer will be 0.

Demo. I will create a function "Main"

which will contain the core
of my script.

Hop, I put the function end

at the end of the script,
I call "Main".

I move the call to that function below
so that it is more clean

just before the call of Main.

Remember, ShowConsoleMsg("")
is used to clean the console.

I take this.
This function return an item.

So I will stock this item in a variable.

Item = reaper. GetSelectedMedialtem()

Here I delete value type reference,
we don't need it.

As first parameter,
0 for current project,

and 0 as ineteger,
for First Selected Item.

If I run the scrip...

The console open because of
ShowConsoleMsg(""), but nothing happen.

If I display item in the console...

Hop, save, run..

We see that the item
is a special type of data

called userdata.

Userdata in Lua represent an array value...

but all you have to remember is that

this userdata is specific to this item
the project with a unique ID.

We will try to get infos on this item.

I get back in function list,
And I enter Item Infos.

I see that there is a function
GetMedialtemlnfo_Value

and there is a variant for Take properties.

We will focus on item.
So, I click on GetMedialtemlnfo_Value

and I see this function.

If I want to get the state of
Mute of the item.

I add a breakline,
it is more readable.

I add item_mute =

and I copy this function.

The item that we will set as parameter
is the item stored in item variable.

I activate the automatic break lines
of Notepad++ so it is more readable...

As second parameter, it asks for the
name of the type of value we want

It has to be a string
so I write "".

The parameter we want in our case
is called "B_Mute".

I copy "B_Mute"
and I paste it here.

I delete that...
I add a break line here...

and I ask to the console
to display the value of item_mute.

I get back here.

I run the script.

And we see that the value is 0.

If I mute the item
and I run the script again...

we see that when the item is muted,
the value displayed is one.

In other words,
GetMedialtemlnfo_Value("B_Mute")

return 1, when the item is muted.

Another parameter very interesting
is the position.

We will duplicate this line.

We name this variable item_pos.

We add the parameter "D_POS"

and we will display the value
of this variable.

So that we can see better,
I will add...

"Item Mute =" ..

And here "Item Position =" ..

I save and run.

It seems that I made a mistake somewhere...

Oh I forgot to add points
to tell we merge two strings.

I run the script again.

We see Item Mute = 0 and
Item Position = 0

Item Position = 0 because
I made a mistake here (one trailing space).

We will have to be vigilent when coding one small
space at the wrong place can broke the script.

I run the script again.

Here we see the item position
in seconds.

As you can see, it is very precise.

If I want to display the duration,
I duplicate

I get the parameter value here.

I replace.

I rename the variable.

And I duplicate that too,
and display the item length.

I save, I select the item
I run the script.

We see that the item length
as the same value as the item pos

because I forgot to copy paste
the variable here...

Voilà. I run again.

We will see that the
item length is 9 seconds.

If I make it shorter, it display 5s,
if I extend, it displays 9 seconds.

Another item parameter often used
by scripters is the volume.

I will show you how it works,
because it is a bit special.

I duplicate this.

"D_VOL"

Note that the variable can be named
with every name that you want.

I duplicate this line.

And I wrote item_vol here.

If I execute the script, I can see that
item_vol = 1

However, I see that item volume
is set to 0 dB.

It is because the scale of the
vol parameter displayed in the console

is completly different.

The value returned bu "D_VOL"
is on a log scale.

If item_vol = 0, it means that
that item volume is -inf dB

If item_vol > 1, it means that
the item had a volume boost.

I'll show you, if I set -7 dB,
and that I run the script again...

We see that it is 0.4 (log scale)

If I boost at 10 dB, it is equal to 3
(approx).

2 on log scale is for 6 dB boost
(approx).

To convert the log scale value
into dB

We have to do some maths.

It is a bit complicated but
we can use a code snippet

a small code chunk that you can use
without having to write it from scratch

You only have to understand
what variable you have to replace.

Here, we just have to replace
some variable names.

We will replace VolDB by item_voldB so
that it matches our other variable naming

Here, the value to put
is the value of item_vol

which is transform
by this formula.

If I display item_volDB here...

we can see that here is 0dB.

And here is too. If I set to -7db
it displays -7 in the console.

If I go to +6db it displays +6.

There is other nice parameters,

such as fades length,

snap offset position,

and color of the object.

Now imagine that we want to
modify these values.

There is a sister function of
GetMedialtemlnfo_Value which is...

I'll show you...

which is SetMedialtemlnfo_Value

we can see that it look like the Get
version so that there a third parameter

which is the new value we want
to set.

I will copy that.

Put it here...

The item we want to modify
is still in the item variable.

We will start by setting
the mute parameter.

"B_MUTE"

As new value, we set 0.

If I run the script...

Nothing happens.

But if I zoom out,
or click, you see that

the item has been unmuted.

We have to add at the end of the script

a simple function UpdateArrange

which allows to update the arrange view
if some items have been modified.

Now, if I change the script...

You see that I don't need to click

to refresh the arrange view
(and the item).

Now if I want to modify...

the position...

I write a new position in seconds.

I set "D_POSITION" as second parameter.

And now my item should go to 1.5 second.

The item is nicely placed at 1.5 s
in the project.

If I set 3...

it will go there...

We can of course use calculations.

5 + 10

and it will go at position 15 s.

To modify the volume,

I will advice you to modify the
volume converted in dB.

But you will have to set it back
to log to make the modification valid.

If we want to add
+1 dB to our item

We can do the following thing...

And here I do...

reaper. SeMedialtemlnfo_Value(item,
"D_VOL"...

reaper. SeMedialtemlnfo_Value(item,
"D_VOL", item_volDB)

It is still express into dB
we have to convert it in Log scale

Here is the code snippet.

We put it here.

And we replace calc
the variable we have to change,

by what we wanted (our dB value +1)

I unmute the item,
and I run the script.

The item goes to position 0,
its volume had a +1 dB boost,

and it is not muted anymore.
If I run the script again...

we will see that the item volume
gets another extra +1 dB boost.

If I want to substract 1 dB,
I set - here, and when I run the script...

The item volume goes down.

In the next videos, we will see how to get the
parameter values of several selected items

and how to modify them
one after the other.