Margrete
Client for a running Margrete RPC server.
This is the entry point of the Python client. Construct one to connect to a Margrete
instance, then call :meth:open_edit to make scriptable changes to the current
chart inside a transaction.
Functions
func__init__(self, endpoint=None, *, instance_id=None, timeout=60.0, transport=None, tracer=None) -> NoneConnect to a Margrete RPC server.
With no arguments the single running instance is auto-detected via discovery.
paramselfparamendpointstr | None= NoneExplicit host:port to connect to. Mutually exclusive with
instance_id and transport.
paraminstance_idstr | None= NoneConnect to the discovered instance with this id (see
:class:ServerStatus.instance_id). Mutually exclusive with endpoint.
paramtimeoutfloat= 60.0Socket timeout in seconds for requests. Discovery uses at most one second of this budget.
paramtransportRpcTransport | None= NonePre-built transport to use instead of opening a socket; intended
for testing. Cannot be combined with endpoint or instance_id.
paramtracerTracer | None= NoneOptional tracer for observability spans; defaults to a no-op.
Returns
Nonefuncping(self) -> NoneCheck connectivity by round-tripping an empty request to the server.
paramselfReturns
Nonefuncstatus(self) -> ServerStatusQuery the server for its identity and runtime status.
paramselfReturns
margrete_rpc.client.ServerStatusclass:ServerStatus snapshot (version, instance id, uptime, paths).
funcundo(self) -> boolUndo the last edit on the Margrete undo stack.
Note
Undo applies to Margrete's own history, which includes edits made through this Python client. Undoing a transaction that deleted notes can re-create them in a duplicated state, so prefer designing transactions that add or modify rather than relying on undo to reverse deletions.
paramselfReturns
boolTrue if an edit was undone, False if the stack was empty.
funcredo(self) -> boolRedo the edit most recently undone.
paramselfReturns
boolTrue if an edit was redone, False if there was nothing to redo.
funccurrent_tick(self) -> intReturn the playhead position in the editor, in ticks from the chart start.
paramselfReturns
intThe current tick (TICK_RESOLUTION ticks per whole note).
funcopen_edit(self, *, event_scan_lookahead_ticks=None, event_scan_til_ids=None, snapshot=True, raw_notes=False, replace_all=False) -> EditTransactionBegin an edit transaction over the current chart.
Returns an :class:~margrete_rpc.transaction.EditTransaction to be used as a
context manager. Mutate tx.chart inside the with block; on clean exit the
changes are diffed and applied to Margrete as a single undoable edit, and on an
exception nothing is applied.
paramselfparamevent_scan_lookahead_ticksint | None= NoneExtra tick window to scan for timeline events beyond
the note range; None uses the server default.
paramevent_scan_til_idslist[int] | None= NoneTimeline IDs to scan for speed events. None (default)
restricts scanning to timelines that carry notes. Pass an explicit list
(including [] for all default timelines) to override.
paramsnapshotbool= TrueCapture a baseline snapshot so only changed notes are sent on apply. Disable to skip diffing.
paramraw_notesbool= FalseLoad every note as a raw protobuf-tree model (:class:RawNote)
instead of typed note objects.
paramreplace_allbool= FalseReplace every note in the chart on apply instead of applying a diff. Useful for full rewrites.
Returns
margrete_rpc.transaction.EditTransactionclass:~margrete_rpc.transaction.EditTransaction bound to the loaded chart.