Play

The #play command in ZZT-OOP allows objects and scrolls to play music and sound effects.

Syntax

#play <sound>

The general syntax is that parameters come before the notes and drums they modify.

All characters not listed below are silently ignored (like comments).

Parameters

Symbol	Denotes	Length in Ticks
t	32nd Note	1
s	Sixteenth Note	2
i	Eighth Note	4
q	Quarter Note	8
h	Half Note	16
w	Whole Note	32
3	Triplet	(n/3)
.	Time-and-a-half	(n*3)/2
+	Up octave	N/A
-	Down octave	N/A

The octave and length parameters are reset each line. The default note length is 1 (32nd note), and the default octave is 3 (ranges from 1 to 6 inclusively).

Note that the lengths are measured in PIT ticks, not cycles! The PIT ticks at approximately 18.2 Hz, meaning that a 32nd note lasts approximately 55 milliseconds.

The triplet and time-and-a-half modifiers need to be placed somewhere after the length parameters they are modifying (eg w3 or h.). These modifiers also stack (eg. w.3 produces a 16-tick-long note length, equivalent to h).

Notes and Rests

• X - Rest
• CDEFGAB - Piano notes, can be followed by:
  • # - Sharp
  • ! - Flat

Drums

Symbol	"Sound"
0	Tick
1	Tweet
2	Cowbell
3	N/A -- Denotes Triplet
4	Hi snare
5	Hi woodblock
6	Low snare
7	Low tom
8	Low woodblock
9	Bass drum

Drums are hardcoded percussion effects, created by rapidly changing the frequency emitted by the PC Speaker. They last for approximately 14 milliseconds each, with the exception of the 1-millisecond tick.

Examples

This page is a stub! Somebody recolor the walls!

[TODO: Put a simple thing here and explain it character by character.]

Quirks

Sound parser

• When a scroll uses #play it does not suppress the default scroll sound effect. Rather, the sound is appended to the end of the sound effect.
• The triplet and time-and-a-half parameters use integer floor division. If the result of the division is 0 (with either t3 or s3), then the length value will underflow, causing ZZT to play a 256-tick-long note - which is also the maximum possible length of a single note.

Sound playback

• The note frequencies are calculated using scientific pitch, with C₄ equal to 256 Hz and A₄ theoretically equal to 430.54 Hz. However, inaccuracies are introduced in the frequency calculation process by the use of two turncation operations:
  • The first truncation removes the fractional component of the frequency; for example, A₄, after truncation, is equal to 430 Hz.
  • The second truncation is applied inside Turbo Pascal's built-in Sound() function, when deriving the IBM PC's programmable interrupt timer period from the provided frequency. (TODO)
• Drums are timed using Turbo Pascal's built-in Delay() function. As it was designed for the late 1980s state of the art in computer technology, the frequencies will alternate far too quickly on more modern hardware.
  • The above also means that, on slower hardware, a drum playback actually stalls engine execution for the duration of its sound.
• The sound buffer has a size limit of 255 bytes; as each queued sound (note + duration pair) takes up two bytes, this means there may be at most 127 different sounds queued up for playback.

See Also

• Sound effects - ZZT's built-in sound effects, expressed in #play statements.
• Duration Table - A programmatically generated list of possible note durations in ZZT-OOP