RPR GetSetItemState

From CockosWiki

(Difference between revisions)
Jump to: navigation, search
(→GetSetItemState())
 
(36 intermediate revisions not shown)
Line 5: Line 5:
This function gets or sets the state of a media item as an xml-ish rpp chunk.
This function gets or sets the state of a media item as an xml-ish rpp chunk.
-
When calling the function, if you set str="" it will return the current state of the item in the corresponding  
+
When calling the function, if you set str="" it will return the current state of the item in the corresponding return array/list element.
-
the returned state string is limited to maxlen characters, though there is an upper limit (currently 16K) on maxlen.
+
the returned state string is limited to maxlen characters, though there is an upper limit (currently 1MB) on maxlen.
supply str as an xml/rpp string to set the object state.
supply str as an xml/rpp string to set the object state.
returns true on success.
returns true on success.
-
GetSetItemState() can be used to examine the state of the item - the item's properties; it returns a string in its return array. Below is the item state of a short MIDI item.
+
GetSetItemState() can be used to examine the state of the item - the item's properties; it returns a string in its return array.  
 +
 
 +
==Item State Chunk Definitions==
 +
''Comments and blank lines in these State Chunks are for illustration only, you can't really have blank lines and comments in State Chunks''
 +
 
 +
''Parameters are defined once per Wiki page, rather than repeat a definition on perhaps each Item State Chunk example on this page. For the moment anyway.''
 +
===Audio Item State Chunk===
<pre>
<pre>
-
<ITEM
+
 
-
POSITION 12.00000000000000
+
<ITEM                                                   // Item section start
-
SNAPOFFS 0.00000000000000
+
    POSITION 0.00000000000000                           // Item position on the timeline, in seconds
-
LENGTH 8.81585503963759
+
    SNAPOFFS 0.00000000000000                           // Snap offset, in seconds
-
LOOP 1
+
    LENGTH 145.50000000000000                          // Item length, in seconds
-
ALLTAKES 0
+
    LOOP 0                                              // Loop source active? int (bool)
-
SEL 1
+
    ALLTAKES 0                                         // Play all takes at once? 0 - no, 1 - yes
-
FADEIN 1 0.000000 0.000000
+
    COLOR 22278759                                      // Item colour, int , Not present if not set.
-
FADEOUT 1 0.000000 0.000000
+
    BEAT 0                                              // Item timebase, int, Not present if not set. -1 = use track timebase
-
MUTE 0
+
    SEL 1                                               // Is the item selected? int (bool)
-
IGUID {967EE770-4144-472A-89D6-B72BB910A916}
+
    FADEIN 1 0.010000 0.000000                         // Fade in settings
-
NAME "lalala untitled MIDI item"
+
                                                        //  field 1, int, fade in curve type (0 - linear, etc.)
-
VOLPAN 1.000000 0.000000 1.000000 -1.000000
+
                                                        //  field 2, float, fade in time (in seconds)
-
SOFFS 0.00000000000000 0.00000000000000
+
                                                        //  field 3, float, ??
-
PLAYRATE 1.00000000000000 1 0.00000000000000 -65536
+
    FADEOUT 1 0.010000 0.000000                         // Fade out settings
-
CHANMODE 0
+
                                                        //  field 1, int, fade out curve type (0 - linear, etc.)
-
GUID {9C93A652-09A2-4A46-9E1B-EF83EB7CED29}
+
                                                        //  field 2, float, fade out time (in seconds)
-
<SOURCE MIDI
+
                                                        //  field 3, float, ??
-
HASDATA 1 960 QN
+
    MUTE 0                                             // Is the item muted? int (bool)
-
e 300 90 2b 60
+
    FADEFLAG 1                                          // ??, int, may not be present
-
e 60 80 2b 00
+
    IGUID {98E8ECDE-FF4D-4E06-87ED-43A5E7E6A61A}       // Item id. Leave it alone
-
E 120 90 27 60
+
    NAME "Some Name or Other - stem"                   // First take name
-
E 60 80 27 00
+
    VOLPAN 1.000000 0.000000 1.000000 -1.000000         // Volume and pan settings
-
E 1200 90 2c 60
+
                                                        // field 1, float, item volume, 1.00 - 0 dB, 16.00 - +24 dB, 0.50 - -6 dB
-
E 60 80 2c 00
+
                                                        // field 2, float, first take pan, -1.00 = left, 1.00 = right
-
E 60 90 29 60
+
                                                        // field 3, float, first take volume (other takes in TAKEVOLPAN below)
-
E 60 80 29 00
+
                                                        // field 4, float, first take pan law
-
E 360 90 2a 60
+
    SOFFS 0.00000000000000                             // First take slip offset (in seconds)
-
E 60 80 2a 00
+
    PLAYRATE 1.00000000000000 1 0.00000000000000 -1    // First take playrate settings
-
E 120 90 26 60
+
                                                        //  field 1, float, playrate
-
E 60 80 26 00
+
                                                        //  field 2, int (bool), preserve pitch while changing rate
-
E 540 90 2a 60
+
                                                        //  field 3, float, pitch adjust, in semitones.cents
-
E 60 80 2a 00
+
                                                        //  field 4, int, pitch shifting/time stretch mode and preset
-
E 120 90 2e 60
+
                                                        //    -1 - project default
-
E 60 80 2e 00
+
                                                        //    0-2 - Sound Touch (3 presets)
-
E 540 b0 7b 00
+
                                                        //    65536-65567 - Dirac LE (32 presets)
-
GUID {9DAB52C8-6257-4A4E-9E60-323514C0DB9B}
+
                                                        //    131072-131119 - Low quality windowed (48 presets)
-
IGNTEMPO 0 120.00000000 4 4
+
                                                        //    196608-196639 - élastique Pro (32 presets)
-
VELLANE 128 97 0
+
                                                        //    262144-262147 - élastique Efficient (4 presets)
-
BANKPROGRAMFILE "C:\Program Files\REAPER/Data/GM.reabank"
+
                                                        //    327680-327683 - élastique SOLOIST (4 presets)
-
CFGEDITVIEW 3787.833051 0.178906 0 48 0 0 0
+
                                                        //    393216-393247 - élastique 2.1 Pro (32 presets)
-
CFGEDIT 1 1 0 1 1 16 1 1 1 1 1 0.06250000 -4 -4 1404 1001 0 2 0 0 0.00000000 0 0
+
                                                        //    458752-458755 - élastique 2.1 Efficient (4 presets)
-
EVTFILTER 0 -1 -1 -1 -1 0 1
+
                                                        //    524288-524291 - élastique 2.1 SOLOIST (4 presets)
-
>
+
    CHANMODE 0                                         // Channel mode, int
-
>
+
                                                        //  0 = normal, 1 = reverse stereo, 2 = mono (downmix)
 +
                                                        //  3 = mono (left), 4 = mono (right)
 +
    GUID {4EB7779B-D570-4CCF-8739-161D2D32C154}         // Take id. Leave it alone
 +
    <SOURCE SECTION                                    // Source section start (only present when changed in Item properties)
 +
    LENGTH 0.00000000000000                            // Section length
 +
    MODE 3                                              // Mode, 2 = Section and Reverse, 3 = Reverse
 +
    STARTPOS 0.00000000000000                          // Section start offset (in seconds)
 +
    OVERLAP 0.01000000000000                            // Section crossfade (in seconds)
 +
    <SOURCE WAVE                                        // Source details. Appears alone if SOURCE SECTION not set
 +
    FILE "C:Path\To\AudioFile.wav"                      // Source file.
 +
    >                                                  // Source details end
 +
    >                                                  // Source section end
 +
    TAKE SEL                                            // Second take start. SEL only appears if this take is selected
 +
    NAME "Some Name or Other - stem reversed"          // Take name
 +
    TAKEVOLPAN 0.000000 1.000000 -1.000000              // Take volume and pan settings
 +
                                                        //  field 1, float, take pan
 +
                                                        //  field 2, float, take volume
 +
                                                        //  field 3, float, take pan law
 +
    SOFFS 0.00000000000000                              // Take slip offset (in seconds)
 +
    PLAYRATE 1.00000000000000 1 0.00000000000000 -1    // see PLAYRATE above
 +
    CHANMODE 1                                          // see CHANMODE above
 +
    GUID {4EB7779B-D570-4CCF-8739-161D2D32C154}         // Take id. Leave it alone
 +
    <SOURCE WAVE                                        // Take source details
 +
    FILE "C:\Full\Path\To\AudioFile reversed.wav"       // Source filename
 +
    >                                                  // Source section end
 +
 
 +
                                                        // --- Start of Take FX section ----
 +
    <TAKEFX                                            //    Not present if take hasn't got/had FX ---
 +
      WNDRECT 98 97 747 454                            // FX Window pos, int (top, left, width, height)
 +
      SHOW 0                                           // Show FX window, int (bool)
 +
      LASTSEL 0                                         // Index of selected plugin (zero based), int
 +
      DOCKED 0                                         // FX window is docked, int (bool)
 +
 
 +
                                                        // --- Start of first plugin definition
 +
      BYPASS 0 0                                       //  Plugin bypass state
 +
                                                        //  field 1, int (bool), bypassed
 +
                                                        //  field 2, int (bool), offline
 +
      <VST "VST: ReaEQ (Cockos)" "reaeq.dll" 0 ""      //  Start of VST plugin data
 +
                                                        //  field 1, str, default name
 +
                                                        //  field 2, str, filename
 +
                                                        //  field 3, int, ??
 +
                                                        //  field 4, str, display name (default used if empty)
 +
        cWVlcu5e7f4CAAA......AAAABAAAAAAAAAA==          //  Binary data, leave it alone (variable number of lines)
 +
        AgAAAAAAAACgAAA......AAAABAAAAAAAAAA==          //
 +
        AABZQAAAAAAAAPA......AAAAAAMByQAAAAA==          //
 +
        AAAA8D8AAAAAAAA......AAAAAAAAA8D8AAA==          //
 +
        AAAAAABAAQEAAAA......wPwAAAAAAAABAAQ==          //
 +
        AQAAAAEAAAAAAAA......BAAAAA=                    //
 +
      >                                                //  End of VST plugin data
 +
      FLOATPOS 0 0 0 0                                 //  Plugin floating window pos, int (top, left, width, height)
 +
      FXID {C8C640E0-AE49-4DDD-925E-84F865FDEC24}      //  Plugin id, leave it alone
 +
      WAK 0                                             //  int, ??
 +
                                                        // --- End of first plugin definition
 +
    >                                                   // --- End of FX section
 +
>                                                       // Item section end
</pre>
</pre>
-
You can then use the same function to set one or more properties of that item. This is shown in the Perl example below.
+
===Midi Item State Chunk===
 +
One example is below, but more info can be found in the [[StateChunkAndRppMidiFormat]] page.
 +
<pre>
 +
<ITEM                                                  // Item section start
 +
    POSITION 12.00000000000000                          // Duplicated definition, see Audio item state chunk above
 +
    SNAPOFFS 0.00000000000000
 +
    LENGTH 8.81585503963759
 +
    LOOP 1
 +
    ALLTAKES 0
 +
    SEL 1
 +
    FADEIN 1 0.000000 0.000000
 +
    FADEOUT 1 0.000000 0.000000
 +
    MUTE 0
 +
    IGUID {967EE770-4144-472A-89D6-B72BB910A916}
 +
    NAME "lalala untitled MIDI item"
 +
    VOLPAN 1.000000 0.000000 1.000000 -1.000000
 +
    SOFFS 0.00000000000000 0.00000000000000            // Slip offset (in seconds; the second field is always twice the first field)
 +
    PLAYRATE 1.00000000000000 1 0.00000000000000 -65536
 +
    CHANMODE 0
 +
    GUID {9C93A652-09A2-4A46-9E1B-EF83EB7CED29}
 +
    <SOURCE MIDI                                        // Source section start
 +
        HASDATA 1 960 QN                                // Does the item have any data? PPQ resolution in ticks per quarter note
 +
        e 300 90 2b 60                                  // Standard MIDI message
 +
                                                        // field1, e - selected, E - not selected
 +
                                                        // field2, int, msg start offset
 +
                                                        // field3, msg type and channel num, hexadecimal
 +
                                                            // 80 - Note Off, channel 0
 +
                                                            // 90 - Note On, channel 0
 +
                                                            // b0 - Control Change, channel 0
 +
                                                        // field4, Data1, depends on the message type (eg. note number)
 +
                                                        // field5, Data2, depends on the message type (eg. velocity)
 +
        e 60 80 2b 00                                  // selected msg, offset 60, note off, note 2b, velocity 0
 +
        <X 286306 0                                    // SysEx section start (SysEx midi message, variable length)
 +
                                                        // field1, x - selected, X - not selected
 +
                                                        // field2, ?
 +
                                                        // field3, ?
 +
          8AECAwQF9w==                                  // (Base64 encoded)
 +
        >                                              // SysEx section end
 +
        E 540 b0 7b 00                                  // unselected msg, offset 540, Control Change , all notes off (cc123)
 +
        GUID {9DAB52C8-6257-4A4E-9E60-323514C0DB9B}
 +
        IGNTEMPO 0 120.00000000 4 4                    // Ignore project tempo, override with new settings
 +
                                                        // field1, int, ignore on/off
 +
                                                        // field2, float, tempo used to override project tempo
 +
                                                        // field3-4, int, time signature to override project time signature
 +
        VELLANE 128 97 0                                // Velocity/CC lane settings
 +
                                                        // field1, int, lane type
 +
                                                          // -1 - velocity
 +
                                                          // 0-119 - CC #0 - CC #119
 +
                                                          // 128 - pitch bend
 +
                                                          // 129 - program
 +
                                                          // 130 - channel pressure
 +
                                                          // 131 - bank/program select
 +
                                                          // 132 - text events
 +
                                                          // 133 - sysex
 +
                                                        // field2, int, height of the lane in MIDI editor mode
 +
                                                        // field3, int, height of the lane in inline editor mode
 +
        BANKPROGRAMFILE "C:\Path\To\GM.reabank"        // Path to ReaBank file used by the current item
 +
        CFGEDITVIEW 3787.833051 0.178906 0 48 0 0 0    // Somehow related to H/V zoom levels and scrollbar positions
 +
        CFGEDIT 1 1 0 1 1 16 1 1 1 1 1 0.06250000 0 0  // Configuration variables for MIDI editor window
 +
        1024 768 0 2 0 0 0.00000000 0 0                // field1, int, ?
 +
                                                        // field2, int, state of Sync editor transport to project transport
 +
                                                          // 0 - off, 1 - on
 +
                                                        // field3, int, ?
 +
                                                        // field4, int, state of Show velocity handles
 +
                                                          // 0 - off, 1 - on
 +
                                                        // field5, int, state of Show note names
 +
                                                          // 0 - off, 1 - on
 +
                                                        // field6, int, state of ME view modes
 +
                                                          // 0 - piano roll, rectangle
 +
                                                          // 1 - named notes, rectangle
 +
                                                          // 5 - event list, rectangle
 +
                                                          // 8 - piano roll, triangle
 +
                                                          // 9 - named notes, triangle
 +
                                                          // 13 - event list, triangle
 +
                                                          // 16 - piano roll, diamond
 +
                                                          // 17 - named notes, diamond
 +
                                                          // 21 - event list, diamond
 +
                                                        // field7, int, ?
 +
                                                        // field8, int, state of Move CCs with notes
 +
                                                          // 0 - off, 1 - on
 +
                                                        // field9, int, ?
 +
                                                        // field10, int, state of Snap to grid
 +
                                                          // 0 - off, 1 - on
 +
                                                        // field11, int, state of Show grid
 +
                                                          // 0 - off, 1 - on
 +
                                                        // field12, float, grid division unit, in beats.ticks
 +
                                                        // field13, field14, int, X and Y coords of upper left corner of ME window
 +
                                                        // field15, field16, int, X and Y coords of bottom right corner of ME window
 +
                                                        // field17, int, state of Dock window
 +
                                                          // 0 - off, 1 - on
 +
                                                        // field18, int, state of Note row view modes
 +
                                                          // 0 - show all rows
 +
                                                          // 1 - hide unused rows
 +
                                                          // 2 - hide unused and unnamed rows
 +
                                                        // field19, int, state of Timebase setting
 +
                                                          // 0 - project beats
 +
                                                          // 1 - project sync
 +
                                                          // 2 - project time
 +
                                                          // 4 - source beats
 +
                                                        // field20, int, state of Color mode setting
 +
                                                          // 0 - velocity
 +
                                                          // 1 - channel
 +
                                                          // 2 - pitch
 +
                                                          // 4 - source
 +
                                                        // field21, float, length of last drawn note, in beats.ticks
 +
                                                        // field22, int, state of Reuse window mode
 +
                                                          // 0 - no reuse
 +
                                                          // 1 - reuse MIDI editor window
 +
                                                          // 2 - reuse MIDI editor window, keeping current item secondary
 +
                                                        // field23, int, state of Show velocity numbers
 +
                                                          // 0 - off, 1 - on
 +
        EVTFILTER 0 -1 -1 -1 -1 0 1                    // Event filter settings
 +
                                                        // field1, int (16-bit mask), state of channel checkboxes
 +
                                                          // 0000000000000000 (0) - "All" is checked, 1-16 unchecked
 +
                                                          // 1111111111111111 (65536) - "All" is checked along with 1-16
 +
                                                          // 1000000000000001 (32769) -  1 (LSB) and 16 (MSB) are selected
 +
                                                          // etc.
 +
                                                        // field2, int, Event type
 +
                                                          // -1 - <all>
 +
                                                          // 144 - Note
 +
                                                          // 160 - Poly Aftertouch
 +
                                                          // 176 - Control Change (CC)
 +
                                                          // 192 - Program Change (PC)
 +
                                                          // 208 - Channel Aftertouch
 +
                                                          // 224 - Pitch
 +
                                                          // 240 - Sysex/Meta
 +
                                                        // field3, int, Parameter field (range: 0-127)
 +
                                                        // field4, int, Value Low field (range: 0-127)
 +
                                                        // field5, int, Value High field (range: 0-127)
 +
                                                        // field6, int, Draw events on channel setting (range: 0-15)
 +
                                                        // field7, int, Enable filter setting (0 is off, 1 is on)
 +
    >                                                  // Source section end
 +
 
 +
                                                        // --- Start of Take FX section ----
 +
    <TAKEFX                                            //    Not present if take hasn't got/had FX ---
 +
      WNDRECT 4 50 747 454                              // Duplicated definition, see Audio item
 +
      SHOW 0
 +
      LASTSEL 0
 +
      DOCKED 0
 +
      BYPASS 0 0
 +
      <VST "VST: ReaEQ (Cockos)" "reaeq.dll" 0 ""
 +
        cWVlcu5e7f4CAAA......AAAABAAAAAAAAAA==
 +
        AgAAAAAAAACgAAA......AAAABAAAAAAAAAA==
 +
        AABZQAAAAAAAAPA......AAAAAAMByQAAAAA==
 +
        AAAA8D8AAAAAAAA......AAAAAAAAA8D8AAA==
 +
        AAAAAABAAQEAAAA......wPwAAAAAAAABAAQ==
 +
        AQAAAAEAAAAAAAA......BAAAAA=
 +
      >
 +
      FLOATPOS 0 0 0 0
 +
      FXID {6835B2B2-4FD8-4593-B250-C3B0F4676F0B}
 +
      WAK 0
 +
    >                                                  // --- End of FX section
 +
>                                                      // Item section end
 +
</pre>
 +
MIDI Event -> field2 above... This is the number of ticks (it's ok, I'll tell you in a minute) since the last event or (if this is the first MIDI Event) the start of the Item.
 +
 
 +
Ticks then. A tick is a small slice of a beat, so the number of Ticks per second varies with the BPM (Beats Per Minute) of the music.
 +
 
 +
<wiki math markup> <math>1 beat = 2.6041666666666666666666666666667e-4 \times 240 \times 16</math> </wiki math markup>
 +
 
 +
1 beat = 2.6041666666666666666666666666667e-4 * 240 * 16
 +
 
 +
The MIDI format used in REAPER State Chunks and .rpp files is documented here [[StateChunkAndRppMidiFormat|State Chunk And RPP MIDI Format]].
==Parameters==
==Parameters==
  MediaItem* item,  A pointer to a valid MediaItem, as returned by GetSelectedMediaItem()
  MediaItem* item,  A pointer to a valid MediaItem, as returned by GetSelectedMediaItem()
  char* str,        str="" to get the state returned in str, str as an xml/rpp string to set the object state.
  char* str,        str="" to get the state returned in str, str as an xml/rpp string to set the object state.
-
  int maxlen,        maximum number of characters that will be returned, limited to 16k
+
  int maxlen,        maximum number of characters that will be returned, limited to 1MB
==Returns==
==Returns==
  An Array/List
  An Array/List
Line 71: Line 293:
   char* str,        the current state of the item, possibly after a Set operation
   char* str,        the current state of the item, possibly after a Set operation
   int maxlen,      unchanged
   int maxlen,      unchanged
 +
==Caveats==
 +
After using AddMediaItemToTrack() and then setting the contents of the new item with GetSetItemState() you might experience some "graphical glitches" - involving Items apparently disappearing after Zooming in or out, Waveforms (Peaks images) not always displaying.
 +
 +
These odd things resolve after saving the project, closing and then reloading it but that's not something you'll want to do in a script. The Item's display will also be corrected if you use another (Non-GetSet*State function) to update the Item, e.g You could use SetMediaItemInfo_Value() to set the position.
==Examples==
==Examples==
 +
===C++===
 +
<source lang=cpp>
 +
</source>
 +
 +
===Perl===
===Perl===
-
<pre>
+
<source lang=perl>
#
#
# GetSetItemState.pl
# GetSetItemState.pl
Line 102: Line 333:
RPR_ShowConsoleMsg("GetSetItemState reports $result\n$chunk\n");
RPR_ShowConsoleMsg("GetSetItemState reports $result\n$chunk\n");
-
RPR_ShowConsoleMsg("LENGTH = $length\n");
 
# Pick out the LENGTH property
# Pick out the LENGTH property
$chunk =~ /LENGTH\s+(.*)\n/;
$chunk =~ /LENGTH\s+(.*)\n/;
Line 118: Line 348:
$result = "pass" if $bool;
$result = "pass" if $bool;
RPR_ShowConsoleMsg("AFTER SET: GetSetItemState reports $result\n$chunk\n");
RPR_ShowConsoleMsg("AFTER SET: GetSetItemState reports $result\n$chunk\n");
-
</pre>
+
</source>
 +
 
 +
 
===Python===
===Python===
-
<pre>
+
<source lang=python>
-
</pre>
+
#
 +
# GetSetItemState.py
 +
#
 +
# "Get" and "Set" example (converted from Perl example above)
 +
# regex could probably be better but hey, it works :)
 +
 
 +
import re
 +
 
 +
CURR_PROJ = 0
 +
 
 +
bool = 0
 +
it = 0
 +
chunk = 0
 +
maxlen = 0
 +
length = -1;
 +
result = "fail"
 +
 
 +
# Get the first selected item in the current project
 +
it = RPR_GetSelectedMediaItem(CURR_PROJ, 0)
 +
 
 +
# Set-up for call to GetSetItemState
 +
chunk = ""    # Get, not Set
 +
maxlen = 2048  # max num of chars to return
 +
 
 +
# Get the ItemState
 +
(bool, it, chunk, maxlen) = RPR_GetSetItemState(it, chunk, maxlen)
 +
if bool :
 +
    result = "pass"
 +
 +
RPR_ShowConsoleMsg("GetSetItemState reports result\n" + chunk + "\n")
 +
 
 +
# Pick out the LENGTH property
 +
ex = re.compile(r"LENGTH\s+(.*)\n")
 +
match = ex.search(chunk)
 +
length = float(match.group(1));
 +
 
 +
# Display the current LENGTH property
 +
RPR_ShowConsoleMsg("LENGTH = " + str(length) + "\n\n");
 +
 
 +
# Add one second to the LENGTH property
 +
length += 1;
 +
 
 +
chunk = ex.sub("LENGTH " + str(length) + "\n", chunk)
 +
 
 +
# Set the ItemState
 +
result = "fail";
 +
(bool, it, chunk, maxlen) = RPR_GetSetItemState(it, chunk, maxlen)
 +
if bool :
 +
    result = "pass"
 +
 +
RPR_ShowConsoleMsg("AFTER SET: GetSetItemState reports result\n" + chunk + "\n"
 +
</source>
 +
 
==See Also==
==See Also==
-
{{SeeAlsoMediaItemFunctions}}
+
{{SeeAlso_GetSetState}}
 +
 
 +
{{SeeAlso_item}}
 +
 
 +
''(Section automatically generated, edits may be overwritten.)''
==Stuff==
==Stuff==

Latest revision as of 22:53, 5 September 2012

Main Page > REAPER Documentation > ReaScript > ReaScript API, Functions > RPR GetSetItemState
Main Page > REAPER Documentation > REAPER API > REAPER API Functions > RPR GetSetItemState

Contents

GetSetItemState()

bool GetSetItemState(MediaItem* item, char* str, int maxlen)

This function gets or sets the state of a media item as an xml-ish rpp chunk.

When calling the function, if you set str="" it will return the current state of the item in the corresponding return array/list element. the returned state string is limited to maxlen characters, though there is an upper limit (currently 1MB) on maxlen. supply str as an xml/rpp string to set the object state. returns true on success.

GetSetItemState() can be used to examine the state of the item - the item's properties; it returns a string in its return array.

Item State Chunk Definitions

Comments and blank lines in these State Chunks are for illustration only, you can't really have blank lines and comments in State Chunks

Parameters are defined once per Wiki page, rather than repeat a definition on perhaps each Item State Chunk example on this page. For the moment anyway.

Audio Item State Chunk


<ITEM                                                   // Item section start
    POSITION 0.00000000000000                           // Item position on the timeline, in seconds
    SNAPOFFS 0.00000000000000                           // Snap offset, in seconds
    LENGTH 145.50000000000000                           // Item length, in seconds
    LOOP 0                                              // Loop source active? int (bool)
    ALLTAKES 0                                          // Play all takes at once? 0 - no, 1 - yes
    COLOR 22278759                                      // Item colour, int , Not present if not set.
    BEAT 0                                              // Item timebase, int, Not present if not set. -1 = use track timebase
    SEL 1                                               // Is the item selected? int (bool)
    FADEIN 1 0.010000 0.000000                          // Fade in settings
                                                        //  field 1, int, fade in curve type (0 - linear, etc.)
                                                        //  field 2, float, fade in time (in seconds)
                                                        //  field 3, float, ??
    FADEOUT 1 0.010000 0.000000                         // Fade out settings
                                                        //  field 1, int, fade out curve type (0 - linear, etc.)
                                                        //  field 2, float, fade out time (in seconds)
                                                        //  field 3, float, ??
    MUTE 0                                              // Is the item muted? int (bool)
    FADEFLAG 1                                          // ??, int, may not be present
    IGUID {98E8ECDE-FF4D-4E06-87ED-43A5E7E6A61A}        // Item id. Leave it alone
    NAME "Some Name or Other - stem"                    // First take name
    VOLPAN 1.000000 0.000000 1.000000 -1.000000         // Volume and pan settings
                                                        // field 1, float, item volume, 1.00 - 0 dB, 16.00 - +24 dB, 0.50 - -6 dB
                                                        // field 2, float, first take pan, -1.00 = left, 1.00 = right
                                                        // field 3, float, first take volume (other takes in TAKEVOLPAN below)
                                                        // field 4, float, first take pan law
    SOFFS 0.00000000000000                              // First take slip offset (in seconds)
    PLAYRATE 1.00000000000000 1 0.00000000000000 -1     // First take playrate settings
                                                        //  field 1, float, playrate
                                                        //  field 2, int (bool), preserve pitch while changing rate
                                                        //  field 3, float, pitch adjust, in semitones.cents
                                                        //  field 4, int, pitch shifting/time stretch mode and preset
                                                        //    -1 - project default
                                                        //    0-2 - Sound Touch (3 presets)
                                                        //    65536-65567 - Dirac LE (32 presets)
                                                        //    131072-131119 - Low quality windowed (48 presets)
                                                        //    196608-196639 - élastique Pro (32 presets)
                                                        //    262144-262147 - élastique Efficient (4 presets)
                                                        //    327680-327683 - élastique SOLOIST (4 presets)
                                                        //    393216-393247 - élastique 2.1 Pro (32 presets)
                                                        //    458752-458755 - élastique 2.1 Efficient (4 presets)
                                                        //    524288-524291 - élastique 2.1 SOLOIST (4 presets)
    CHANMODE 0                                          // Channel mode, int
                                                        //   0 = normal, 1 = reverse stereo, 2 = mono (downmix)
                                                        //   3 = mono (left), 4 = mono (right)
    GUID {4EB7779B-D570-4CCF-8739-161D2D32C154}         // Take id. Leave it alone
    <SOURCE SECTION                                     // Source section start (only present when changed in Item properties)
    LENGTH 0.00000000000000                             // Section length
    MODE 3                                              // Mode, 2 = Section and Reverse, 3 = Reverse
    STARTPOS 0.00000000000000                           // Section start offset (in seconds)
    OVERLAP 0.01000000000000                            // Section crossfade (in seconds)
    <SOURCE WAVE                                        // Source details. Appears alone if SOURCE SECTION not set
    FILE "C:Path\To\AudioFile.wav"                      // Source file. 
    >                                                   // Source details end
    >                                                   // Source section end
    TAKE SEL                                            // Second take start. SEL only appears if this take is selected
    NAME "Some Name or Other - stem reversed"           // Take name
    TAKEVOLPAN 0.000000 1.000000 -1.000000              // Take volume and pan settings
                                                        //  field 1, float, take pan
                                                        //  field 2, float, take volume
                                                        //  field 3, float, take pan law
    SOFFS 0.00000000000000                              // Take slip offset (in seconds)
    PLAYRATE 1.00000000000000 1 0.00000000000000 -1     // see PLAYRATE above
    CHANMODE 1                                          // see CHANMODE above
    GUID {4EB7779B-D570-4CCF-8739-161D2D32C154}         // Take id. Leave it alone
    <SOURCE WAVE                                        // Take source details
    FILE "C:\Full\Path\To\AudioFile reversed.wav"       // Source filename
    >                                                   // Source section end

                                                        // --- Start of Take FX section ----
    <TAKEFX                                             //     Not present if take hasn't got/had FX ---
      WNDRECT 98 97 747 454                             // FX Window pos, int (top, left, width, height)
      SHOW 0                                            // Show FX window, int (bool)
      LASTSEL 0                                         // Index of selected plugin (zero based), int
      DOCKED 0                                          // FX window is docked, int (bool)

                                                        // --- Start of first plugin definition
      BYPASS 0 0                                        //  Plugin bypass state
                                                        //   field 1, int (bool), bypassed
                                                        //   field 2, int (bool), offline
      <VST "VST: ReaEQ (Cockos)" "reaeq.dll" 0 ""       //  Start of VST plugin data
                                                        //   field 1, str, default name
                                                        //   field 2, str, filename
                                                        //   field 3, int, ??
                                                        //   field 4, str, display name (default used if empty)
        cWVlcu5e7f4CAAA......AAAABAAAAAAAAAA==          //  Binary data, leave it alone (variable number of lines)
        AgAAAAAAAACgAAA......AAAABAAAAAAAAAA==          //
        AABZQAAAAAAAAPA......AAAAAAMByQAAAAA==          //
        AAAA8D8AAAAAAAA......AAAAAAAAA8D8AAA==          //
        AAAAAABAAQEAAAA......wPwAAAAAAAABAAQ==          //
        AQAAAAEAAAAAAAA......BAAAAA=                    //
      >                                                 //  End of VST plugin data
      FLOATPOS 0 0 0 0                                  //  Plugin floating window pos, int (top, left, width, height)
      FXID {C8C640E0-AE49-4DDD-925E-84F865FDEC24}       //  Plugin id, leave it alone
      WAK 0                                             //  int, ??
                                                        // --- End of first plugin definition
    >                                                   // --- End of FX section
>                                                       // Item section end

Midi Item State Chunk

One example is below, but more info can be found in the StateChunkAndRppMidiFormat page. 

<ITEM                                                   // Item section start
    POSITION 12.00000000000000                          // Duplicated definition, see Audio item state chunk above
    SNAPOFFS 0.00000000000000
    LENGTH 8.81585503963759
    LOOP 1
    ALLTAKES 0
    SEL 1
    FADEIN 1 0.000000 0.000000
    FADEOUT 1 0.000000 0.000000
    MUTE 0
    IGUID {967EE770-4144-472A-89D6-B72BB910A916}
    NAME "lalala untitled MIDI item"
    VOLPAN 1.000000 0.000000 1.000000 -1.000000
    SOFFS 0.00000000000000 0.00000000000000             // Slip offset (in seconds; the second field is always twice the first field)
    PLAYRATE 1.00000000000000 1 0.00000000000000 -65536
    CHANMODE 0
    GUID {9C93A652-09A2-4A46-9E1B-EF83EB7CED29}
    <SOURCE MIDI                                        // Source section start
        HASDATA 1 960 QN                                // Does the item have any data? PPQ resolution in ticks per quarter note
        e 300 90 2b 60                                  // Standard MIDI message
                                                        // field1, e - selected, E - not selected
                                                        // field2, int, msg start offset
                                                        // field3, msg type and channel num, hexadecimal
                                                            // 80 - Note Off, channel 0
                                                            // 90 - Note On, channel 0
                                                            // b0 - Control Change, channel 0
                                                        // field4, Data1, depends on the message type (eg. note number)
                                                        // field5, Data2, depends on the message type (eg. velocity)
        e 60 80 2b 00                                   // selected msg, offset 60, note off, note 2b, velocity 0
        <X 286306 0                                     // SysEx section start (SysEx midi message, variable length)
                                                        // field1, x - selected, X - not selected
                                                        // field2, ?
                                                        // field3, ?
          8AECAwQF9w==                                  // (Base64 encoded)
        >                                               // SysEx section end
        E 540 b0 7b 00                                  // unselected msg, offset 540, Control Change , all notes off (cc123)
        GUID {9DAB52C8-6257-4A4E-9E60-323514C0DB9B}
        IGNTEMPO 0 120.00000000 4 4                     // Ignore project tempo, override with new settings
                                                        // field1, int, ignore on/off
                                                        // field2, float, tempo used to override project tempo
                                                        // field3-4, int, time signature to override project time signature
        VELLANE 128 97 0                                // Velocity/CC lane settings
                                                        // field1, int, lane type
                                                           // -1 - velocity
                                                           // 0-119 - CC #0 - CC #119
                                                           // 128 - pitch bend
                                                           // 129 - program
                                                           // 130 - channel pressure
                                                           // 131 - bank/program select
                                                           // 132 - text events
                                                           // 133 - sysex
                                                        // field2, int, height of the lane in MIDI editor mode
                                                        // field3, int, height of the lane in inline editor mode
        BANKPROGRAMFILE "C:\Path\To\GM.reabank"         // Path to ReaBank file used by the current item
        CFGEDITVIEW 3787.833051 0.178906 0 48 0 0 0     // Somehow related to H/V zoom levels and scrollbar positions
        CFGEDIT 1 1 0 1 1 16 1 1 1 1 1 0.06250000 0 0   // Configuration variables for MIDI editor window
        1024 768 0 2 0 0 0.00000000 0 0                 // field1, int, ?
                                                        // field2, int, state of Sync editor transport to project transport
                                                           // 0 - off, 1 - on
                                                        // field3, int, ?
                                                        // field4, int, state of Show velocity handles
                                                           // 0 - off, 1 - on
                                                        // field5, int, state of Show note names
                                                           // 0 - off, 1 - on
                                                        // field6, int, state of ME view modes
                                                           // 0 - piano roll, rectangle
                                                           // 1 - named notes, rectangle
                                                           // 5 - event list, rectangle
                                                           // 8 - piano roll, triangle
                                                           // 9 - named notes, triangle
                                                           // 13 - event list, triangle
                                                           // 16 - piano roll, diamond
                                                           // 17 - named notes, diamond
                                                           // 21 - event list, diamond
                                                        // field7, int, ?
                                                        // field8, int, state of Move CCs with notes
                                                           // 0 - off, 1 - on
                                                        // field9, int, ?
                                                        // field10, int, state of Snap to grid
                                                           // 0 - off, 1 - on
                                                        // field11, int, state of Show grid
                                                           // 0 - off, 1 - on
                                                        // field12, float, grid division unit, in beats.ticks
                                                        // field13, field14, int, X and Y coords of upper left corner of ME window
                                                        // field15, field16, int, X and Y coords of bottom right corner of ME window
                                                        // field17, int, state of Dock window
                                                           // 0 - off, 1 - on
                                                        // field18, int, state of Note row view modes
                                                           // 0 - show all rows
                                                           // 1 - hide unused rows
                                                           // 2 - hide unused and unnamed rows
                                                        // field19, int, state of Timebase setting
                                                           // 0 - project beats
                                                           // 1 - project sync
                                                           // 2 - project time
                                                           // 4 - source beats
                                                        // field20, int, state of Color mode setting
                                                           // 0 - velocity
                                                           // 1 - channel
                                                           // 2 - pitch
                                                           // 4 - source
                                                        // field21, float, length of last drawn note, in beats.ticks
                                                        // field22, int, state of Reuse window mode
                                                           // 0 - no reuse
                                                           // 1 - reuse MIDI editor window
                                                           // 2 - reuse MIDI editor window, keeping current item secondary
                                                        // field23, int, state of Show velocity numbers
                                                           // 0 - off, 1 - on
        EVTFILTER 0 -1 -1 -1 -1 0 1                     // Event filter settings
                                                        // field1, int (16-bit mask), state of channel checkboxes
                                                           // 0000000000000000 (0) - "All" is checked, 1-16 unchecked
                                                           // 1111111111111111 (65536) - "All" is checked along with 1-16
                                                           // 1000000000000001 (32769) -  1 (LSB) and 16 (MSB) are selected
                                                           // etc.
                                                        // field2, int, Event type
                                                           // -1 - <all>
                                                           // 144 - Note
                                                           // 160 - Poly Aftertouch
                                                           // 176 - Control Change (CC)
                                                           // 192 - Program Change (PC)
                                                           // 208 - Channel Aftertouch
                                                           // 224 - Pitch
                                                           // 240 - Sysex/Meta
                                                        // field3, int, Parameter field (range: 0-127)
                                                        // field4, int, Value Low field (range: 0-127)
                                                        // field5, int, Value High field (range: 0-127)
                                                        // field6, int, Draw events on channel setting (range: 0-15)
                                                        // field7, int, Enable filter setting (0 is off, 1 is on)
    >                                                   // Source section end

                                                        // --- Start of Take FX section ----
    <TAKEFX                                             //     Not present if take hasn't got/had FX ---
      WNDRECT 4 50 747 454                              // Duplicated definition, see Audio item 
      SHOW 0
      LASTSEL 0
      DOCKED 0
      BYPASS 0 0
      <VST "VST: ReaEQ (Cockos)" "reaeq.dll" 0 ""
        cWVlcu5e7f4CAAA......AAAABAAAAAAAAAA==
        AgAAAAAAAACgAAA......AAAABAAAAAAAAAA==
        AABZQAAAAAAAAPA......AAAAAAMByQAAAAA==
        AAAA8D8AAAAAAAA......AAAAAAAAA8D8AAA==
        AAAAAABAAQEAAAA......wPwAAAAAAAABAAQ==
        AQAAAAEAAAAAAAA......BAAAAA=
      >
      FLOATPOS 0 0 0 0
      FXID {6835B2B2-4FD8-4593-B250-C3B0F4676F0B}
      WAK 0
    >                                                   // --- End of FX section
>                                                       // Item section end

MIDI Event -> field2 above... This is the number of ticks (it's ok, I'll tell you in a minute) since the last event or (if this is the first MIDI Event) the start of the Item.

Ticks then. A tick is a small slice of a beat, so the number of Ticks per second varies with the BPM (Beats Per Minute) of the music.

<wiki math markup> <math>1 beat = 2.6041666666666666666666666666667e-4 \times 240 \times 16</math> </wiki math markup>

1 beat = 2.6041666666666666666666666666667e-4 * 240 * 16

The MIDI format used in REAPER State Chunks and .rpp files is documented here State Chunk And RPP MIDI Format.

Parameters

MediaItem* item,   A pointer to a valid MediaItem, as returned by GetSelectedMediaItem()
char* str,         str="" to get the state returned in str, str as an xml/rpp string to set the object state.
int maxlen,        maximum number of characters that will be returned, limited to 1MB

Returns

An Array/List
 bool,             true on success, false on failure
 MediaItem* item,  unchanged
 char* str,        the current state of the item, possibly after a Set operation
 int maxlen,       unchanged

Caveats

After using AddMediaItemToTrack() and then setting the contents of the new item with GetSetItemState() you might experience some "graphical glitches" - involving Items apparently disappearing after Zooming in or out, Waveforms (Peaks images) not always displaying.

These odd things resolve after saving the project, closing and then reloading it but that's not something you'll want to do in a script. The Item's display will also be corrected if you use another (Non-GetSet*State function) to update the Item, e.g You could use SetMediaItemInfo_Value() to set the position.

Examples

C++

 


Perl

#
# GetSetItemState.pl
#
# "Get" and "Set" example
#
 
use strict;
use warnings;
 
use constant CURR_PROJ => 0;
 
my ($bool, $it, $chunk, $maxlen);
 
my $length = -1;
my $result = "fail";
 
# Get the first selected item in the current project
$it = RPR_GetSelectedMediaItem(CURR_PROJ, 0);
 
# set-up for call to GetSetItemState
$chunk="";     # Get, not Set
$maxlen=2048;  # max num of chars to return
 
# Get the ItemState
($bool, $it, $chunk, $maxlen) = RPR_GetSetItemState($it, $chunk, $maxlen);
$result = "pass" if $bool;
RPR_ShowConsoleMsg("GetSetItemState reports $result\n$chunk\n");
 
# Pick out the LENGTH property
$chunk =~ /LENGTH\s+(.*)\n/;
$length = $1;
# Display the current LENGTH property
RPR_ShowConsoleMsg("LENGTH = $length\n");
 
# Add one second to the LENGTH property
$length++;
$chunk =~ s/LENGTH.*\n/LENGTH $length\n/;
 
# Set the ItemState
$result = "fail";
($bool, $it, $chunk, $maxlen) = RPR_GetSetItemState($it, $chunk, $maxlen);
$result = "pass" if $bool;
RPR_ShowConsoleMsg("AFTER SET: GetSetItemState reports $result\n$chunk\n");


Python

#
# GetSetItemState.py
#
# "Get" and "Set" example (converted from Perl example above)
# regex could probably be better but hey, it works :)
 
import re
 
CURR_PROJ = 0
 
bool = 0
it = 0
chunk = 0
maxlen = 0 
length = -1;
result = "fail"
 
# Get the first selected item in the current project
it = RPR_GetSelectedMediaItem(CURR_PROJ, 0)
 
# Set-up for call to GetSetItemState
chunk = ""     # Get, not Set
maxlen = 2048  # max num of chars to return
 
# Get the ItemState
(bool, it, chunk, maxlen) = RPR_GetSetItemState(it, chunk, maxlen)
if bool :
    result = "pass"
 
RPR_ShowConsoleMsg("GetSetItemState reports result\n" + chunk + "\n")
 
# Pick out the LENGTH property
ex = re.compile(r"LENGTH\s+(.*)\n")
match = ex.search(chunk)
length = float(match.group(1));
 
# Display the current LENGTH property
RPR_ShowConsoleMsg("LENGTH = " + str(length) + "\n\n");
 
# Add one second to the LENGTH property
length += 1;
 
chunk = ex.sub("LENGTH " + str(length) + "\n", chunk)
 
# Set the ItemState
result = "fail";
(bool, it, chunk, maxlen) = RPR_GetSetItemState(it, chunk, maxlen)
if bool :
    result = "pass"
 
RPR_ShowConsoleMsg("AFTER SET: GetSetItemState reports result\n" + chunk + "\n"

See Also

get set state: GetSetEnvelopeState, GetSetItemState, GetSetTrackState

item: AddMediaItemToTrack, AddTakeToMediaItem, GetTrackMediaItem, GetTrackNumMediaItems, CountMediaItems, CountSelectedMediaItems, GetItemProjectContext, SetMediaItemInfo_Value, CountTrackMediaItems, SetMediaItemTakeInfo_Value, GetMediaItem, GetMediaItem_Track, GetMediaItemInfo_Value, GetMediaItemNumTakes, GetMediaItemTake, GetMediaItemTake_Item, GetMediaItemTake_Source, GetMediaItemTake_Track, GetMediaItemTakeInfo_Value, SplitMediaItem, MoveMediaItemToTrack, GetSelectedMediaItem, DeleteTrackMediaItem, GetSetItemState, GetSetMediaItemTakeInfo_String, Undo_OnStateChange_Item, UpdateItemInProject,

(Section automatically generated, edits may be overwritten.)

Stuff

Main Page > REAPER Documentation > ReaScript > ReaScript API, Functions > RPR GetSetItemState
Main Page > REAPER Documentation > REAPER API > REAPER API Functions > RPR GetSetItemState

Retrieved from "https://wiki.cockos.com/wiki/index.php/RPR_GetSetItemState"