add_midi_note
Insert a MIDI note into a specific track and item in REAPER, with precise control over pitch, start position (time or measure), length, and velocity. Supports absolute or item-relative timing.
Instructions
Add a MIDI note to a MIDI item. Reaper format 2.1.00 should be converted to 2:1,000.
Important: Please check MIDI item length in which you want to add the note. If the note extends beyond the item bounds, create another one or resize existing before note adding. Double-check the item's starting position before adding it. Notes positioned before the item's position won't be added.
Item Identification - TWO ways to specify which item:
Using track_pos_idx (integer):
Pass the simple index number from create_midi_item response
Example: item=track_pos_idx=0 for first item, item=track_pos_idx=1 for second item
Fast and easy but may change if items are reordered
Using direct_item_id (string):
Pass the exact string ID from create_midi_item or get_items_in_time_range
Example: item=direct_item_id="MediaItem*0x000001234567890A"
Stable and reliable, won't change even if items move
The system automatically detects which type you're using.
Note about positioning:
start_time and start_measure specify ABSOLUTE position in the project timeline
The note will be placed at this absolute position, regardless of item location
Example: start_measure="5:1,000" means measure 5 in the project, not 5 measures into the item
Args: track_index: 0-based track index (0 = first track, 1 = second, etc.) Important: REAPER UI displays "Track 1" but API uses index 0. item: EITHER an integer track_pos_idx (0, 1, 2...) OR a string direct_item_id pitch: MIDI note pitch (0-127) start_time: ABSOLUTE start position in seconds in the project timeline (optional if start_measure is provided) start_measure: ABSOLUTE start position as "measure:beat,fraction" in the project timeline (optional if start_time is provided) length_time: Duration in seconds from note start (from start_time or start_measure)(optional if length_measure is provided) length_measure: Duration as "measure:beat,fraction" from note start (e.g., "0:2,000" = 2 beats from start_time or start_measure)(optional if length_time is provided). Also remember 2:0,0 is not end of 2 measure and 3:1,0 should be. velocity: Note velocity (0-127, default: 96) relative_start: If True, start_time/start_measure are interpreted as offsets from the item's start (i.e. relative to item.start). If False (default), they are treated as absolute project positions.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| item | Yes | ||
| pitch | Yes | ||
| velocity | No | ||
| start_time | No | ||
| length_time | No | ||
| track_index | Yes | ||
| start_measure | No | ||
| length_measure | No | ||
| relative_start | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |