antescofo

Antescofo Python Interface

A Python library for communicating with and controlling Antescofo, the score following and synchronous programming language for music.

Basic usage:

>>> from antescofo import AntescofoClient
>>> client = AntescofoClient()
>>> client.connect()
>>> client.load_score("myscore.asco.txt")
>>> client.start()

For more examples, see the examples/ directory.

class antescofo.ActionTraceEvent(action_name: str, trace_type: str, father_name: str, now: float, rnow: float, message: str, raw_address: str = None)

Specialized event for action traces.

class antescofo.AntescofoClient(host: str = 'localhost', port: int = None, receive_port: int | None = None, auto_connect: bool = False)

High-level client for controlling an Antescofo instance.

This class provides a Pythonic interface to Antescofo, allowing you to: - Load and control score playback - Send OSC messages - Subscribe to events - Control transport (start, stop, tempo, etc.)

Example

>>> client = AntescofoClient()
>>> client.connect()
>>> client.load_score("myscore.asco.txt")
>>> client.start()
>>> client.set_tempo(120)
>>> client.stop()
>>> client.disconnect()

Or use as a context manager:

>>> with AntescofoClient() as client:
...     client.load_score("myscore.asco.txt")
...     client.start()

configure_ascograph(host: str = 'localhost', port: int = 6789)

Configure Ascograph communication.

Parameters:

• host – Ascograph host

• port – Ascograph port (default: 6789)

connect()

Establish connection to Antescofo.

Creates the OSC communicator and starts receiving if a receive port is configured.

disconnect()

Disconnect from Antescofo.

Stops receiving and cleans up resources.

enable_incoming_osc(enable: bool = True)

Enable or disable incoming OSC messages.

Parameters:

enable – Whether to enable (True) or disable (False)

enable_osc_communication(enable: bool = True)

Enable or disable OSC communication with Ascograph/external systems.

Parameters:

enable – Whether to enable (True) or disable (False)

load_score(filepath: str | Path)

Load an Antescofo score file.

Parameters:

filepath – Path to the score file (.asco.txt or similar)

next_event()

Skip to the next event in the score.

off(event_type: EventType | str | None, handler: Callable[[Event], None])

Unsubscribe from events.

Parameters:

• event_type – Type of event to unsubscribe from

• handler – Handler to remove

on(event_type: EventType | str | None, handler: Callable[[Event], None])

Subscribe to events from Antescofo.

Parameters:

• event_type – Type of event to subscribe to (EventType enum or string), or None to subscribe to all events

• handler – Callback function that takes an Event object

Example

>>> def on_tempo_change(event):
...     print(f"Tempo changed to: {event.data}")
>>> client.on(EventType.TEMPO, on_tempo_change)
>>> # or
>>> client.on("tempo", on_tempo_change)

pause()

Pause score playback.

prev_event()

Go back to the previous event in the score.

resume()

Resume paused playback.

send_osc(address: str, *args)

Send an OSC message to Antescofo.

Parameters:

• address – OSC address (will be prefixed with /antescofo/ if not present)

• *args – Message arguments

set_incoming_osc_port(port: int)

Set the port for incoming OSC messages.

Parameters:

port – Port number

set_tempo(tempo: float)

Set the tempo.

Parameters:

tempo – Tempo in BPM (beats per minute)

start()

Start score playback.

stop()

Stop score playback.

wait(seconds: float)

Wait for a specified number of seconds.

Useful for keeping a script alive while Antescofo is playing.

Parameters:

seconds – Number of seconds to wait

exception antescofo.AntescofoException

Base exception for all Antescofo-related errors.

exception antescofo.ConnectionError

Raised when connection to Antescofo fails.

class antescofo.Event(event_type: EventType, data: Any, raw_address: str = None)

Represents an event received from Antescofo.

class antescofo.EventDispatcher

Manages event subscriptions and dispatching.

Allows subscribing to specific event types and dispatching events to registered handlers.

clear() → None

Clear all event handlers.

dispatch(event: Event) → None

Dispatch an event to all registered handlers.

Parameters:

event – Event to dispatch

subscribe(event_type: EventType | None, handler: Callable[[Event], None]) → None

Subscribe to an event type.

Parameters:

• event_type – Type of event to subscribe to, or None for all events

• handler – Callback function to handle the event

unsubscribe(event_type: EventType | None, handler: Callable[[Event], None]) → None

Unsubscribe from an event type.

Parameters:

• event_type – Type of event to unsubscribe from, or None for global handlers

• handler – Handler to remove

class antescofo.EventType(value)

Types of events that can be received from Antescofo.

classmethod from_message(message_type: str) → EventType

Get EventType from message type string.

exception antescofo.InvalidMessageError

Raised when an invalid OSC message is received.

class antescofo.Map(data: Dict[str, Any] = None)

Represents an Antescofo map (associative array/dictionary).

Maps are collections of key-value pairs.

classmethod from_dict(dct: Dict[str, Any]) → Map

Create a Map from a Python dictionary.

get(key: str, default: Any = None) → Any

Get a value by key with an optional default.

items()

Return key-value pairs.

keys()

Return the keys.

to_dict() → Dict[str, Any]

Convert to a Python dictionary.

values()

Return the values.

class antescofo.OSCCommunicator(host: str = 'localhost', send_port: int = 5678, receive_port: int | None = None)

Handles OSC communication with Antescofo.

Manages sending messages to Antescofo and receiving messages from it.

close()

Close the communicator and clean up resources.

send(address: str, *args)

Send an OSC message.

Parameters:

• address – OSC address pattern (e.g., “/antescofo/tempo”)

• *args – Message arguments

send_raw(*args)

Send raw arguments without an address (for internal Antescofo commands).

Parameters:

*args – Message arguments (first arg typically the command name)

start_receiving()

Start the OSC server to receive messages.

stop_receiving()

Stop the OSC server.

subscribe(event_type: EventType | None, handler: Callable[[Event], None])

Subscribe to events.

Parameters:

• event_type – Type of event to subscribe to, or None for all events

• handler – Callback function to handle events

unsubscribe(event_type: EventType | None, handler: Callable[[Event], None])

Unsubscribe from events.

Parameters:

• event_type – Type of event to unsubscribe from

• handler – Handler to remove

exception antescofo.OSCError

Raised when OSC communication fails.

class antescofo.ScoreBuilder

Builder pattern for constructing Antescofo scores programmatically.

Example

>>> builder = ScoreBuilder()
>>> builder.comment("My Score")
>>> builder.event("NOTE", 1.0, "C4 60")
>>> builder.action("print Hello")
>>> builder.save("myscore.asco.txt")

action(action: str) → ScoreBuilder

Add an action.

Parameters:

action – Action code

Returns:

Self for chaining

comment(text: str) → ScoreBuilder

Add a comment.

Parameters:

text – Comment text

Returns:

Self for chaining

event(event_type: str, duration: float | None = None, attributes: str | None = None) → ScoreBuilder

Add an event.

Parameters:

• event_type – Event type

• duration – Duration

• attributes – Attributes

Returns:

Self for chaining

get_score() → ScoreFile

Get the built score.

Returns:

The ScoreFile object

insert(filepath: str | Path) → ScoreBuilder

Insert a file.

Parameters:

filepath – Path to insert

Returns:

Self for chaining

insert_once(filepath: str | Path) → ScoreBuilder

Insert a file once.

Parameters:

filepath – Path to insert

Returns:

Self for chaining

raw(line: str) → ScoreBuilder

Add a raw line.

Parameters:

line – Line to add

Returns:

Self for chaining

save(filepath: str | Path)

Save the score to a file.

Parameters:

filepath – Path to save to

exception antescofo.ScoreError

Raised when score file operations fail.

class antescofo.ScoreFile(content: str = '')

Represents an Antescofo score file.

Provides methods to read, write, and manipulate score files.

add_action(action: str)

Add an action to the score.

Parameters:

action – Action code

add_comment(comment: str)

Add a comment line.

Parameters:

comment – Comment text (will be prefixed with ;)

add_conditional(condition: str, if_block: str, else_block: str | None = None)

Add a conditional block.

Parameters:

• condition – Condition expression

• if_block – Code to execute if condition is true

• else_block – Optional code to execute if condition is false

add_event(event_type: str, duration: float | None = None, attributes: str | None = None)

Add an event to the score.

Parameters:

• event_type – Type of event (e.g., “NOTE”, “CHORD”)

• duration – Duration of the event

• attributes – Additional attributes

append(line: str)

Append a line to the score.

Parameters:

line – Line to append

clear()

Clear the score content.

insert(index: int, line: str)

Insert a line at a specific position.

Parameters:

• index – Position to insert at

• line – Line to insert

insert_file(filepath: str | Path, quote_if_spaces: bool = True)

Insert a @insert directive for another file.

Parameters:

• filepath – Path to the file to insert

• quote_if_spaces – Whether to quote the filepath if it contains spaces

insert_file_once(filepath: str | Path, quote_if_spaces: bool = True)

Insert a @insert_once directive for another file.

Parameters:

• filepath – Path to the file to insert

• quote_if_spaces – Whether to quote the filepath if it contains spaces

classmethod load(filepath: str | Path) → ScoreFile

Load a score file from disk.

Parameters:

filepath – Path to the score file

Returns:

ScoreFile object

Raises:

ScoreError – If the file cannot be read

save(filepath: str | Path)

Save the score to a file.

Parameters:

filepath – Path to save the score to

Raises:

ScoreError – If the file cannot be written

class antescofo.Tab(values: List[Any] = None)

Represents an Antescofo tab (array/list).

Tabs are ordered collections of values that can be of mixed types.

append(value: Any)

Add a value to the end of the tab.

classmethod from_list(lst: List[Any]) → Tab

Create a Tab from a Python list.

to_list() → List[Any]

Convert to a Python list.

exception antescofo.TimeoutError

Raised when an operation times out.

antescofo.from_osc_value(value: Any) → int | float | str | Tab | Map | List | Dict

Convert an OSC value to a Python value.

Parameters:

value – OSC value to convert

Returns:

Python value

antescofo.get_config_value(key: str, default: Any = None) → Any

Get a specific configuration value.

Parameters:

• key – Configuration key

• default – Default value if key not found

Returns:

Configuration value

antescofo.init_config(force: bool = False) → Path

Initialize user configuration with defaults.

Creates ~/.config/antescofo/config.json with default settings.

Parameters:

force – If True, overwrite existing config

Returns:

Path to the config file

antescofo.load_config(reload: bool = False) → Dict[str, Any]

Load user configuration.

Parameters:

reload – If True, bypass cache and reload from disk

Returns:

Configuration dictionary

antescofo.print_config()

Print the current configuration.

antescofo.resolve_score_path(score_name: str) → Path

Resolve a score file path.

If score_name is relative, looks in the default score directory. If absolute, uses as-is.

Parameters:

score_name – Score filename or path

Returns:

Resolved absolute path

antescofo.save_config(config: Dict[str, Any])

Save configuration to file.

Parameters:

config – Configuration dictionary to save

antescofo.set_config_value(key: str, value: Any)

Set a specific configuration value and save.

Parameters:

• key – Configuration key

• value – Value to set

antescofo.to_osc_value(value: int | float | str | Tab | Map | List | Dict) → Any

Convert a Python value to an OSC-compatible value.

Parameters:

value – Python value to convert

Returns:

OSC-compatible value