Skip to content

Latest commit

 

History

History
213 lines (145 loc) · 4.39 KB

alda-repl-server-api.adoc

File metadata and controls

213 lines (145 loc) · 4.39 KB
Raw

Alda REPL server API

Alda REPL clients and servers communicate using the nREPL protocol, with bencode over TCP as the transport.

Tip

You can also send JSON messages via the Alda CLI. For example:

$ alda repl --client --port 34223 --message '{"op": "eval-and-play", "code": "harmonica: c8 d e f"}'
{"id":"17aa14c2-fa23-4bde-af4d-85839a85fc5d","session":"2d9ca3d1-2bcb-4e8b-9344-957ee4e4bdd9","status":["done"]}

$ alda repl --client --port 34223 --message '{"op": "eval-and-play", "code": "g f e d c2"}'
{"id":"27612a45-7d4a-4f7e-b65d-be6cf5107abf","session":"60f70325-efd6-492c-9e8f-279eba76a4d7","status":["done"]}

$ alda repl --client --port 34223 --message '{"op": "score-text"}'
{"id":"f1f45d28-d7f3-4fc2-b605-0fbc2b8d4ae1","session":"3da40081-1007-4630-bb38-b19abeaeef0a","status":["done"],"text":"harmonica: c8 d e f\ng f e d c2\n"}

Operations

describe

Returns information on the Alda REPL server.

Required parameters

Optional parameters

Returns

  • ops - the operations available on the Alda REPL server

  • problems if there were any

  • status

  • versions - Alda version information

eval-and-play

Parses the provided input in the context of the current score, updates the score with the parse results, and plays any new events that were added to the score.

This is the operation that occurs in an Alda REPL session each time you enter a line of Alda code and press Enter.

Required parameters

  • code - a string of Alda code

Optional parameters

Returns

  • status

  • problems if there were any

export

Exports the current score to MIDI and returns the binary data to be saved as a MIDI file.

Required parameters

Optional parameters

Returns

  • status

  • problems if there were any

  • binary-data - exported MIDI binary data for the current score

instruments

Returns the list of instruments available to use in an Alda score.

Required parameters

Optional parameters

Returns

  • status

  • problems if there were any

  • instruments - the list of available instruments

load

Parses the provided input as a new score and loads the score into the REPL server.

Required parameters

  • code - a string of Alda code

Optional parameters

Returns

  • status

  • problems if there were any

new-score

Resets the REPL server state and initializes a new score.

Required parameters

Optional parameters

Returns

  • status

  • problems if there were any

replay

Plays back the score currently loaded into the REPL server.

Required parameters

Optional parameters

  • from - a string that is either a minute-second marking (e.g. 0:30) or a marker name (e.g. verse), representing where in the score to start playing

  • to - a string that is either a minute-second marking (e.g. 1:00) or a marker name (e.g. chorus), representing where in the score to stop playing

Returns

  • status

  • problems if there were any

score-ast

Returns the parsed AST of the current score. (This is the output that you get when you run alda parse -o ast …​ at the command line.)

Required parameters

Optional parameters

Returns

  • status

  • problems if there were any

  • ast - the parsed AST of the current score, as a JSON string

score-data

Returns a data representation of the current score. (This is the output that you get when you run alda parse -o data …​ at the command line.)

Required parameters

Optional parameters

Returns

  • status

  • problems if there were any

  • data - a data representation of the current score

score-events

Returns the parsed events output of the score. (This is the output that you get when you run alda parse -o events …​ at the command line.)

Required parameters

Optional parameters

Returns

  • status

  • problems if there were any

  • events - the parsed events output of the current score

score-text

Returns the text (Alda code) of the current score.

Required parameters

Optional parameters

Returns

  • status

  • problems if there were any

  • text - the Alda code of the current score

stop

Stops playback.

Required parameters

Optional parameters

Returns

  • status

  • problems if there were any