Audio Libraries

Platform Scope

• audio/Audio_Device: JVM interpreter, generated JVM
• audio/Sound: JVM interpreter, generated JVM
• audio/Track, audio/Music: JVM interpreter, generated JVM
• audio/Midi, audio/Synth, audio/Midi_Score, audio/Midi_Song: JVM interpreter, generated JVM

Playing sound needs a sound device. Everything else works without one, so the same program runs headless, for example in tests or on a server: see Without a sound device.

Load

intern audio/Sound        -- short effects; also interns Audio_Device
intern audio/Music        -- recorded tracks; also interns Track
intern audio/Synth        -- notes played live; also interns Midi
intern audio/Midi_Song    -- MIDI files and scores; also interns Track, Midi_Score, Midi

Example

intern audio/Sound
intern audio/Synth

let beep := create Sound.tone(880.0, 120)   -- no sound file needed
beep.play()                                  -- returns at once

let s := create Synth.make()
s.set_instrument(0, Midi.SQUARE_LEAD)
s.play_note(0, Midi.MIDDLE_C, 100, 150)     -- C for 150 ms

examples/audio_example.nex plays a generated beep, an arpeggio on the synthesizer and a short tune written in code, and needs no sound files.

Without a sound device

When there is no sound device, or the environment variable NEX_AUDIO (or the Java system property nex.audio) is off, every audio class still works but plays nothing:

• Sound still loads, knows its length and counts play_count.
• Synth still keeps each channel's instrument and counts notes_played.
• Music and Midi_Song still move through their states. A Midi_Song's sequencer keeps running in real time, so it reaches its end as usual; a Music stays at position 0 and never reaches its end by itself.
• is_audible() reports false.

A test can therefore drive a program headless and check which sounds it asked for — say, that the hit sound played three times.

Files

Sound and Music read WAV, AIFF and AU files with uncompressed (PCM) audio; MP3 and OGG are not supported. Midi_Song reads standard MIDI files. A relative file name is resolved against the directory nex was started from (NEX_USER_DIR), as in Picture.load.

Audio_Device

Sound

A short sound effect held in memory. play() starts a fresh copy at once and returns without waiting, so a burst of plays sounds like a burst. Up to voices copies (4 by default) play at once; beyond that, the copy that has played longest starts over.

Track

The deferred class behind Music and Midi_Song: something that plays over time, with the state machine below. Every contract here is inherited.

       play            pause
  STOPPED ──► PLAYING ───────► PAUSED
     ▲          │  ▲  resume     │
     └── stop ──┘  └─────────────┘   (stop from PAUSED too)

The state changes only on the program's calls. The audio itself runs on a background thread, so a track can reach its end at any moment. That shows at once in reached_end(), and the state follows it when update() is called — a game calls it once per frame:

music.update()
if music.is_stopped() then next_level_music.play() end

This is what lets play() promise is_playing(): nothing can change the state between the routine's body and the postcondition check.

Music

A recorded track — background music, an ambience loop — held in memory, which suits tracks of a few minutes. Inherits Track.

Midi

General MIDI constants, so a program writes Midi.TRUMPET, not 56: DRUM_CHANNEL (9), MIDDLE_C (60), instruments from PIANO to SYNTH_DRUM, and drum notes such as BASS_DRUM, SNARE and CLOSED_HI_HAT. Notes are numbered by semitone, so 61 is the C sharp above middle C and 72 the C an octave up.

Synth

Notes played live on Java's built-in General MIDI synthesizer. There are 16 channels (0..15), each set to one of 128 instruments; channel 9 plays drums, where each note number is a different drum.

note is a keyword in Nex, so the note number is called pitch.

Midi_Score

A piece of music written in code, note by note. Time is counted in ticks, and a beat is ticks_per_beat ticks; a song plays at 120 beats per minute unless Midi_Song.set_tempo says otherwise.

let score := create Midi_Score.make(4)       -- 4 ticks per beat
score.set_instrument(0, Midi.SQUARE_LEAD, 0)
score.add_note(0, 60, 100, 0, 4)             -- C, one beat
score.add_note(0, 64, 100, 4, 4)             -- E
score.add_note(0, 67, 100, 8, 8)             -- G, two beats
let tune := create Midi_Song.from_score(score)
tune.play()

Midi_Song

A MIDI file or a Midi_Score, played by Java's sequencer on the built-in synthesizer. Inherits Track.

set_volume sets the synthesizer's master volume, so it scales the whole song whatever volumes the song sets on its own channels.

Java's sequencer runs on a thread that would keep the JVM alive, so a song has one only while it is playing or paused: play() opens it, and stop(), close() and an update() that finds the song ended close it again.