Sound¶
A canvas has a speaker and a microphone. The speaker plays notes, chords, melodies and audio files. The microphone measures how loud the sound around the computer is. xnano makes the sound of notes, chords and melodies while they play. Thus, a program can play music without sound files.
To use sound, you need the audio extra. See
Installation. On a computer without a sound
device, terminal.speaker.is_available is False. If a program plays a sound
on such a computer, xnano raises an error. If your program must run on all
computers, check is_available before you play a sound. The first example does
this check. The other examples do not, so that they stay short.
Notes and melodies¶
speaker.play() takes a note name, for example 'C4'. It also takes melody
text, which is a list of notes with spaces between them:
:2after a note holds the note for two beats.restis a silence.+between notes plays them together as a chord.
import xnano
with xnano.open(height=1) as terminal:
terminal.write('♪ playing · q quit')
if terminal.speaker.is_available:
terminal.speaker.play('C4 E4 G4:2 rest C4+E4+G4:2', instrument='piano')
terminal.run(stop_on='q')
play() returns immediately. The sound plays while the program continues.
terminal.write() is the same as terminal.screen.write().
A Note keeps a note as a value. It holds the pitch, the number of
beats and the instrument that plays the note. To make a chord, give a tuple of
pitches.
import xnano
tap = xnano.Note('C5', beats=0.25, instrument='marimba')
chord = xnano.Note(('C4', 'E4', 'G4'), beats=2, instrument='electric_piano')
The instrument argument takes one of these names:
- Instruments:
piano,electric_piano,organ,bell,marimba,guitar,electric_guitar,pluck,bass,synth,padandstrings - Waves:
sine,square,sawandtriangle - Drums:
kick,snare,hihat,open_hat,clap,tomandcowbell
Play notes from keys¶
A note is a value, so a key hook can play a note on each key press. In this example, the number keys play a scale, and the space key plays a chord:
import xnano
scale = ['C4', 'D4', 'E4', 'G4', 'A4']
chord = xnano.Note(('C4', 'E4', 'G4'), beats=2, instrument='electric_piano')
with xnano.open(height=2) as terminal:
terminal.write('1-5 play a note · space a chord · q quit', dim=True)
playing = terminal.write('', foreground='cyan')
@terminal.hook(on='key', keys=['1', '2', '3', '4', '5', 'space'])
def play(context: xnano.Context):
key = context.keyboard.key
if key == 'space':
context.speaker.play(chord)
playing.text = '♪ C4 E4 G4'
else:
pitch = scale[int(key) - 1]
context.speaker.play(xnano.Note(pitch, beats=0.5))
playing.text = f'♪ {pitch}'
terminal.run(stop_on='q')
Tempo and beats¶
xnano measures beats at the tempo of the canvas. The default tempo is 120 beats
per minute. To change it, give bpm= to xnano.open(). A hook with on='beat'
runs on the beat, and its every= value is a number of beats. Thus, a metronome
needs only a few lines:
import xnano
with xnano.open(height=1, bpm=90) as terminal:
count = terminal.write('')
tick = xnano.Note('C6', beats=0.1, instrument='cowbell')
beat = 0
@terminal.hook(on='beat', every=1)
def click(context: xnano.Context):
global beat
beat += 1
count.text = '● ' * (beat % 4 or 4)
context.speaker.play(tick)
terminal.run(stop_on='q')
Sound effects¶
The speaker takes effects, as a placement does. When you add an effect to
speaker.fx, the effect changes all the sound that the speaker plays after that.
The effects are reverb, delay, distortion, tremolo, bit_crush,
low_pass and high_pass.
import xnano
with xnano.open(height=1) as terminal:
terminal.write('a bell in a large room · q quit')
terminal.speaker.fx.reverb(room=0.9, mix=0.5)
terminal.speaker.play('C5 G5 E5:2', instrument='bell')
terminal.run(stop_on='q')
Audio files¶
xnano.load_audio() reads WAV, MP3, FLAC, Ogg Vorbis and MP4 files. The speaker
plays the result in the same way as a note.
import xnano
chime = xnano.load_audio('chime.wav')
with xnano.open(height=1) as terminal:
terminal.write('space chime · q quit')
@terminal.hook(on='key', keys='space')
def ring(context: xnano.Context):
context.speaker.play(chime)
terminal.run(stop_on='q')
The microphone¶
terminal.microphone.level is the loudness of the input, from 0.0 to 1.0.
It is an expression, as the clock is. Thus, it can set a size directly. This
meter becomes longer when you speak:
import xnano
with xnano.open(height=2) as terminal:
terminal.write('speak into your microphone · q quit', dim=True)
level = terminal.microphone.level
terminal.write('░' * 40, y=1, dim=True)
terminal.write(
'█' * 40, x=0, y=1, width=level * 40 + 1, foreground='green', layer=1
)
terminal.run(stop_on='q')
xnano opens the input device the first time that a program reads the level. If
there is no microphone, or if the program has no permission to record, the level
stays at 0.
Sound in tests¶
A canvas from xnano.new() has no sound device. Instead, the canvas records the
sound that it plays, on its own clock. speaker.render() returns the recording
as Audio. Thus, a test can examine the sound that a program
played, and no sound comes out of the speakers.
import xnano
with xnano.new(width=10, height=1) as canvas:
canvas.speaker.play('C4 E4 G4', instrument='piano')
canvas.clock.step(delta_seconds=2.0)
recording = canvas.speaker.render()
print(recording)
The xnano.audio reference gives more information:
- melodies that you make in code
- the volume of each sound, and its position between the left and right speakers
- the history of the microphone level