This README is the one indexed from the repository at its latest ref, not from the tag for this version.

raudio.cr

:sound: raudio - a simple audio library based on miniaudio - for Crystal

Installation

Add to shard.yml:

dependencies:
  raudio:
    github: kojix2/raudio.cr

Run shards install. The native library builds automatically.

Usage

Audio device

require "raudio"

Raudio::AudioDevice.open do
  Raudio::AudioDevice.master_volume = 0.8
end

Sound playback

Raudio::AudioDevice.open do
  sound = Raudio::Sound.load("effect.wav")
  sound.volume = 0.5
  sound.play

  while sound.playing?
    sleep 10.milliseconds
  end
end

Music streaming

Raudio::AudioDevice.init

music = Raudio::Music.load("background.mp3")
music.volume = 0.8
music.looping = false  # Disable looping (enabled by default)
music.play

loop do
  music.update
  break unless music.playing?
  sleep 10.milliseconds
end

Raudio::AudioDevice.close

Wave data

Raudio::AudioDevice.open do
  wave = Raudio::Wave.load("audio.wav")
  sound = Raudio::Sound.from_wave(wave)
  sound.play
  wave.export("output.wav")
end

Resource Management

Resources should be explicitly released when done, or use the block form for automatic cleanup.

Recommended patterns:

# Block form (automatic cleanup)
Raudio::Sound.load("effect.wav") do |sound|
  sound.play
end

# Manual release
sound = Raudio::Sound.load("effect.wav")
begin
  sound.play
ensure
  sound.release  # or sound.close
end

Finalizers are provided as a fallback but explicit cleanup is recommended.

Playback model (practical)

• Non-blocking: Sound#play / Music#play return immediately. Mixing/output is done on a separate audio thread (miniaudio).
• Streaming: Call Music#update regularly (e.g. once per frame/tick) to refill the buffer and avoid underruns/stutter.
• Threading: AudioDevice lifetime operations are synchronized, and nested/concurrent AudioDevice.open blocks are reference-counted. Individual Sound, Music, Wave, and AudioStream handles should be owned from one audio/game context.
• ExecutionContext: With Fiber::ExecutionContext::Parallel, prefer sending audio commands through a Channel to a dedicated owner fiber or ExecutionContext::Isolated loop. This keeps resource release, Music#update, and playback state changes serialized without adding broad locks to every audio call.
• Callbacks: AudioStream callbacks/processors run from the audio backend thread. Keep them short and synchronize any shared application data yourself.
• Device lifetime: After AudioDevice.init, the device keeps running until AudioDevice.close. With AudioDevice.open, the device closes when the last active open block exits.

Supported formats

WAV, OGG, MP3, FLAC, QOA, XM, MOD

API

• Raudio::AudioDevice - audio device management
• Raudio::Sound - short audio clips
• Raudio::Music - streaming audio
• Raudio::Wave - raw waveform data
• Raudio::AudioStream - custom streaming

Low-level C bindings: Raudio::LibRaudio

API Documentation

Development

git clone --recursive https://github.com/kojix2/raudio.cr # submodule
make -C ext        # build native library
crystal spec       # run tests
crystal build examples/simple_sound.cr
./simple_sound     # one of the two sounds will play

License

MIT

Dependencies (bundled single-header/native libraries):

• raudio (C library) – zlib
  • miniaudio – Public Domain or MIT-0
  • dr_wav – Public Domain or MIT-0
  • dr_mp3 – Public Domain or MIT-0
  • dr_flac – Public Domain or MIT-0
  • stb_vorbis – Public Domain or MIT
  • qoa – MIT
  • jar_xm – WTFPL v2 – (included in source)
  • jar_mod – WTFPL v2 – (included in source)

Summary: Project code is MIT, bundled raudio is zlib, and all other bundled dependencies are permissive (Public Domain, MIT-0, MIT, WTFPL v2) with no copyleft obligations.