Audio Output with Harmony

Harmony is an independent audio server system. It is capable of creating complex audio routing systems and also provides a variety of audio effects, outputs, and inputs out of the box. Please see its documentation for more details. In this section we briefly outline how the integration system trial-harmony can help you bridge the gap with Trial.

First, you will want to inherit from org.shirakumo.fraf.trial.harmony:settings-main. This main subclass will take care of initializing and finalizing the audio server when the game is started up, and will also automatically interpret the audio-related settings. If you would like to customise how the server builds its pipeline or provide other customisations outside the settings, you can do so with server-initargs:

(defmethod org.shirakumo.fraf.trial.harmony:server-initargs append ((main main))
  '(:effects ((mixed:biquad-filter :filter :lowpass :name :lowpass))))

See harmony:make-simple-server for more information on accepted initargs.

Second, you will want to pre-load sound files. The trial-harmony system provides assets and resources to encapsulate the Harmony objects you need to manage. To import sounds and simple music tracks, use audio-file to define your assets:

(define-asset (my-pool my-sound) audio-file
  #p"sound.mp3")

You can also use sound-bank and input a number of effect files. When playing the sound, Trial will then randomly pick between one of the sounds, which helps avoid repetition. If you want to use Harmony's environments system to do horizontal mixing, define the environment using the org.shirakumo.fraf.trial.harmony:environment asset.

Before a sound can be played, it must be "staged". It is sufficient to associate stage with any entity present in the associated scene:

(defmethod stage :after ((my-entity my-entity) (area staging-area))
  (stage (// 'my-pool 'my-sound) area))

Finally, in order to play back the sound, just access its resource and call play:

(org.shirakumo.fraf.harmony:play (// 'my-project 'sound))

Note that each asset generates exactly one voice instance. You thus cannot play the same sound twice at the same time. Usually this is not an issue, as you can pass :reset T to play to restart the effect instead. In the rare cases where it is vital that the sound effect be played back multiple times simultaneously, you can either define the same sound as multiple assets, or use close before playing it back.