RPR GetSetItemState
From CockosWiki
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 16K) 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? 0 - no, 1 - yes
ALLTAKES 0 // Play all takes at once? 0 - no, 1 - yes
SEL 1 // Is the item selected? 0 - no, 1 - yes
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? 0 - no, 1 - yes
IGUID {98E8ECDE-FF4D-4E06-87ED-43A5E7E6A61A} // ignore, generated nicely by REAPER
NAME "Some Name or Other - stem" // Item 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, item pan, -1.00 - left, 0.00 - center, 1.00 - right
// field 3, float, first take volume (other takes are in TAKEVOLPAN below)
// field 4, float, ??
SOFFS 0.00000000000000 // Item start offset
PLAYRATE 1.00000000000000 1 0.00000000000000 -1 // Playrate settings
// field 1, float, playrate
// field 2, int, preserve pitch while changing rate, 0 - no, 1 - yes
// 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
// 0 - normal
// 1 - reverse stereo
// 2 - mono (downmix)
// 3 - mono (left)
// 4 - mono (right)
GUID {4EB7779B-D570-4CCF-8739-161D2D32C154} // ignore, generated nicely by REAPER
<SOURCE SECTION // Source section start
LENGTH 0.00000000000000 // Source/item/take length
MODE 3 // Mode ??
STARTPOS 0.00000000000000 // Take start position (in seconds)
OVERLAP 0.01000000000000 // Take overlap (in seconds)
<SOURCE WAVE FILE "C:Path\To\AudioFile.wav" // Take source file
>
> // Source section end
TAKE SEL // This marks active take and shows up only in active take
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, ??
SOFFS 0.00000000000000 // Item start offset
PLAYRATE 1.00000000000000 1 0.00000000000000 -1 // see PLAYRATE above
CHANMODE 1 // see CHANMODE above
GUID {4EB7779B-D570-4CCF-8739-161D2D32C154} // ignore, generated nicely by REAPER
<SOURCE WAVE // Take source filename
FILE "C:\Full\Path\To\AudioFile reversed.wav"
> // Source section end
> // Item section end
Midi Item State Chunk
<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
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
> // 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 16k
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
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
