# Audio in jME3

There are two ways to handle audio data: Short audio files are to be stored entirely in memory, while long audio files (music) is streamed from the hard drive as it is played.

Place audio files in the `assets/Sound/` directory of your project. jME3 supports Ogg Vorbis (.ogg) and Wave (.wav) formats.

## Creating Audio Nodes: Streamed or Buffered

The main class to look at is `com.jme3.audio.AudioNode`.

- Buffered: By default, a new audio node is buffered. This means jME3 loads the whole file into memory before playing. You create a buffered sound by setting the boolean to false, or using no boolean at all:

      AudioNode boom = new AudioNode(assetManager, "Sound/boom.wav");

- Streamed: If it is a long file, you stream the audio, that means, you load and play in parallel until the sound is done. You create a streamed sound by setting the boolean to true:

      AudioNode music = new AudioNode(assetManager, "Sound/music.wav", true);

## Getting AudioNode Properties

AudioNode Method | Usage
--- | ---
getStatus() | Returns either Status.Playing, Status.Stopped, or Status.Paused.
getVolume() | Returns the volume.
getPitch() | Returns the pitch.

There are other obvious getters to poll the status of corresponding setters below.

## Setting AudioNode Properties

AudioNode Method | Usage
--- | ---
setVolume(1) | Sets the volume gain. 1 is the default volume, 2 is twice as loud, etc. 0 is silent/mute.
setPitch(1) | Makes the sound play in a higher or lower pitch. Default is 1. 2 is twice as high, .5f is half as low.

AudioNode Method | Usage
--- | ---
setLooping(false) | Configures the sound so that, if it is played, it plays once and stops. This is the default.
setLooping(true) | Configures the sound so that, if it is played, it plays repeats from the beginning, until stop() or pause() are called. Good for ambient background noises. Does not work for streamed sounds!
setPositional(false) setDirectional(false) | All 3D effects switched off. This sound is global and comes from everywhere. Good for environmental ambient sounds and background music.
setTimeOffset(0.5f) | Start playing the sound after waiting the given amount of seconds. Default is 0.
setMaxDistance(100f) | Maximum distance the sound can be heard, in world units. Default is 20.

AudioNode Method | Usage
--- | ---
setPositional(true) setLocalTranslation(…) | Activates 3D audio: The sound appears to come from a certain position, where it is loudest. Position the AudioNode in the 3D scene, or move it with mobile players or NPCs.
setReverbEnabled(true) | A 3D echo effect that only makes sense to use with positional AudioNodes. The reverb effect is influenced by the environment that the audio renderer is in. See "Setting Environment Properties" below.

AudioNode Method | Usage
--- | ---
setDirectional(true) setDirection(…) | Activates 3D audio: This sound can only be heard from a certain direction. Specify the direction and angle in the 3D scene if you have setDirectional() true. Use this to restrict noises that should not be heard, for example, through a wall.
setInnerAngle() setOuterAngle() | Set the angle in degrees for the directional audio. The angle is relative to the direction. Note: By default, both angles are 360° and the sound can be heard from all directions!

## Play, Pause, Stop

You play, pause, and stop a node called myAudioNode by using the respective of the following three methods:

    myAudioNode.play();

    myAudioNode.pause();

    myAudioNode.stop();

Note: Whether an Audio Node plays continuously or only once, depends on the Loop properties you have set above!

You can also start playing an instance of this AudioNode. Use the playInstance() method if you need to play the same AudioNode multiple times, possibly simulatenously. Note that changes to the parameters of the original AudioNode do not affect the instances that are already playing!

    myAudioNode.playInstance();

## The Listener

The default listener object is the user's ear in the scene. If you use positional audio, you have to move the listener with the player: For example, for a first-person player, you move the listener with the camera. For a third-person player, you move the listener with the player avatar Geometry.

      @Override
      public void simpleUpdate(float tpf) {
        // keep the audio listener moving with the camera
        listener.setLocation(cam.getLocation());
        listener.setRotation(cam.getRotation());
      }

## Setting Environment Properties

Optionally, You can choose from the following environmental presets from `com.jme3.audio.Environment`. This presets influence subtle echo effects that evoke associations of different environments in your users. You use it together with setReverbEnabled(true) mentioned above.

Environment | density | diffusion | gain | gainHf | decayTime | decayHf | reflGain | reflDelay | lateGain | lateDelay
--- | --- | --- | --- | --- | --- | --- | --- | --- | --- | ---
Garage | 1.00f | 1.0f | 1.0f | 1.00f | 0.90f | 0.5f | 0.751f | 0.0039f | 0.661f | 0.0137f
Dungeon | 0.75f | 1.0f | 1.0f | 0.75f | 1.60f | 1.0f | 0.950f | 0.0026f | 0.930f | 0.0103f
Cavern | 0.50f | 1.0f | 1.0f | 0.50f | 2.25f | 1.0f | 0.908f | 0.0103f | 0.930f | 0.0410f
AcousticLab | 0.50f | 1.0f | 1.0f | 1.00f | 0.28f | 1.0f | 0.870f | 0.0020f | 0.810f | 0.0080f
Closet | 1.00f | 1.0f | 1.0f | 1.00f | 0.15f | 1.0f | 0.600f | 0.0025f | 0.500f | 0.0006f

Activate the preset with setEnvironment(). E.g. in a dungeon environment:

    audioRenderer.setEnvironment(new Environment.Dungeon));

A sound engineer can create a custom `com.​jme3.​audio.Environment` object and specify custom environment factors. You can find many examples of audio environment presets here. Activate your custom environment settings in the Environment constructor:

    audioRenderer.setEnvironment(
            new Environment( density, diffusion, gain, gainHf, decayTime, decayHf,
                    reflGain, reflDelay, lateGain, lateDelay ) );

You can find more info about OpenAL and its advanced features here:
. It depends on the hardware whether audio effects are supported (if not, you get the message `OpenAL EFX not available! Audio effects won't work.`)

sound, documentation, environment

view online version