Commands

play

Supported By

Syntax

play instrument [[tempo tempo] notes]

play stop

Instrument and notes yield strings. Tempo yields a number.

Examples

play "harpsichord" "ch d e f g a b c5w"
play "music box" "c4e c dq c f eh"
play "harpsichord" "c4 a3 f c4 a3 f c4 d c c c"

Description

The play command plays the specified sequence of notes with the specified instrument using a MIDI synthesizer (in OpenXION) or sampled sounds (in HyperTalk). The tempo parameter specifies the number of quarter notes per minute; the default value is 120.

The play command in OpenXION uses an extended version of the scripted music notation originally found in HyperTalk. A sequence of notes is represented as a string with notes delimited by whitespace. Each note has the following format for a regular note:

noteName [octave] [duration] [velocity] [effect]

or the following format for a rest:

duration r

NoteName is a letter between A and G, which may or may not be followed by any number of # symbols, each of which raises the pitch a half step, or any number of b symbols, each of which lowers the pitch a half step. In OpenXION, noteName can also be one of the letters M, N, or P followed by the MIDI dollar value, for which 60 is middle C. NoteName is the only required part of a note string.

Octave is an integer specifying which octave the note belongs to. If the octave is not specified, the last octave specified is used. The default is 4, the octave starting with middle C.

(Middle C corresponds to the note string C4 or B#3. The note one half step below middle C is B3 or Cb4. 440 Hz corresponds to the note string A4.)

Duration is one of the following letters:

w whole note
h half note
q quarter note
e eighth note
s 16th note
t 32nd note
x 64th note
o 128th note

which may or may not be followed by any number of . symbols, each of which multiplies the duration by 1.5 to create a dotted note, or any number of 3 symbols, each of which divides the duration by 3 to create a triplet note. (In OpenXION, you can use any digit 2 through 9 to divide the duration by that value. Also in OpenXION, duration can be the letter d followed by the duration in MIDI ticks. OpenXION uses 64 ticks per quarter note.) If the duration is not specified, the last duration specified is used. The default is q, the duration of a quarter note.

Velocity is an extension provided by OpenXION not found in HyperTalk. It may be any of the following strings:

fff triple forte (velocity 127)
ff fortissimo (velocity 112)
f forte (velocity 96)
mff (velocity 88)
mf mezzo forte (velocity 80)
m (velocity 72)
mp mezzo piano (velocity 64)
mpp (velocity 56)
p piano (velocity 48)
pp pianissimo (velocity 32)
ppp triple piano (velocity 16)

Velocity can also be the letter v followed by the velocity of the note from 0 to 127. If the velocity is not specified, the last velocity specified is used. The default is fff or 127.

Effect is another extension provided by OpenXION not found in HyperTalk. It is one or more of the following characters:

, The note is stopped a few MIDI ticks before it normally would be, creating a stoccato effect.
* The note keeps playing after its duration has passed. This can be used to start a fermata. (This overrides the effect of any , or any preceding !.)
! Stops a note previously started by * after the duration has passed. This can be used to end a fermata. If the note is not already playing, this is equivalent to a rest. (This overrides the effect of any preceding *.)
+ Starts the next note at the same time as this note, creating a chord.

If effect is not specified, no effects are applied.

If the note string contains an r, it is a rest and only the duration can be specified.

Notes

The play command is asynchronous: it will return immediately while the sound keeps playing in the background. If there is already sound playing on the current soundChannel, the next sound to be played will be added to a queue. The play stop form of the play command will stop playing any sound on the current soundChannel. The stop sound command will stop all currently-playing and pending sounds on all soundChannels.

Early versions of HyperTalk limited the length of the note string to 254 characters. OpenXION and later versions of HyperTalk do not limit the length of the note string.

In HyperTalk, the play command accepted note strings that were left unquoted, and this was often done. For example:

play harpsichord c4 a3 f c4 a3 f c4 d c c c

OpenXION will also accept unquoted note strings, but this is highly discouraged. You cannot use any special symbols (such as #, ., or +) in an unquoted note string, and if one of the notes in an unquoted note string turns out to also be the name of a constant or variable, the value of the constant or the contents of the variable will be played instead of the intended note.

See Also

stop, sound, soundChannel