Module item
Provide implementation for Item functions.
Info:
- License: MIT
- Author: Nomad Monad
| Item:add_take () |
Add Take. |
| Item:count_takes () |
Count Takes. |
| Item:get_active_take () |
Get Active Take. |
| Item:get_displayed_color () |
Get Displayed Color. |
| Item:get_displayed_color2 () |
Get Displayed Color2. |
| Item:get_project_context () |
Get Item Project Context. |
| Item:get_state_chunk (str, is_undo) |
Get Item State Chunk. |
| Item:get_track () |
Get Track. |
| Item:get_info_value (param_name) |
Get Info Value. |
| Item:get_num_takes () |
Get Num Takes. |
| Item:get_take (tk) |
Get Take. |
| Item:get_set_info_string (param_name, info, set_value) |
Get Set Info String. |
| Item:is_selected () |
Is Selected. |
| Item:descends_from_track () |
Descends From Track. |
| Item:midi_set_item_extents (start_qn, end_qn) |
Midi Set Item Extents. |
| Item:move_to_track (dest_track) |
Move To Track. |
| Item:set_item_state_chunk (str, is_undo) |
Set Item State Chunk. |
| Item:set_info_value (param_name, new_value) |
Set Info Value. |
| Item:set_length_seconds (length, refresh_ui) |
Set Length in seconds. |
| Item:set_position_seconds (position, refresh_ui) |
Set Position in seconds. |
| Item:set_selected (selected) |
Set Selected. |
| Item:split (position) |
Split. |
| Item:update_item_in_project () |
Update Item In Project. |
| Item:get_guid () |
Get Guid. |
| Item:get_image_resource () |
Get Image Resource. |
| Item:set_item_edges (start_time, end_time) |
Set Item Edges. |
| Item:set_image_resource (image_in, image_flags) |
Set Image Resource. |
| Item:analyze_peak_and_rms (win_size, peaks, peaks_pos, rms, rms_pos) |
Analyze Peak And Rms. |
| Item:delete_take_from_item (take_idx) |
Delete Take From Item. |
| Item:get_average_rms () |
Get Average Rms. |
| Item:get_max_peak () |
Get Max Peak. |
| Item:get_max_peak_and_max_peak_pos () |
Get Max Peak And Max Peak Pos. |
| Item:get_peak_rms_non_windowed () |
Get Peak Rms Non Windowed. |
| Item:get_peak_rms_windowed () |
Get Peak Rms Windowed. |
| Item:get_set_source_state (take_idx, state, new_value) |
Get Set Source State. |
-
Item:new (item)
-
Create new Item instance.
Parameters:
- item
userdata The pointer to Reaper MediaItem*
Returns:
table Item instance
-
Item:log (...)
-
Log messages with the Item logger.
Parameters:
- ...
(varargs) Messages to log.
-
Item:__tostring ()
-
String representation of the Item instance.
Returns:
string
-
Item:get_takes ()
-
Get all takes.
Returns:
table array
-
Item:iter_takes ()
-
Iterate over takes.
Returns:
function iterator
-
Item:has_takes ()
-
Whether there is at least one take in the item.
Returns:
boolean
-
Item:set_length_beats (length, refresh_ui)
-
Set Length in Beats.
Redraws the screen only if refreshUI == true.
Parameters:
- length
number Length in beats.
- refresh_ui
boolean Optional (default true).
Returns:
boolean
-
Item:set_position_beats (position, refresh_ui)
-
Set Position in Beats.
Redraws the screen only if refreshUI == true.
Parameters:
- position
number Position in beats.
- refresh_ui
boolean Optional (default true).
Returns:
boolean
-
Item:add_take ()
-
Add Take. Wraps AddTakeToMediaItem.
creates a new take in an item
Returns:
table Take instance
-
Item:count_takes ()
-
Count Takes. Wraps CountTakes.
count the number of takes in the item
Returns:
number
-
Item:get_active_take ()
-
Get Active Take. Wraps GetActiveTake.
get the active take in this item
Returns:
table Take instance
-
Item:get_displayed_color ()
-
Get Displayed Color. Wraps GetDisplayedMediaItemColor.
Returns:
number
See also:
-
Item:get_displayed_color2 ()
-
Get Displayed Color2. Wraps GetDisplayedMediaItemColor2.
Returns the custom take, item, or track color that is used (according to the
user preference) to color the media item. The returned color is OS
dependent|0x01000000 (i.e. ColorToNative(r,g,b)|0x01000000), so a return of zero
means "no color", not black.
Returns:
number
See also:
-
Item:get_project_context ()
-
Get Item Project Context. Wraps GetItemProjectContext.
Returns:
table Project instance
-
Item:get_state_chunk (str, is_undo)
-
Get Item State Chunk. Wraps GetItemStateChunk.
Gets the RPPXML state of an item, returns true if successful. Undo flag is a
performance/caching hint.
Parameters:
- str
string
- is_undo
boolean
Returns:
string
-
Item:get_track ()
-
Get Track. Wraps GetMediaItem_Track.
Get parent track of media item
Returns:
table Track object
-
Item:get_info_value (param_name)
-
Get Info Value. Wraps GetMediaItemInfo_Value.
Get media item numerical-value attributes.
Parameters:
- param_name
string Item.GetInfoValueConstants
Returns:
number
See also:
-
Item:get_num_takes ()
-
Get Num Takes. Wraps GetMediaItemNumTakes.
Returns:
number
-
Item:get_take (tk)
-
Get Take. Wraps GetMediaItemTake.
Parameters:
Returns:
Take table
-
Item:get_set_info_string (param_name, info, set_value)
-
Get Set Info String. Wraps GetSetMediaItemInfo_String.
Gets/sets an item attribute string.
Parameters:
- param_name
string Item.GetSetInfoStringConstants
- info
string
- set_value
boolean Optional (default false)
Returns:
string info
See also:
-
Item:is_selected ()
-
Is Selected. Wraps IsMediaItemSelected.
Returns:
boolean
-
Item:descends_from_track ()
-
Descends From Track. Wraps MediaItemDescendsFromTrack.
Returns 1 if the track holds the item, 2 if the track is a folder containing the
track that holds the item, etc.
Returns:
number
-
Item:midi_set_item_extents (start_qn, end_qn)
-
Midi Set Item Extents. Wraps MIDI_SetItemExtents.
Set the start/end positions of a media item that contains a MIDI take.
Parameters:
- start_qn
number
- end_qn
number
Returns:
boolean
-
Item:move_to_track (dest_track)
-
Move To Track. Wraps MoveMediaItemToTrack.
Returns TRUE if move succeeded.
Parameters:
Returns:
boolean
-
Item:set_item_state_chunk (str, is_undo)
-
Set Item State Chunk. Wraps SetItemStateChunk.
Sets the RPPXML state of an item, returns true if successful. Undo flag is a
performance/caching hint.
Parameters:
- str
string
- is_undo
boolean
Returns:
boolean
-
Item:set_info_value (param_name, new_value)
-
Set Info Value. Wraps SetMediaItemInfo_Value.
Set media item numerical-value attributes.
Parameters:
- param_name
string Item.SetInfoValueConstants
- new_value
any
Returns:
boolean
See also:
-
Item:set_length_seconds (length, refresh_ui)
-
Set Length in seconds. Wraps SetMediaItemLength.
Redraws the screen only if refreshUI == true.
Parameters:
- length
number Length in seconds.
- refresh_ui
boolean Optional (default true)
Returns:
boolean
-
Item:set_position_seconds (position, refresh_ui)
-
Set Position in seconds. Wraps SetMediaItemPosition.
Redraws the screen only if refreshUI == true.
Parameters:
- position
number Position in seconds.
- refresh_ui
boolean Optional (default true).
Returns:
boolean
-
Item:set_selected (selected)
-
Set Selected. Wraps SetMediaItemSelected.
Parameters:
-
Item:split (position)
-
Split. Wraps SplitMediaItem.
the original item becomes the left-hand split, the function returns the right-
hand split (or NULL if the split failed)
Parameters:
Returns:
Item table
-
Item:update_item_in_project ()
-
Update Item In Project. Wraps UpdateItemInProject.
-
Item:get_guid ()
-
Get Guid. Wraps BR_GetMediaItemGUID.
[BR] Get media item GUID as a string (guidStringOut_sz should be at least 64).
To get media item back from GUID string, see BR_GetMediaItemByGUID.
Returns:
string guid_string
-
Item:get_image_resource ()
-
Get Image Resource. Wraps BR_GetMediaItemImageResource.
[BR] Get currently loaded image resource and its flags for a given item. Returns
false if there is no image resource set.
Returns:
-
string image
-
number image_flags
See also:
-
Item:set_item_edges (start_time, end_time)
-
Set Item Edges. Wraps BR_SetItemEdges.
[BR] Set item start and end edges' position - returns true in case of any
changes
Parameters:
- start_time
number
- end_time
number
Returns:
boolean
-
Item:set_image_resource (image_in, image_flags)
-
Set Image Resource. Wraps BR_SetMediaItemImageResource.
[BR] Set image resource and its flags for a given item. To clear current image
resource, pass imageIn as "". imageFlags: &1=0: don't display image, &1: center
/ tile, &3: stretch, &5: full height (REAPER 5.974+). Can also be used to
display existing text in empty items unstretched (pass imageIn = "", imageFlags
= 0) or stretched (pass imageIn = "". imageFlags = 3).
Parameters:
- image_in
string
- image_flags
number
See also:
-
Item:analyze_peak_and_rms (win_size, peaks, peaks_pos, rms, rms_pos)
-
Analyze Peak And Rms. Wraps NF_AnalyzeMediaItemPeakAndRMS.
This function combines all other NF_Peak/RMS functions in a single one and
additionally returns peak RMS positions. Lua example code here. Note: It's
recommended to use this function with ReaScript/Lua as it provides reaper.array
objects. If using this function with other scripting languages, you must provide
arrays in the reaper.array format.
Parameters:
- win_size
number
- peaks
userdata
- peaks_pos
userdata
- rms
userdata
- rms_pos
userdata
Returns:
boolean
-
Item:delete_take_from_item (take_idx)
-
Delete Take From Item. Wraps NF_DeleteTakeFromItem.
Deletes a take from an item. takeIdx is zero-based. Returns true on success.
Parameters:
Returns:
boolean
-
Item:get_average_rms ()
-
Get Average Rms. Wraps NF_GetMediaItemAverageRMS.
Returns the average overall (non-windowed) dB RMS level of active channels of an
audio item active take, post item gain, post take volume envelope, post-fade,
pre fader, pre item FX. Returns -150.0 if MIDI take or empty item.
Returns:
number
-
Item:get_max_peak ()
-
Get Max Peak. Wraps NF_GetMediaItemMaxPeak.
Returns the greatest max. peak value in dBFS of all active channels of an audio
item active take, post item gain, post take volume envelope, post-fade, pre
fader, pre item FX. Returns -150.0 if MIDI take or empty item.
Returns:
number
-
Item:get_max_peak_and_max_peak_pos ()
-
Get Max Peak And Max Peak Pos. Wraps NF_GetMediaItemMaxPeakAndMaxPeakPos.
Returns:
number max_peak_pos
See also:
-
Item:get_peak_rms_non_windowed ()
-
Get Peak Rms Non Windowed. Wraps NF_GetMediaItemPeakRMS_NonWindowed.
Returns the greatest overall (non-windowed) dB RMS peak level of all active
channels of an audio item active take, post item gain, post take volume
envelope, post-fade, pre fader, pre item FX. Returns -150.0 if MIDI take or
empty item.
Returns:
number
-
Item:get_peak_rms_windowed ()
-
Get Peak Rms Windowed. Wraps NF_GetMediaItemPeakRMS_Windowed.
Returns the average dB RMS peak level of all active channels of an audio item
active take, post item gain, post take volume envelope, post-fade, pre fader,
pre item FX. Obeys 'Window size for peak RMS' setting in 'SWS: Set RMS
analysis/normalize options' for calculation. Returns -150.0 if MIDI take or
empty item.
Returns:
number
-
Item:get_set_source_state (take_idx, state, new_value)
-
Get Set Source State. Wraps SNM_GetSetSourceState.
[S&M] Gets or sets a take source state. Returns false if failed. Use takeidx=-1
to get/alter the active take. Note: this function does not use a MediaItem_Take*
param in order to manage empty takes (i.e. takes with MediaItem_Take*==NULL),
see SNM_GetSetSourceState2.
Parameters:
- take_idx
number
- state
userdata
- new_value
boolean
Returns:
boolean
-
Item.GetInfoValueConstants
-
Constants for Item:get_info_value.
Fields:
- B_MUTE
boolean: muted (item solo overrides). setting this value will clear C_MUTE_SOLO.
- B_MUTE_ACTUAL
boolean: muted (ignores solo). setting this value will not affect C_MUTE_SOLO.
- C_LANEPLAYS
string: on fixed lane tracks, 0=this item lane does not play, 1=this item lane plays exclusively, 2=this item lane plays and other lanes also play, -1=this item is on a non-visible, non-playing lane on a formerly fixed-lane track (read-only)
- C_MUTE_SOLO
string: solo override (-1=soloed, 0=no override, 1=unsoloed). note that this API does not automatically unsolo other items when soloing (nor clear the unsolos when clearing the last soloed item), it must be done by the caller via action or via this API.
- B_LOOPSRC
boolean: loop source
- B_ALLTAKESPLAY
boolean: all takes play
- B_UISEL
boolean: selected in arrange view
- C_BEATATTACHMODE
string: char *item timebase, -1=track or project default, 1=beats (position, length, rate), 2=beats (position only). for auto-stretch timebaseC_BEATATTACHMODE=1, C_AUTOSTRETCH=1
- C_AUTOSTRETCH
string: auto-stretch at project tempo changes, 1=enabled, requires C_BEATATTACHMODE=1
- C_LOCK
string: locked, &1=locked
- D_VOL
number: item volume, 0=-inf, 0.5=-6dB, 1=+0dB, 2=+6dB, etc
- D_POSITION
number: item position in seconds
- D_LENGTH
number: item length in seconds
- D_SNAPOFFSET
number: item snap offset in seconds
- D_FADEINLEN
number: item manual fadein length in seconds
- D_FADEOUTLEN
number: item manual fadeout length in seconds
- D_FADEINDIR
number: item fadein curvature, -1..1
- D_FADEOUTDIR
number: item fadeout curvature, -1..1
- D_FADEINLEN_AUTO
number: item auto-fadein length in seconds, -1=no auto-fadein
- D_FADEOUTLEN_AUTO
number: item auto-fadeout length in seconds, -1=no auto-fadeout
- C_FADEINSHAPE
number: fadein shape, 0..6, 0=linear
- C_FADEOUTSHAPE
number: fadeout shape, 0..6, 0=linear
- I_GROUPID
number: group ID, 0=no group
- I_LASTY
number: Y-position (relative to top of track) in pixels (read-only)
- I_LASTH
number: height in pixels (read-only)
- I_CUSTOMCOLOR
number: custom color, OS dependent color|0x1000000 (i.e. ColorToNative(r,g,b)|0x1000000). If you do not |0x1000000, then it will not be used, but will store the color
- I_CURTAKE
number: active take number
- IP_ITEMNUMBER
number: item number on this track (read-only, returns the item number directly)
- F_FREEMODE_Y
float *: free item positioning or fixed lane Y-position. 0=top of track, 1.0=bottom of track
- F_FREEMODE_H
float *: free item positioning or fixed lane height. 0.5=half the track height, 1.0=full track height
- I_FIXEDLANE
number: fixed lane of item (fine to call with setNewValue, but returned value is read-only)
- B_FIXEDLANE_HIDDEN
boolean: true if displaying only one fixed lane and this item is in a different lane (read-only)
- P_TRACK
userdata: (read-only)
-
Item.GetSetInfoStringConstants
-
Constants for Item:get_set_info_string.
Fields:
- P_NOTES
string: item note text (do not write to returned pointer, use setNewValue to update)
- P_EXT
xyz: xyzchar *extension-specific persistent data
- GUID
GUID *: 16-byte GUID, can query or update. If using a _String() function, GUID is a string {xyz-...}.
-
Item.SetInfoValueConstants
-
Constants for Item:set_info_value.
Fields:
- B_MUTE
boolean: muted (item solo overrides). setting this value will clear C_MUTE_SOLO.
- B_MUTE_ACTUAL
boolean: muted (ignores solo). setting this value will not affect C_MUTE_SOLO.
- C_LANEPLAYS
string: on fixed lane tracks, 0=this item lane does not play, 1=this item lane plays exclusively, 2=this item lane plays and other lanes also play, -1=this item is on a non-visible, non-playing lane on a formerly fixed-lane track (read-only)
- C_MUTE_SOLO
string: solo override (-1=soloed, 0=no override, 1=unsoloed). note that this API does not automatically unsolo other items when soloing (nor clear the unsolos when clearing the last soloed item), it must be done by the caller via action or via this API.
- B_LOOPSRC
boolean: loop source
- B_ALLTAKESPLAY
boolean: all takes play
- B_UISEL
boolean: selected in arrange view
- C_BEATATTACHMODE
string: char *item timebase, -1=track or project default, 1=beats (position, length, rate), 2=beats (position only). for auto-stretch timebaseC_BEATATTACHMODE=1, C_AUTOSTRETCH=1
- C_AUTOSTRETCH
string: auto-stretch at project tempo changes, 1=enabled, requires C_BEATATTACHMODE=1
- C_LOCK
string: locked, &1=locked
- D_VOL
number: item volume, 0=-inf, 0.5=-6dB, 1=+0dB, 2=+6dB, etc
- D_POSITION
number: item position in seconds
- D_LENGTH
number: item length in seconds
- D_SNAPOFFSET
number: item snap offset in seconds
- D_FADEINLEN
number: item manual fadein length in seconds
- D_FADEOUTLEN
number: item manual fadeout length in seconds
- D_FADEINDIR
number: item fadein curvature, -1..1
- D_FADEOUTDIR
number: item fadeout curvature, -1..1
- D_FADEINLEN_AUTO
number: item auto-fadein length in seconds, -1=no auto-fadein
- D_FADEOUTLEN_AUTO
number: item auto-fadeout length in seconds, -1=no auto-fadeout
- C_FADEINSHAPE
number: fadein shape, 0..6, 0=linear
- C_FADEOUTSHAPE
number: fadeout shape, 0..6, 0=linear
- I_GROUPID
number: group ID, 0=no group
- I_LASTY
number: Y-position (relative to top of track) in pixels (read-only)
- I_LASTH
number: height in pixels (read-only)
- I_CUSTOMCOLOR
number: custom color, OS dependent color|0x1000000 (i.e. ColorToNative(r,g,b)|0x1000000). If you do not |0x1000000, then it will not be used, but will store the color
- I_CURTAKE
number: active take number
- IP_ITEMNUMBER
number: item number on this track (read-only, returns the item number directly)
- F_FREEMODE_Y
float *: free item positioning or fixed lane Y-position. 0=top of track, 1.0=bottom of track
- F_FREEMODE_H
float *: free item positioning or fixed lane height. 0.5=half the track height, 1.0=full track height
- I_FIXEDLANE
number: fixed lane of item (fine to call with setNewValue, but returned value is read-only)
- B_FIXEDLANE_HIDDEN
boolean: true if displaying only one fixed lane and this item is in a different lane (read-only)