Create: Computing AgesBrass Docs
Libraries

sound

Notes and the sounds of the game, played by a Speaker touching the computer, or by the speaker of a smartphone.

Any computer a Speaker touches, and the Smartphone

The sound library makes a computer heard: a chime when a train pulls in, a bell at the door, an alarm when a line overstresses, music for a game. It plays the notes of the 16 note block instruments, and any sound of the game.

Brass
sound.note("harp", 12)         -- the F# in the middle of a note block
sound.play("block.bell.use")   -- the village bell

Things to know before you start:

  • A Speaker. A computer has sound only while a Speaker touches one of its faces: without one, sound is nil. The Speaker is made at the crafting table in the Vacuum Tube Age (planks, paper, an Electromagnet, a Vacuum Tube) and works with every computer, the Tube Computer included. Put it against any face, as you would a monitor: a Data Cable does not carry sound.
  • The Smartphone has a speaker built in: sound is always there, and the sound follows the player who carries it.
  • It comes and goes. The library appears when the first Speaker is placed and goes away with the last one, even while a program runs. A program that may run without a speaker checks first: if sound then ... end. A program that kept sound in a variable stops with no speaker: put a Speaker against the computer when its speaker goes.
  • Where it is heard. The sound comes out of the Speaker, like a note block: players hear it up to 16 blocks away at volume 1, 48 blocks at volume 3, louder the closer they stand. With several speakers it comes out of one of them, no louder. It follows the "Jukebox/Note Blocks" slider of the game's sound settings.
  • Eight a tick. A computer plays 8 sounds a tick at most, notes and sounds together: enough for a chord, never a flood. The next calls in the same tick play nothing and return false; the count starts again at the next tick. A melody waits between its notes with sleep.
Functions
sound.note(instrument, note [, volume])Plays a note, as a note block with that instrument would after that many clicks. The notes of the first octave, for the harp:
sound.instruments()The names sound.note takes, to try them all or to let a player choose one.
sound.play(name [, volume [, pitch]])Plays any sound of the game, or of a mod. A name without a namespace is one of Minecraft's: "block.bell.use" and "minecraft:block.bell.use" are the same sound. Typing /playsound in the chat lists them all as you type.

Notes

#

sound.note(instrument, note [, volume])

→ boolean

Plays a note, as a note block with that instrument would after that many clicks. The notes of the first octave, for the harp:

Parameters
instrument string
one of the 16 instruments of a note block: "harp", "bass", "bell", "bit"... (see sound.instruments)
note number
the pitch in semitones, from 0 to 24, like the clicks of a note block: 0 is an F#, 12 the F# one octave higher, 24 two octaves higher
volume number optional
from 0 (silent) to 3; 1 when left out
Returns
boolean
true when it played, false when the computer already played 8 sounds this tick
note01234567891011
nameF#GG#AA#BCC#DD#EF

12 to 23 are the same notes one octave higher, and 24 is the highest F#. A note in between, like 12.5, plays a quarter tone; a note below 0 or above 24 becomes 0 or 24, and so does a volume outside 0 to 3. The other instruments play the same notes in their own octave: the bass two octaves lower, the bell two octaves higher.

Three notes in the same tick make a chord:

Brass
sound.note("harp", 6)    -- C
sound.note("harp", 10)   -- E
sound.note("harp", 13)   -- G

A doorbell: a pressure plate in front of the door is wired to the left face, and two notes ring when someone steps on it.

Brass
local was = false
while true do
  os.pull_event("redstone")
  local on = rs.get("left") > 0
  if on and not was then
    sound.note("bell", 18)
    sleep(0.3)
    sound.note("bell", 14)
  end
  was = on
end

A tune is a list of notes, each with how long it lasts. A beat of 0.15 seconds is 3 ticks: sleep counts in ticks (see Events).

Brass
local tune = {{6, 2}, {8, 2}, {10, 2}, {6, 2}, {10, 2}, {11, 2}, {13, 4}}
for _, n in ipairs(tune) do
  sound.note("flute", n[1])
  sleep(n[2] * 0.15)
end

The built-in music program plays a whole tune this way: music bell plays it with another instrument.

An instrument that is not in the list stops the program, and the error lists the right ones:

Terminal
> brass
Brass 1.0 - type 'exit' to leave.
brass> sound.note("kazoo", 12)
brass:1: unknown instrument 'kazoo' (harp, basedrum
, snare, hat, bass, flute, bell, guitar, chime, xyl
ophone, iron_xylophone, cow_bell, didgeridoo, bit,
banjo, pling)
brass> exit

The voices a mob head gives a note block are not instruments: play them with sound.play, for example sound.play("block.note_block.imitate.creeper").

See also sound.instruments() sound.play() note_block.play()

#

sound.instruments()

→ table

The names sound.note takes, to try them all or to let a player choose one.

Returns
table
the names of the 16 instruments, in the order of the game
Brass
for _, name in ipairs(sound.instruments()) do
  print(name)
  sound.note(name, 12)
  sleep(0.5)
end

They are the instruments a note block gets from the block under it:

instrumentblock under a note block
harpany other block (dirt, grass...)
basedrumstone, netherrack, obsidian, concrete
snaresand, gravel, concrete powder
hatglass, sea lantern
basswood (planks, logs)
fluteclay
bellblock of gold
guitarwool
chimepacked ice
xylophonebone block
iron_xylophoneblock of iron
cow_bellsoul sand
didgeridoopumpkin
bitblock of emerald
banjohay bale
plingglowstone

See also sound.note() note_block.instrument()

Sounds of the game

#

sound.play(name [, volume [, pitch]])

→ boolean

Plays any sound of the game, or of a mod. A name without a namespace is one of Minecraft's: "block.bell.use" and "minecraft:block.bell.use" are the same sound. Typing /playsound in the chat lists them all as you type.

Parameters
name string
the id of a sound, as in the /playsound command: "block.bell.use", "minecraft:entity.cat.ambient", or a sound of another mod ("create:...")
volume number optional
from 0 (silent) to 3; 1 when left out
pitch number optional
from 0.5 (an octave lower, twice as slow) to 2 (an octave higher, twice as fast); 1 when left out
Returns
boolean
true when it played, false when the computer already played 8 sounds this tick
idwhat it sounds like
block.bell.usethe village bell
entity.experience_orb.pickupthe experience ding: a job done
entity.player.levelupthe level up chime
entity.villager.yes, entity.villager.noa villager agreeing, or not
block.anvil.landa heavy clang
block.lever.click, ui.button.clicka click
block.beacon.activatea beacon powering up
entity.generic.explodean explosion
Brass
sound.play("entity.experience_orb.pickup")
sound.play("entity.cat.ambient", 1, 1.5)   -- a higher, quicker meow
sound.play("block.anvil.land", 0.3)        -- far quieter

An alarm that rings while the stress of a line is over 90 % of its capacity, read from a Stressometer:

Brass
local gauge = peripheral.find("stressometer")
while true do
  if gauge.stress() > gauge.capacity() * 0.9 then
    sound.play("block.bell.use", 2)
  end
  sleep(1)
end

A name that is no sound stops the program: sound.play("block.bel.use") gives unknown sound 'block.bel.use'. A long sound plays to its end: a music disc ("music_disc.cat") plays the whole record, and nothing can stop it.

Good to know

  • Far from the computer. The Speaker touches the computer. To make a sound far away, put note blocks on the computer's Data Cable and play them as peripherals (Note Block), or send a message to another computer with its own Speaker (net).
  • A Smartphone in your pocket. The players around you hear it too, as they would hear a note block you carry.
  • Silence. A volume of 0 plays nothing that can be heard, but still counts in the 8 sounds of the tick.

See also sound.note()