Change a project's song
r3_song_updateChange a project's Song with small typed changes, or make a new Song (create). The changes are applied in order and kept as ONE change (one undo step, every open R3 tab shows it): ops: setSong, setSections, setMaster, addTrack, setTrack, removeTrack, setClips, addClip, moveClip, removeClip, setLane, removeLane, addPoint, setPoint, removePoint, setChain, setEffect, addModulator, removeModulator, insertBars, splitClip, transposeClip, setClipGain. Tracks are named by their id ("kick"), sources by entityRef (a Pattern, DrumGrid, Beat, Audio or AudioPositional), clips and lane points by their index as r3_song_read lists them, positions in bars (bar 0 = the start). Examples: {"op": "moveClip", "track": "hats", "clip": 0, "start": 6}; {"op": "setLane", "track": "master", "target": "lp.frequency", "points": [{"bar": 0, "value": 350, "curve": "exp"}, {"bar": 12, "value": 1200}]}; {"op": "insertBars", "at": 64, "count": 8} (moves everything from bar 64 on 8 bars later); one eighth of a clip a few semitones higher, its length kept: {"op": "splitClip", "track": "bass", "clip": 0, "at": 65}, {"op": "splitClip", "track": "bass", "clip": 1, "at": 65.125}, {"op": "transposeClip", "track": "bass", "clip": 1, "semitones": 2} (whole semitones -24..24; a Sound Studio sound is rendered again from its public recipe, another file pitch-shifted, a Pattern's synth notes moved; 0 takes it off); that clip quieter (a clip's Volume in dB, -24..12, on top of its track's; 0 takes it off): {"op": "setClipGain", "track": "bass", "clip": 1, "gain": -4}. A song is version-checked, never merged: changing one needs baseVersion, the songVersion r3_song_read answered; if someone changed it since, the write is refused with the current version. A new Song (create) needs none. Every result is checked by lib-r3's song schema (SONGS.md) before anything is kept. How-to: HOWTO_SONG.md.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"projectId": "<projectId>"
},
"name": "r3_song_update"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| song | No | The Song's entityRef; leave it out when the project has one song. | |
| create | No | Make a NEW Song (wired to the project's Transport), then apply changes to it, e.g. {"name": "Main song"}. | |
| changes | No | The changes, in order: [{"op": "setTrack", "track": "kick", "gain": -3}, …]. Required unless create. | |
| projectId | Yes | The project, from r3_project_list. | |
| baseVersion | No | REQUIRED to change a song: its songVersion from r3_song_read. Leave it out with create. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| seq | No | ||
| name | Yes | ||
| parts | Yes | ||
| action | Yes | ||
| answer | Yes | This answer in words: what was done, what R3 measured, decided or refused, and what to do next. The same text as the result's text block. Read it: the fields beside it are the data, this is the guidance. | |
| changed | Yes | ||
| summary | Yes | ||
| warnings | No | ||
| entityRef | Yes | ||
| projectId | Yes | ||
| componentId | Yes | ||
| songVersion | Yes |