Clip Module: Dictionary Registry + Notes/Warp Markers/Views/All Properties

[PhotonicVelocity]

Summary

This PR depends on PR‑182 and uses the same dictionary‑based registry refactor described there. Suggest closing that first to reduce the diff of this PR. It applies that structure to clip.py, expanding clip coverage across notes, warp markers, time conversion, and view APIs, and adds a comprehensive test suite in tests/test_clip.py. It also adds support for arrangement clips. The README table has been split into logical groups so it's not such a large single table.

Endpoint Updates

All methods and properties are located at both /live/clip/ and /live/arrangement_clip

Methods

• New Endpoints:
  • Playback / Transport: set/fire_button, scrub, stop/scrub, move/playing_pos, crop, duplicate/loop, quantize, quantize/pitch
  • Warp / Time Conversion: add/warp_marker, move/warp_marker, remove/warp_marker, convert/time
  • Notes: add/notes, get/notes, get/selected_notes, replace/notes, replace/selected_notes, remove/notes, remove/selected_notes, duplicate/all_notes, duplicate/selected_notes, duplicate/region, select/notes, deselect/notes, convert/note_number_to_name
  • Clip.View: view/hide/envelope, view/show/envelope, view/show/loop
• Removed Endpoints:
  • remove_notes_by_id - This was not exposed in the README, and was not valid considering that AbletonOSC does not return the note_id field from MidiNote objects.
• Kept for Backwards Compatibility:
  • duplicate_loop - Only duplicate/loop kept in README going forward

Properties

• Custom getters for serialization of notes and warp_markers
• Listener-only loop_jump and playing_status handled via listen: "bang"
• New Endpoints:
  • get: available_warp_modes, is_arrangement_clip, is_session_clip, is_take_lane_clip, sample_rate
  • get / set: is_playing, view/grid_quantization, view/grid_is_triplet
  • get / listen: notes, has_envelopes, warp_markers
  • get / set / listen: signature_denominator, signature_numerator
  • listen only: loop_jump, playing_status
• Removed Endpoints:
  • Removed invalid listeners for: gain_display_string, has_groove, is_audio_clip, is_midi_clip, is_playing, is_triggered, length, sample_length, will_record_on_start

Notes API strategy

• Background:
  • With Live 11.0, notes were changed from a 5-field tuple format to the MidiNote object with note_id, probability, velocity_deviation, release_velocity. With that they also released new API methods (often with _extended suffixes), but the naming is all over the place. Use of the old methods causes an “older process” popup in Live warning about the use of old functions that may lose this data.
  • The current release of AbletonOSC supports add/notes, get/notes, remove/notes. It internally uses the new MidiNote-based methods (which avoids the popup), but still uses 5-field input/output for add/get. The pitch/time filters are based on the input order of the new get_notes_extended and remove_notes_extended.
• Strategy for this update
  • Standardize naming of endpoints with verb/object pattern.
    • Verbs: add, get, replace, remove, duplicate, select, deselect
    • Objects: notes, selected_notes
      • verb/notes generally accepts no input to mean "all".
        • e.g. get/notes () == "get all notes"
    • duplicate breaks this pattern slightly due to differing input shapes:
      • region has inputs: from_time, time_span, [destination_time], [pitch], [transposition]
      • all_notes has inputs: [destination_time], [transposition]
        • destination_time defaults to -1 (place at end of time_span)
        • pitch defaults to -1 (no pitch filter)
        • transposition defaults to 0
  • Keep the public API as 5‑field tuples (pitch, start, duration, velocity, mute)
  • Internally use extended Live APIs to avoid the Live 11 “older process” popup
  • Emit a warning when extended note attributes are detected but are not returned or will be discarded.
  • Directly use Live API methods where possible, otherwise use multiple methods internally.
    • e.g. For deselect/notes(from_pitch, pitch_span, from_time, time_span), Live API only has a deselect_all_notes endpoint.
      • Get the current set of selected note ids: selected_ids = get_selected_notes_extended()[note_id]
      • Get the note ids to deselect based on the input: deselect_ids = get_notes_extended(from_pitch, pitch_span, from_time, time_span)[note_id]
      • Calculate new selection id set: select_ids = selected_ids - deselect_ids
      • Deselect all notes: deselect_all_notes
      • Select the new set of ids: select_notes_by_id(select_ids)
  • ID‑based endpoints cannot be exposed for now, as AbletonOSC does not give or recieve note_id to the user.

ClipViewHandler

A dedicated ClipViewHandler was added to isolate Clip.View endpoints. This keeps the endpoint verb structure clean (/live/clip/view/get/prop vs /live/clip/get/view/prop). manager.py and __init__.py are updated to support this.

Tests

• Updated tests/test_clip.py to cover:
  • Playback controls (fire/stop/scrub/move/duplicate/quantize)
  • Notes API (add/get/replace/remove/select/deselect/duplicate)
  • Warp markers (add/move/remove/listen)
  • Time conversion (convert/time) and note naming (convert/note_number_to_name)
  • Getting/setting/listening on all properties
  • Clip view actions and grid properties
• Uses the silent_audio_file fixture (from PR‑182) for audio clip tests
• Cleanup is handled via try/finally to avoid leaving clips/listeners around

Known limitations / deferred items

• Object‑returning properties (e.g., canonical_parent, automation_envelopes, groove) remain disabled for now as these return objects.
• ID‑based note endpoints are deferred until a full extended‑note API is supported
  • Need to decide how to expose the full extended attribute notes while keeping the current functions backwards-compatible and easily allowing users to update to the new format. Maybe an /extended addition to the endpoints?
  • duplicate_notes_by_id will be particularly tricky as the list of note ids is variable length, and the destination_time / transposition inputs are optional.

---

Checklist

• The title is descriptive and summarises the new changes
• The code and any comments are consistent with the current code style
• For any new or modified API endpoints, I have added appropriate documentation to README.md
• For any new or modified API endpoints, I have added unit tests covering the new functionality
• I have verified that all unit tests pass (see CONTRIBUTING.md for guidance)