Sound: samples, synth, file player

Short sounds are loaded into memory (sample, sampleplayer), long ones are streamed (fileplayer, max 3), and synth provides 16 oscillator voices. Audio files must be converted to the STS format.

Conventions on every page: Availability says whether a symbol exists on the console BIOS, the emulator, or both. c8b and C8B are the same table.

Contents#

• Mixer
  • c8b.sound.play
  • c8b.sound.stopAll
  • c8b.sound.setMasterVolume
  • c8b.sound.getMasterVolume
  • c8b.sound.getActiveVoiceCount
  • c8b.sound.setBassBoost
  • c8b.sound.setWarmth
  • c8b.sound.setAnalogMode
  • c8b.sound.setPluginGain
  • c8b.sound.getSpectrum
  • c8b.sound.getLevel
  • c8b.sound.getCurrentTime
• Samples
  • c8b.sound.sample.new
  • c8b.sound.sample:getLength
  • c8b.sound.sample:getLengthSeconds
  • c8b.sound.sample:getSampleRate
  • c8b.sound.sample:free
• Sample players
  • c8b.sound.sampleplayer.new
  • c8b.sound.sampleplayer:play
  • c8b.sound.sampleplayer:stop
  • c8b.sound.sampleplayer:pause
  • c8b.sound.sampleplayer:resume
  • c8b.sound.sampleplayer:isPlaying
  • c8b.sound.sampleplayer:setVolume
  • c8b.sound.sampleplayer:getVolume
  • c8b.sound.sampleplayer:setPan
  • c8b.sound.sampleplayer:getPan
  • c8b.sound.sampleplayer:setRate
  • c8b.sound.sampleplayer:getRate
  • c8b.sound.sampleplayer:setOffset
  • c8b.sound.sampleplayer:getOffset
  • c8b.sound.sampleplayer:setSample
  • c8b.sound.sampleplayer:free
• File players (streaming)
  • c8b.sound.fileplayer.new
  • c8b.sound.fileplayer:load
  • c8b.sound.fileplayer:play
  • c8b.sound.fileplayer:stop
  • c8b.sound.fileplayer:pause
  • c8b.sound.fileplayer:isPlaying
  • c8b.sound.fileplayer:getLength
  • c8b.sound.fileplayer:setOffset
  • c8b.sound.fileplayer:getOffset
  • c8b.sound.fileplayer:setRate
  • c8b.sound.fileplayer:getRate
  • c8b.sound.fileplayer:setVolume
  • c8b.sound.fileplayer:getVolume
  • c8b.sound.fileplayer:setFinishCallback
  • c8b.sound.fileplayer:didUnderrun
  • c8b.sound.fileplayer:setStopOnUnderrun
  • c8b.sound.fileplayer:setBufferSize
  • c8b.sound.fileplayer:setLoopRange
  • c8b.sound.fileplayer:setLoopCallback
• Synth
  • c8b.sound.synth.new
  • c8b.sound.synth:playNote
  • c8b.sound.synth:playMIDINote
  • c8b.sound.synth:noteOff
  • c8b.sound.synth:stop
  • c8b.sound.synth:isPlaying
  • c8b.sound.synth:setWaveform
  • c8b.sound.synth:setADSR
  • c8b.sound.synth:setAttack
  • c8b.sound.synth:setDecay
  • c8b.sound.synth:setSustain
  • c8b.sound.synth:setRelease
  • c8b.sound.synth:setLegato
  • c8b.sound.synth:setVolume
  • c8b.sound.synth:getVolume
  • c8b.sound.synth:setFinishCallback
  • c8b.sound.synth:copy
  • c8b.sound.synth:setAmplitudeMod
  • c8b.sound.synth:setFrequencyMod
  • c8b.sound.synth:setParameter
  • c8b.sound.synth:setParameterMod
  • c8b.sound.synth:setEnvelopeCurvature
  • c8b.sound.synth:setWavetable
• Waveform constants
  • c8b.sound.kWaveSquare
  • c8b.sound.kWaveTriangle
  • c8b.sound.kWaveSine
  • c8b.sound.kWaveNoise
  • c8b.sound.kWaveSawtooth
  • c8b.sound.kWavePOPhase
  • c8b.sound.kWavePODigital
  • c8b.sound.kWavePOVosim

Mixer#

c8b.sound.play#

c8b.sound.play(path, [volume=1.0], [pan=0.0])

Fire-and-forget: loads a sample (.sts) and plays it once.

• Returns: voice handle (integer, -1 on failure)
• Availability: Console (BIOS) and emulator

c8b.sound.stopAll#

c8b.sound.stopAll()

Stops all mixer voices.

• Availability: Console (BIOS) and emulator

c8b.sound.setMasterVolume#

c8b.sound.setMasterVolume(volume)

Master volume.

• Availability: Console (BIOS) and emulator

c8b.sound.getMasterVolume#

c8b.sound.getMasterVolume()

Master volume.

• Returns: number
• Availability: Console (BIOS) and emulator

c8b.sound.getActiveVoiceCount#

c8b.sound.getActiveVoiceCount()

Number of active voices.

• Returns: integer
• Availability: Console (BIOS) and emulator

c8b.sound.setBassBoost#

c8b.sound.setBassBoost(enabled, [gainDb=3])

Output bass boost (-6..+12 dB).

• Availability: Console (BIOS) and emulator

c8b.sound.setWarmth#

c8b.sound.setWarmth(enabled, [amount=128])

Output warmth filter (0-255).

• Availability: Console (BIOS) and emulator

c8b.sound.setAnalogMode#

c8b.sound.setAnalogMode(enabled)

Enables bass boost (+3 dB) and warmth (128) together.

• Availability: Console (BIOS) and emulator

c8b.sound.setPluginGain#

c8b.sound.setPluginGain([gain=1.0])

Gain for native-plugin (emulator core) audio, 0.0-2.0.

• Availability: Console (BIOS) and emulator

c8b.sound.getSpectrum#

c8b.sound.getSpectrum([bands=8], [log])

Spectrum of the mixed output, values 0-255 (1-128 bands). log = true or "log" uses musical band spacing.

• Returns: table of integers
• Availability: Console (BIOS) and emulator

c8b.sound.getLevel#

c8b.sound.getLevel()

Output level 0-255 (VU meter).

• Returns: integer
• Availability: Console (BIOS) and emulator

c8b.sound.getCurrentTime#

c8b.sound.getCurrentTime()

Audio clock in seconds; use for the when argument of synth notes.

• Returns: number
• Availability: Console (BIOS) and emulator

Samples#

c8b.sound.sample.new#

c8b.sound.sample.new(path)

Loads a sample (STS format; ".sts" is appended if missing). Returns nil on failure.

• Availability: Console (BIOS) and emulator
• Note: Loads STS files only; convert WAV/AIFF files with the asset tools.

c8b.sound.sample:getLength#

sample:getLength()

Length in sample frames.

• Returns: integer
• Availability: Console (BIOS) and emulator
• Note: For seconds use getLengthSeconds.

c8b.sound.sample:getLengthSeconds#

sample:getLengthSeconds()

Length in seconds.

• Returns: number
• Availability: Console (BIOS) and emulator

c8b.sound.sample:getSampleRate#

sample:getSampleRate()

Sample rate in Hz.

• Returns: integer
• Availability: Console (BIOS) and emulator

c8b.sound.sample:free#

sample:free()

Frees the sample now.

• Availability: Console (BIOS) and emulator

Sample players#

c8b.sound.sampleplayer.new#

c8b.sound.sampleplayer.new([pathOrSample])

Creates a player from a path (the player owns the loaded sample) or a sample object. Returns nil if loading fails.

• Availability: Console (BIOS) and emulator

local jump = c8b.sound.sampleplayer.new("sfx/jump")
jump:play()

c8b.sound.sampleplayer:play#

player:play([repeatCount=1])

Plays; 0 loops forever.

• Availability: Console (BIOS) and emulator

c8b.sound.sampleplayer:stop#

player:stop()

Stops.

• Availability: Console (BIOS) and emulator

c8b.sound.sampleplayer:pause#

player:pause()

Pauses.

• Availability: Console (BIOS) and emulator

c8b.sound.sampleplayer:resume#

player:resume()

Resumes.

• Availability: Console (BIOS) and emulator

c8b.sound.sampleplayer:isPlaying#

player:isPlaying()

Playing state.

• Returns: boolean
• Availability: Console (BIOS) and emulator

c8b.sound.sampleplayer:setVolume#

player:setVolume(left, [right])

Volume 0.0-1.0; right enables stereo volume.

• Availability: Console (BIOS) and emulator

c8b.sound.sampleplayer:getVolume#

player:getVolume()

Volume.

• Returns: left, right
• Availability: Console (BIOS) and emulator

c8b.sound.sampleplayer:setPan#

player:setPan(pan)

Pan -1.0..1.0.

• Availability: Console (BIOS) and emulator

c8b.sound.sampleplayer:getPan#

player:getPan()

Pan.

• Returns: number
• Availability: Console (BIOS) and emulator

c8b.sound.sampleplayer:setRate#

player:setRate(rate)

Playback rate (1.0 normal).

• Availability: Console (BIOS) and emulator

c8b.sound.sampleplayer:getRate#

player:getRate()

Rate.

• Returns: number
• Availability: Console (BIOS) and emulator

c8b.sound.sampleplayer:setOffset#

player:setOffset(seconds)

Playback position.

• Availability: Console (BIOS) and emulator

c8b.sound.sampleplayer:getOffset#

player:getOffset()

Playback position.

• Returns: number
• Availability: Console (BIOS) and emulator

c8b.sound.sampleplayer:setSample#

player:setSample(sample)

Replaces the sample (nil clears).

• Availability: Console (BIOS) and emulator

c8b.sound.sampleplayer:free#

player:free()

Frees the player now.

• Availability: Console (BIOS) and emulator

File players (streaming)#

c8b.sound.fileplayer.new#

c8b.sound.fileplayer.new([path])

Acquires one of 3 streaming players; with a path loads it (.sts optional). Returns nil when all players are in use, or nil, "cannot open file".

• Availability: Console (BIOS) and emulator
• Note: Streams STS files only; max 3 at once.

local music = c8b.sound.fileplayer.new("music/theme")
music:play(0) -- loop

c8b.sound.fileplayer:load#

fp:load(path)

Loads a file.

• Returns: boolean
• Availability: Console (BIOS) and emulator

c8b.sound.fileplayer:play#

fp:play([repeatCount=1])

Starts; 0 loops forever. Errors with "fileplayer has been released" after an application switch.

• Returns: boolean
• Availability: Console (BIOS) and emulator

c8b.sound.fileplayer:stop#

fp:stop()

Stops.

• Availability: Console (BIOS) and emulator

c8b.sound.fileplayer:pause#

fp:pause()

Pauses.

• Availability: Console (BIOS) and emulator

c8b.sound.fileplayer:isPlaying#

fp:isPlaying()

Playing state.

• Returns: boolean
• Availability: Console (BIOS) and emulator

c8b.sound.fileplayer:getLength#

fp:getLength()

Length in seconds.

• Returns: number
• Availability: Console (BIOS) and emulator

c8b.sound.fileplayer:setOffset#

fp:setOffset(seconds)

Seek.

• Availability: Console (BIOS) and emulator

c8b.sound.fileplayer:getOffset#

fp:getOffset()

Position in seconds.

• Returns: number
• Availability: Console (BIOS) and emulator

c8b.sound.fileplayer:setRate#

fp:setRate(rate)

Playback rate.

• Availability: Console (BIOS) and emulator

c8b.sound.fileplayer:getRate#

fp:getRate()

Rate.

• Returns: number
• Availability: Console (BIOS) and emulator

c8b.sound.fileplayer:setVolume#

fp:setVolume(left, [right], [fadeSeconds=0], [callback], [arg])

Sets or fades volume; callback(fp, arg) runs when the fade ends (immediately when fadeSeconds is 0).

• Availability: Console (BIOS) and emulator

c8b.sound.fileplayer:getVolume#

fp:getVolume()

Volume.

• Returns: left, right
• Availability: Console (BIOS) and emulator

c8b.sound.fileplayer:setFinishCallback#

fp:setFinishCallback(fn, [arg])

fn(fp, arg) when playback ends; called from the runtime after each frame.

• Availability: Console (BIOS) and emulator

c8b.sound.fileplayer:didUnderrun#

fp:didUnderrun()

Whether the stream ran dry.

• Returns: boolean
• Availability: Console (BIOS) and emulator

c8b.sound.fileplayer:setStopOnUnderrun#

fp:setStopOnUnderrun(flag)

Stop instead of waiting when data runs out.

• Availability: Console (BIOS) and emulator

c8b.sound.fileplayer:setBufferSize#

fp:setBufferSize(...)

Accepted and ignored.

• Availability: Console (BIOS) and emulator

c8b.sound.fileplayer:setLoopRange#

fp:setLoopRange(...)

Accepted and ignored.

• Availability: Console (BIOS) and emulator

c8b.sound.fileplayer:setLoopCallback#

fp:setLoopCallback(...)

Accepted and ignored.

• Availability: Console (BIOS) and emulator

Synth#

c8b.sound.synth.new#

c8b.sound.synth.new([waveform])

Acquires one of 16 synth voices (nil when all are used).

• Availability: Console (BIOS) and emulator

local s = c8b.sound.synth.new(c8b.sound.kWaveSquare)
s:setADSR(0, 0.05, 0.5, 0.1)
s:playNote("C4", 1, 0.25)

c8b.sound.synth:playNote#

synth:playNote(pitch, [volume=1], [length], [when])

pitch in Hz or a note name ("C4", "F#5"); length in seconds (omitted = until noteOff); when is c8b.sound.getCurrentTime()-based.

• Returns: true
• Availability: Console (BIOS) and emulator

c8b.sound.synth:playMIDINote#

synth:playMIDINote(note, [volume=1], [length], [when])

Like playNote with a MIDI note number or name.

• Returns: true
• Availability: Console (BIOS) and emulator

c8b.sound.synth:noteOff#

synth:noteOff()

Starts the release phase.

• Availability: Console (BIOS) and emulator

c8b.sound.synth:stop#

synth:stop()

Stops immediately.

• Availability: Console (BIOS) and emulator

c8b.sound.synth:isPlaying#

synth:isPlaying()

Playing state.

• Returns: boolean
• Availability: Console (BIOS) and emulator

c8b.sound.synth:setWaveform#

synth:setWaveform(kWave*)

Waveform.

• Availability: Console (BIOS) and emulator

c8b.sound.synth:setADSR#

synth:setADSR(attack, decay, sustain, release)

Envelope (seconds, sustain level).

• Availability: Console (BIOS) and emulator

c8b.sound.synth:setAttack#

synth:setAttack(s)

Attack.

• Availability: Console (BIOS) and emulator

c8b.sound.synth:setDecay#

synth:setDecay(s)

Decay.

• Availability: Console (BIOS) and emulator

c8b.sound.synth:setSustain#

synth:setSustain(level)

Sustain.

• Availability: Console (BIOS) and emulator

c8b.sound.synth:setRelease#

synth:setRelease(s)

Release.

• Availability: Console (BIOS) and emulator

c8b.sound.synth:setLegato#

synth:setLegato(flag)

Legato.

• Availability: Console (BIOS) and emulator

c8b.sound.synth:setVolume#

synth:setVolume(left, [right])

Volume.

• Availability: Console (BIOS) and emulator

c8b.sound.synth:getVolume#

synth:getVolume()

Volume.

• Returns: left, right
• Availability: Console (BIOS) and emulator

c8b.sound.synth:setFinishCallback#

synth:setFinishCallback(fn, [arg])

Called when a note finishes.

• Availability: Console (BIOS) and emulator

c8b.sound.synth:copy#

synth:copy()

New synth with the same waveform and volume (envelope not copied).

• Returns: synth
• Availability: Console (BIOS) and emulator

c8b.sound.synth:setAmplitudeMod#

synth:setAmplitudeMod(...)

Accepted and ignored.

• Availability: Console (BIOS) and emulator

c8b.sound.synth:setFrequencyMod#

synth:setFrequencyMod(...)

Accepted and ignored.

• Availability: Console (BIOS) and emulator

c8b.sound.synth:setParameter#

synth:setParameter(...)

Accepted and ignored.

• Availability: Console (BIOS) and emulator

c8b.sound.synth:setParameterMod#

synth:setParameterMod(...)

Accepted and ignored.

• Availability: Console (BIOS) and emulator

c8b.sound.synth:setEnvelopeCurvature#

synth:setEnvelopeCurvature(...)

Accepted and ignored.

• Availability: Console (BIOS) and emulator

c8b.sound.synth:setWavetable#

synth:setWavetable(...)

Accepted and ignored.

• Availability: Console (BIOS) and emulator

Waveform constants#

c8b.sound.kWaveSquare#

c8b.sound.kWaveSquare = 0

Synth waveform.

• Availability: Console (BIOS) and emulator

c8b.sound.kWaveTriangle#

c8b.sound.kWaveTriangle = 1

Synth waveform.

• Availability: Console (BIOS) and emulator

c8b.sound.kWaveSine#

c8b.sound.kWaveSine = 2

Synth waveform.

• Availability: Console (BIOS) and emulator

c8b.sound.kWaveNoise#

c8b.sound.kWaveNoise = 3

Synth waveform.

• Availability: Console (BIOS) and emulator

c8b.sound.kWaveSawtooth#

c8b.sound.kWaveSawtooth = 4

Synth waveform.

• Availability: Console (BIOS) and emulator

c8b.sound.kWavePOPhase#

c8b.sound.kWavePOPhase = 5

Synth waveform.

• Availability: Console (BIOS) and emulator

c8b.sound.kWavePODigital#

c8b.sound.kWavePODigital = 6

Synth waveform.

• Availability: Console (BIOS) and emulator

c8b.sound.kWavePOVosim#

c8b.sound.kWavePOVosim = 7

Synth waveform.

• Availability: Console (BIOS) and emulator