Songs, MCP: markers of a song (#338)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

MCP.md

@@ -167,7 +167,7 @@ for an area or for command names asked for.
 | tiles | `add_tile_picture`, `remove_tile_picture`, `move_tile_picture`, `paint_tiles`, `add_tilemap_layer`, `duplicate_tilemap_layer`, `remove_tilemap_layer`, `move_tilemap_layer`, `set_tilemap_layer`, `resize_placed_tilemap` |
 | pixelart | `paint_pixels`, `add_pixel_layer`, `duplicate_pixel_layer`, `remove_pixel_layer`, `set_pixel_layer`, `move_pixel_layer`, `merge_pixel_layer_down`, `add_pixel_frame`, `remove_pixel_frame`, `move_pixel_frame`, `resize_pixel_canvas`, `set_palette_colors`, `remove_palette_color` |
 | vectorart | `add_vector_shape`, `set_vector_shape_outline`, `set_vector_shape_style`, `transform_vector_shapes`, `duplicate_vector_shape`, `remove_vector_shapes`, `combine_vector_shapes`, `rename_vector_shape`, `order_vector_shape`, `move_vector_shapes`, `group_vector_shapes`, `ungroup_vector_shapes`, `add_vector_layer`, `remove_vector_layer`, `move_vector_layer`, `set_vector_layer` |
-| music | `add_notes`, `change_notes`, `remove_notes`, `set_loop`, `apply_preset`, `add_song_track`, `change_song_track`, `move_song_track`, `remove_song_track`, `set_song_lane`, `add_song_item`, `change_song_item`, `remove_song_items`, `set_send`, `add_clip`, `change_clip`, `remove_clip` |
+| music | `add_notes`, `change_notes`, `remove_notes`, `set_loop`, `apply_preset`, `add_song_track`, `change_song_track`, `move_song_track`, `remove_song_track`, `set_song_lane`, `add_song_marker`, `change_song_marker`, `remove_song_marker`, `add_song_item`, `change_song_item`, `remove_song_items`, `set_send`, `add_clip`, `change_clip`, `remove_clip` |
 | composition | `add_composition_track`, `change_composition_track`, `move_composition_track`, `remove_composition_track`, `add_composition_item`, `change_composition_item`, `remove_composition_items`, `add_composition_clip`, `change_composition_clip` |
 | project | `rename_project`, `set_layer_names`, `set_play_from`, `set_while_playing`, `set_game_link_zoom`, `set_symbol_scale`, `set_master_volume`, `set_master_fx` |
 
@@ -209,6 +209,9 @@ from the inspector.
   not there are refused. `points: []` takes the lane of the volume or the pan away. A parameter lane
   is only made for a parameter something on the track has (`params` in `get_asset`); without `min`
   and `max` it gets the range the Song tab would offer, round the default. `remove` takes it away.
+- **Markers of a song** (#338): `add_song_marker` puts one on a tick (named *Marker n* without a
+  name) and gives its id, `change_song_marker` renames or moves it, `remove_song_marker` takes it
+  away. A blank name is refused. `get_asset` lists them under `markers`, in the order of their ticks.
 Not for the agent, on purpose: uploading a file (it takes one the server holds), pasting needs the
 clipboard (the agent builds directly instead), and switching a plugin on would run its code.
 

Songs.md

@@ -8,7 +8,7 @@ Songs are listed under **Songs** in the asset panel. A new song has one empty tr
 
 ## What a song says
 
-The tracks, the items and the loop are the song's own data; everything else is a row in the
+The tracks, the items, the loop and the [markers](#markers) are the song's own data; everything else is a row in the
 inspector.
 
 | Row | What it does |
@@ -60,7 +60,7 @@ the right: it starts that far before the end of a round.
 Down the left are the **heads** of the tracks: the name, **FX** (the track's sound FX, blue when it
 has one; its menu can also make [one of its own](#a-sound-fx-of-its-own)), **M** (mute, orange when on) and **S** (solo, yellow when on), below them the volume (the line marks 0 dB) and the pan (the line marks the
 middle), and up the right edge the track's [level meter](#levels-and-clipping). A track is added from the right-click menu of a head, above or below it. Along the top is the **ruler**, as in the
-Pattern tab. Left of it, above the heads, is **Out**, the meter of the whole song. Between them are the **lanes** with the items: a pattern blue with its notes drawn
+Pattern tab, and under it the strip of the [markers](#markers). Left of them, above the heads, is **Out**, the meter of the whole song. Between them are the **lanes** with the items: a pattern blue with its notes drawn
 small, every round it plays; a sound green with its waveform, from where it starts in it, every
 round drawn alike (each column shows the loudest part of what it covers). An item
 longer than what it plays has a white line with a small notch where it starts over, one for every
@@ -121,7 +121,28 @@ where playing starts, a drag on the loop strip along its top sets the loop, a ri
 after its last item, and at least one bar. An empty song is a single bar long, so **Fit** shows that
 one bar across; the wheel takes the view out to lay items further on.
 
-The wheel zooms and does nothing else: over the lanes or the ruler the time about the pointer, over
+### Markers
+
+A **marker** (#338) is a named spot on the song's time, on a whole tick. Markers lie on a strip of
+their own under the ruler: a green flag with the name beside it, as much of the name as there is
+room for before the next marker, and a faint green line down the tracks. Resting the pointer on a
+marker shows its whole name. Two markers may share a tick and a name; a marker is known by its id.
+They change nothing that is heard and are not in a [bake's](#baking) print.
+
+| Do this on the strip | And this happens |
+|---|---|
+| Double-click an empty spot | A marker there, on the grid line nearest the pointer (with `Alt` or `Shift` on the tick), named *Marker 1*, *Marker 2* and so on by the first number not taken. |
+| Right-click an empty spot | *Add marker*, the same. |
+| Drag a marker | It moves along the grid, with `Alt` or `Shift` on the tick. One undo step. |
+| Click a marker | Playing starts there, as a click on the ruler would set it. |
+| Double-click a marker | A dialog names it. |
+| Right-click a marker | *Play from here*, *Rename…*, *Delete marker*. |
+
+In a game, markers are what *On song marker* and a switch to a song at a marker will aim at (#338,
+still to come). The agent sets them with `add_song_marker`, `change_song_marker` and
+`remove_song_marker`; `get_asset` lists them under `markers`.
+
+The wheel zooms and does nothing else: over the lanes, the ruler or the markers the time about the pointer, over
 the heads the height of the tracks (28 to 320 px), about the track under the pointer. The time zooms
 in eight times as far as in the Pattern tab, to 3840 px a quarter, so a take can be laid down to
 the millisecond. A middle-drag pans both ways, and as in the Pattern tab it can take bar 1 up to
@@ -491,7 +512,7 @@ bus. Stop let it go. An item's *Sound FX* offered *From the asset*, *None* and t
 
 A link sends at one volume; it cannot be moved over time. Nothing tells a graph that a song played
 once has ended (#373), and there is no node that changes the volume of a playing song or the value
-of a lane while it plays. No start at a marker (#338), no automation of the tempo and none in a
+of a lane while it plays. Markers do nothing in a game yet: the events, a switch at a marker and the other links between a game and its music are on their way with #338. No automation of the tempo and none in a
 pattern (#337 left both out), no swing (#372), no song inside a song, no held note (drone) as
 an item. A variation of a pattern for one item is *Embed a copy* in the item's menu (see
 [Embedded assets](#embedded-assets)). A song cannot keep an instrument to itself.