Add consolidated Browser API — supersedes #183/#191/#192/#194/#200#204
Add consolidated Browser API — supersedes #183/#191/#192/#194/#200#204esaruoho wants to merge 3 commits into
Conversation
Consolidates five competing open Browser API PRs (ideoforms#183, ideoforms#191, ideoforms#192, ideoforms#194, ideoforms#200) into a single handler exposing 30 endpoints across six categories: load-by-name, load-by-target, load-by-query, defaults, discovery, and preview/hotswap/utility. Based on PR ideoforms#194 (@bimsonz) which already absorbed ideoforms#183 / ideoforms#191 / ideoforms#192, with two additions: - load_by_query / load_from_category from PR ideoforms#200 (@keshav55) — search-based loading that doesn't require an exact name match - load_default_instrument / load_default_audio_effect / load_default_midi_effect from PR ideoforms#183 (@christopherwxyz) — convenience one-shots for "give me a working device on this track" All five contributors credited as Co-authored-by. Co-authored-by: Zach Bimson <bimsonz@users.noreply.github.com> Co-authored-by: Keshav Rao <keshav55@users.noreply.github.com> Co-authored-by: christopherwxyz <christopherwxyz@users.noreply.github.com> Co-authored-by: Dandiggas <Dandiggas@users.noreply.github.com> Co-authored-by: keepyourpolicy-lab <keepyourpolicy-lab@users.noreply.github.com>
|
|
|
Oooh thanks @esaruoho, this is great and much appreciated as it has been daunting to approach all of these PRs. I am still unfortunately totally backlogged on another project which I'm working on around the clock, but this consolidation massively helps simplify the workload! Main question: My #1 priority within this whole API is to make it as consistent as possible with the Live Object Model and Live's internal APIs in general. Can you confirm that the function calls (load_instrument, etc) are all the same as within the LOM? Secondly, a few unit tests would be essential to get this merged. Could there be unit tests that just operate on core Live instruments/audio effects (things that are included within Live standard - e.g. Simpler, Drift), to add an instrument to a track, check that it appears OK when querying the track's devices property, change a parameter of the device, and then remove it? And then same for adding/querying/changing/deleting an effect? I will then be happy to give this a check over and merge so that we can get this all all into the core! Thanks again, I appreciate it. |
Three tests in tests/test_browser.py covering Daniel's review request:
- test_browser_load_instrument_lifecycle: loads Simpler onto a MIDI
track (track 0), confirms it appears in /live/track/get/devices/name,
toggles parameter 0 ("Device On") via /live/device/set/parameter/value
and reads it back, restores the original value, then deletes the
device and asserts the track is empty again.
- test_browser_load_audio_effect_lifecycle: same shape but loads
Reverb onto an audio track (track 2).
- test_browser_get_categories: smoke test that
/live/browser/get/categories returns a non-empty tuple containing
at least instruments, audio_effects, midi_effects.
Simpler and Reverb were chosen because they ship with every standard
Live install (Intro included), so the tests don't depend on Live 12 or
on Suite-only content. An autouse fixture clears devices from tracks 0
and 2 before and after each test so a failed run can't pollute the
fixture state used by other test modules.
|
Thanks Daniel! Tests just pushed to this branch —
I picked Simpler + Reverb (rather than Drift, which Live 11 doesn't have) so the tests run on every supported Live version. An autouse fixture wipes devices from tracks 0 and 2 before and after each test, so a failure can't pollute the shared fixture state used by other test modules. On LOM consistency — honest answer: the underlying calls are LOM-faithful, but the endpoint names are convenience wrappers, not direct LOM mirrors. Specifically:
So If you'd prefer LOM-strict naming, two options:
Happy to do either. My weak preference is to keep the convenience layer (it makes the API more discoverable from a client perspective and matches how Live's UI presents the browser), but I'm not married to it — the consistency argument is real, and you're the one who'll be reviewing every future PR against this surface. Let me know which direction you'd like and I'll refactor. |
Open-PR punch list (as of 2026-05-21)Posting this here as a triage map. 26 open PRs total. Grouped by what's needed next — feel free to use this as a checklist when bandwidth returns. 🟢 Ready to merge once reviewed (no author work needed)These are the four consolidation PRs I opened in this batch. Each one supersedes a cluster and credits all original authors as
🔴 Closeable as consolidated (if you merge the corresponding 🟢 PR above)
🟡 Needs author response (you've already reviewed)These are stuck because the original author hasn't come back to address your feedback. May be worth nudging or assuming abandoned.
If @ltackett doesn't come back, the #153 change is 11 lines — I'm happy to open a tiny follow-up that does the namespace move and closes #153. 🟦 Fresh focused feature PRs (no overlap, ready for first review)These are all by @bimsonz from his April push. Each adds a distinct surface that doesn't conflict with anything else open or with the consolidations above.
These are the next-after-consolidations candidates. They share style with #204/#205/#206 and are sized for a single review pass. 🟧 Chain/Rack cluster — second consolidation opportunitySimilar to the browser pattern: two PRs covering overlapping territory.
If you'd like me to consolidate these the same way as the browser cluster, I can. Lower confidence than the browser one because chain semantics are recursive (chains-of-chains) and the surface area is bigger. 🟪 Likely abandoned (consider closing with a polite note)
⚫ Big architectural refactors — needs your direction before anyone touches themThese three are interdependent (#185 + #186 depend on #182's registry pattern) and are massive enough that they probably warrant a project-direction conversation rather than a normal PR review.
I would NOT touch these without your explicit direction. If you want to keep the current property-list-based pattern, all three can be closed. If you want to move to the dictionary-registry pattern, they need to be merged together (or rebuilt from scratch given how stale the diffs are now). Net effect if 🟢 PRs merge and 🔴 PRs close: 26 open → 13 open. Half the backlog cleared with four merges + ten closures. Happy to continue this work in whatever order suits — say the word on the chain cluster, the scroll_view nudge, or PhotonicVelocity direction and I'll start. No urgency on your side. |
Pre-flight cleanup spotted while auditing the PR.
|
Hi @esaruoho — thanks for the great triage work on this PR and the open-PR punch list! Small correction on the entry for #167 in the 🟡 "Needs author response" section: the three items listed (remove So #167 is in the same shape as your 🟢 group from the author's side — it's been waiting on a final review pass, not on author work. Posted a detailed status update over on #167 with the current state. Happy to defer to whatever order makes sense for the maintainer — just wanted to flag the misclassification so it doesn't sit in the wrong bucket. Thanks again for the consolidation work! |
4 participants
Description
Consolidates five competing open Browser API PRs into a single handler. The five PRs (#183, #191, #192, #194, #200) all add overlapping
/live/browser/*endpoints but none of them has been merged — they've sat open for weeks/months while the maintainer reviews other work. This PR is an attempt to unblock that by reducing five reviews to one.The intent is: if this is mergeable, the other five can be closed as consolidated-here. If anything in here is the wrong call, please push back on this PR and I'll either fix it or close this and defer to the originals.
Source PRs being consolidated
load_default_instrument,load_default_audio_effect,load_default_midi_effectadapted into #194's style. Other endpoints either already in #194 or skipped to keep diff lean.load_to_slot,load_to_arrangement,preview).load_by_queryandload_from_categoryadapted into #194's style. Genuinely new functionality — search-based loading that doesn't require an exact name. Valuable for AI/MCP integrations.All five contributors credited as
Co-authored-byon the commit.Endpoint inventory (30 endpoints)
Load by name (10):
load_instrument,load_drum_kit,load_audio_effect,load_midi_effect,load_effect,load_sound,load_sample,load_plugin,load_max_device,load_user_presetLoad by target (2):
load_to_slot,load_to_arrangementLoad by query / category (2, from #200):
load_by_query,load_from_categoryDefaults (3, from #183):
load_default_instrument,load_default_audio_effect,load_default_midi_effectDiscovery (8):
get/categories,get/children,search,list_audio_effects,list_midi_effects,list_sounds,list_plugins,list_user_presetsPreview, hotswap, utility (5):
preview,stop_preview,refresh,hotswap_start,hotswap_loadFiles changed
abletonosc/browser.py— new, 693 lines (PR Add comprehensive browser API with 25 endpoints #194's body + two helper methods + five new endpoint functions + fiveadd_handlerregistrations)abletonosc/__init__.py—from .browser import BrowserHandlermanager.py—BrowserHandler(self)registration +importlib.reload(abletonosc.browser)README.md— new Browser API section, six sub-tables grouping the endpointsWhat I did NOT include and why
load_filefrom feat: Add Browser API support #192 — loads from an arbitrary filesystem path; mild security concern (lets any OSC client read files outside the User Library). Skipped, can be revisited.load_presetfrom Add browser API, chain management, and sidechain routing #191 — overlaps withload_user_presetalready in the spine.get_item_info,browse_path,list_samples,list_max_devices,list_clipsfrom Add comprehensive browser API for loading effects, sounds, samples, and navigation #183 — small individual value, would add ~150 lines for marginal gain. Easy to add in a follow-up.list_categories/list_childrenfrom feat(browser): add /live/browser/* handlers for loading presets via OSC #200 — naming conflicts with Add comprehensive browser API with 25 endpoints #194'sget/categories/get/children(same semantics). Kept Add comprehensive browser API with 25 endpoints #194's naming for consistency with the rest of AbletonOSC'sget/*convention.On the meta — five competing PRs
This is the kind of pile-up that ages a repo. Daniel: if this consolidation works as a pattern, I'd be happy to do the same triage for other stalled clusters (e.g. the chain/master-return PRs around #170, #189, #170, #186, #197). Just say the word.
Checklist
get/categoriesis feasible; full coverage isn't. Happy to add a smoke test if you want one.