alda.lisp — alda/core 0.5.0

alda.parser transforms Alda code into Clojure code, which can then be evaluated with the help of this namespace.

*attribute-table* clj

*initial-attr-vals* clj

absolute-offset clj

(absolute-offset this score)

Returns the offset in ms from the start of the score.

add-event clj

(add-event {:keys [instruments events markers] :as score}
           {:keys [instrument offset] :as event})

add-events clj

(add-events score events)

add-note-or-rest clj

(add-note-or-rest {:keys [beats-tally beats-tally-default instruments
                          voice-instruments current-voice]
                   :as score}
                  {:keys [beats] :as event})

alda-code clj

(alda-code code)

Attempts to parse a string of text within the context of the current score; if the code parses successfully, the result is one or more events that are spliced into the score.

ALDA-LISP-LOADED clj

apply-attribute clj

(apply-attribute {:keys [beats-tally] :as score} inst attr val)

Given an instrument map, a keyword representing an attribute, and a value, returns the updated instrument with that attribute update applied.

apply-global-attributes clj

(apply-global-attributes)

For each instrument in :current-instruments, looks between the instrument's :last-offset and :current-offset and applies any attribute changes occurring within that window.

Both global and per-instrument attributes are applied; in the case that a per-instrument attribute is applied at the exact same time as a global attribute, the per-instrument attribute takes precedence for that instrument.

at-marker clj

(at-marker name)

Set the marker at which events will be added.

barline clj

(barline)

Barlines, at least currently, do nothing when evaluated in alda.lisp.

calculate-duration clj

(calculate-duration beats tempo time-scaling & [ms])

Given a number of beats, a tempo, and a time-scaling factor, calculates the duration in milliseconds.

Takes as an optional final argument a number of milliseconds to add to the total.

chord clj

(chord & events)

Causes every instrument in :current-instruments to play each note in the chord simultaneously at the instrument's :current-offset.

continue clj

(continue score & body)

Continues the score represented by the score map score, evaluating the events in body and returning the completed score.

continue! clj

(continue! score-atom & body)

Convenience function for dealing with Alda scores stored in atoms.

(continue! my-score (part 'bassoon' (note (pitch :c))))

is short for:

(apply swap! my-score continue (part 'bassoon' (note (pitch :c))))

cram clj

(cram & events)

A cram expression evaluates the events it contains, time-scaled based on the inner tally of beats in the events and the outer durations of each current instrument.

defattribute clj macro

(defattribute attr-name & things)

Convenience macro for setting up attributes.

determine-midi-note clj

(determine-midi-note {:keys [letter accidentals] :as note}
                     octave
                     key-sig
                     transpose)

Determines the MIDI note number of a note, within the context of an instrument's octave and key signature.

duration clj

(duration & components)

Combines a variable number of tied note-lengths into one.

Note-lengths can be expressed in beats or milliseconds. This distinction is made via the :type key in the map. The number of beats/milliseconds is provided via the :value key in the map.

e.g. (note-length 1) => {:type :beats, :value 4} (ms 4000) => {:type :milliseconds, :value 4000}

To preserve backwards compatibility, a note-length expressed as a simple number (not wrapped in a map) is interpreted as a number of beats.

Barlines can be inserted inside of a duration -- these currently serve a purpose in the parse tree only, and evaluate to nil in alda.lisp. This function ignores barlines by removing the nils.

Returns a map containing the total number of beats (counting only those note-lengths that are expressed in standard musical notation) and the total number of milliseconds (counting only those note-lengths expressed in milliseconds).

This information is used by events (like notes and rests) to calculate the total duration in milliseconds (as this depends on the score's time-scaling factor and the tempo of the instrument the event belongs to).

end-voice-group clj

(end-voice-group score)

end-voices clj

(end-voices)

By default, the score remains in 'voice mode' until it reaches an end-voices event. This is so that if an instrument part ends with a voice group, the same voices can be appended later if the part is resumed, e.g. when building a score gradually in the Alda REPL or in a Clojure process.

The end-voices event is emitted by the parser when it parses 'V0:'.

get-attr clj

(get-attr kw)

Given a keyword representing an attribute (which could be an alias, e.g. :quant for :quantization), returns the attribute map, which includes the attribute's keyword name (e.g. :quantization) and its transform function.

The transform function is a higher-order function which takes a new, user-friendly value (e.g. 100 instead of 1.0) and returns the function to apply to an instrument's existing value to update it to the new value. (See alda.lisp.attributes for examples of transform functions.)

Throws an exception if the argument supplied is not a valid keyword name or alias for an existing attribute.

get-val-fn clj

(get-val-fn attr val)

Given an attr (e.g. :tempo) and a user-friendly val (e.g. 100), returns the function to apply to an instrument's existing value to update it to the new value.

Throws an exception if the argument supplied is not a valid keyword name or alias for an existing attribute.

get-variable clj

(get-variable var-name)

Returns any number of events previously defined as a variable.

global-attribute clj

(global-attribute attr val)

Public fn for setting global attributes in a score. e.g. (global-attribute :tempo 100)

global-attributes clj

(global-attributes & attrs)

Convenience fn for setting multiple global attributes at once. e.g. (global-attributes :tempo 100 :volume 50)

instruments-all-at-same-offset clj

(instruments-all-at-same-offset {:keys [current-instruments instruments]
                                 :as score})

If all of the :current-instruments are at the same absolute offset, returns that offset. Returns nil otherwise.

(Returns 0 if there are no instruments defined yet, e.g. when placing a marker or a global attribute at the beginning of a score.)

key-sig clj

(key-sig x__13738__auto__)

key-sig! clj

(key-sig! x__13739__auto__)

key-signature clj

(key-signature x__13738__auto__)

key-signature! clj

(key-signature! x__13739__auto__)

log-attribute-change clj

(log-attribute-change {:keys [id] :as inst} attr old-val new-val)

marker clj

(marker name)

Places a marker at the current absolute offset. Throws an exception if there are multiple instruments active at different offsets.

metric-modulation clj

(metric-modulation old new)

Express tempo in terms of metric modulation, where the new note takes the same amount of time (one beat) as the old note. (e.g. (metric-modulation "4." 2) means that the new length of a half note equals the length of a dotted quarter note in the previous measure)

metric-modulation! clj

(metric-modulation! old new)

Global version

midi->hz clj

(midi->hz ref-pitch note)

Converts a MIDI note number to the note's frequency in Hz.

ms clj

(ms n)

Represents a duration value specified in milliseconds.

Wraps it in a map to give the duration function context that we're talking about milliseconds, not beats.

note clj

(note pitch)

(note pitch x)

(note {:keys [letter accidentals]} {:keys [beats ms slurred]} slur?)

Causes every instrument in :current-instruments to play a note at its :current-offset for the specified duration.

If no duration is specified, the note is played for the instrument's own internal duration, which will be the duration last specified on a note or rest in that instrument's part.

note-length clj

(note-length number)

(note-length number {:keys [dots]})

Converts a number, representing a note type, e.g. 4 = quarter, 8 = eighth, into a number of beats. Handles dots if present.

Wraps the result in a map to give the duration function context that we're talking about a number of beats.

octave clj

(octave x__13738__auto__)

octave! clj

(octave! x__13739__auto__)

Offset clj protocol

offset+ clj

(offset+ this bump)

Returns a new offset bump ms later.

offset<= clj

(offset<= score & offsets)

Convenience fn for determining if offsets are in order.

offset= clj

(offset= score & offsets)

Convenience fn for comparing absolute/relative offsets.

pan clj

(pan x__13738__auto__)

pan! clj

(pan! x__13739__auto__)

panning clj

(panning x__13738__auto__)

panning! clj

(panning! x__13739__auto__)

part clj

(part instrument-call & events)

Determines the current instrument instance(s) based on the instrument-call and evaluates the events within that context.

instrument-call can either be a map containing :names and an optional :nickname (e.g. {:names ['piano' 'trumpet'] :nickname ['trumpiano']}) or a valid Alda instrument call string, e.g. 'piano/trumpet 'trumpiano''.

pause clj

(pause & [{:keys [beats ms] :as dur}])

Causes every instrument in :current-instruments to rest (not play) for the specified duration.

If no duration is specified, each instrument will rest for its own internal duration, which will be the duration last specified on a note or rest in that instrument's part.

pitch clj

(pitch letter & accidentals)

quant clj

(quant x__13738__auto__)

quant! clj

(quant! x__13739__auto__)

quantization clj

(quantization x__13738__auto__)

quantization! clj

(quantization! x__13739__auto__)

quantize clj

(quantize x__13738__auto__)

quantize! clj

(quantize! x__13739__auto__)

reference-pitch clj

(reference-pitch x__13738__auto__)

reference-pitch! clj

(reference-pitch! x__13739__auto__)

score clj

(score & body)

Initializes a new score, evaluates the events contained in body (updating the score accordingly) and returns the completed score.

A score and its evaluation context are effectively the same thing. This means that an evaluated score can be used as an input to continue-score

set-attribute clj

(set-attribute attr val)

Public fn for setting attributes in a score. e.g. (set-attribute :tempo 100)

set-attributes clj

(set-attributes & attrs)

Convenience fn for setting multiple attributes at once. e.g. (set-attributes :tempo 100 :volume 50)

set-duration clj

(set-duration x__13738__auto__)

set-duration! clj

(set-duration! x__13739__auto__)

set-note-length clj

(set-note-length length)

Sets note duration in terms of alda note-lengths (e.g. quarter note = 4, dotted note = "4.")

set-variable clj

(set-variable var-name & events)

Defines any number of events as a variable so that they can be referenced by name.

tempo clj

(tempo val)

(tempo note-length val)

Multi-arity function that allows for an additional parameter to represent the tempo in terms of non-quarter notes (e.g.(tempo 2 60) <--> (tempo 120)). Overwrites the single-argument function produced by defattribute

tempo! clj

(tempo! val)

(tempo! note-length val)

Global version of overwritten tempo function

times clj

(times n event)

Repeats an Alda event (or sequence of events) n times. Also implements the alternate endings function. Takes as input a sequence of events optionally paired with which repetitions they play in. If no repetition position is specified for a certain event, then that event will play during all repetitions. e.g. (times 4 [[[1 3] note1] [[2] [note2 note3]] note4]) results in [[note1 note4] [note2 note3 note4] [note1 note4] [note4]]

track-vol clj

(track-vol x__13738__auto__)

track-vol! clj

(track-vol! x__13739__auto__)

track-volume clj

(track-volume x__13738__auto__)

track-volume! clj

(track-volume! x__13739__auto__)

transpose clj

(transpose x__13738__auto__)

transpose! clj

(transpose! x__13739__auto__)

transposition clj

(transposition x__13738__auto__)

transposition! clj

(transposition! x__13739__auto__)

tuning-constant clj

(tuning-constant x__13738__auto__)

tuning-constant! clj

(tuning-constant! x__13739__auto__)

update-score clj multimethod

Events in Alda are represented as maps containing, at the minimum, a value for :event-type to serve as a unique identifier (by convention, a keyword) to be used as a dispatch value.

An Alda score S-expression simply reduces update-score over all of the score's events, with the initial score state as the initial value to be reduced.

Lists/vectors are a special case -- they are reduced internally and treated as a single 'event sequence'.

voice clj

(voice voice-number & events)

One voice in a voice group.

vol clj

(vol x__13738__auto__)

vol! clj

(vol! x__13739__auto__)

volume clj

(volume x__13738__auto__)

volume! clj

(volume! x__13739__auto__)