AudioCue-maven

KO | EN

gitlite — search

#python #java #python3 #arduino #golang #machine-learning #rust #html #flask #javascript #seismology #nodejs

★ 43 Open GitHub ↗

A Java audio-playback class, modeled on javax.sound.sampled.Clip, enhanced with concurrent playback and dynamic handling of volume, pan and frequency. Maven version.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# AudioCue-maven
*AudioCue* is a Java audio-playback class, modeled on 
[javax.sound.sampled.Clip](https://docs.oracle.com/en/java/javase/17/docs/api/java.desktop/javax/sound/sampled/Clip.html), 
enhanced with concurrent playback capabilities and with dynamic handling of volume, 
pan and frequency. Included in the library is an audio mixing tool for merging the output
of multiple *AudioCues* into a single line out.

The project is now [published and available on Maven.org](https://search.maven.org/artifact/com.adonax/audiocue).
Starting from an earlier project, unit tests were added, and a more rigorous API documentation written. Over the course of making those changes, some errors and shortcomings were uncovered and corrected. The changes were extensive enough that this project 
was given a starting release version of 2.0.0. The [previous version](https://github.com/philfrei/AudioCue)
is no longer being maintained. The current Maven version (as of June, 2023) is 2.1.0.

### How to add AudioCue to your Java project

The best way to make use of **AudioCue** is with the Maven build tool, listing *AudioCue* as a
dependency. To use *AudioCue* as a Maven dependency, add the following to your project's POM file.

```xml
    <dependencies>  
        <dependency>
            <groupId>com.adonax</groupId>
            <artifactId>audiocue</artifactId>
            <version>2.1.0</version>
        </dependency>
    </dependencies>
```

When used in this way, source code and Javadocs documentation will automatically be linked.

Another option is to fork this project and clone it to your local development environment. From there, 
executing Maven's *install* command will put the library into your local Maven repository. Alternatively, 
you can directly make use of the jar file that is created in the **/target** subdirectory via the 
*package* command by adding this jar file to your project's classpath. Lastly, since there are only a few 
files, you can simply copy these files directly into your project. Just be sure, if you do, to edit the
*package* lines of the files to appropriately reflect their new file locations.

The library jar, as well as source and documentation jars are [publicly available at
the Maven site](https://repo1.maven.org/maven2/com/adonax/audiocue/2.1.0/) for downloading if you do not wish to use Maven as the build tool.

### Basic playback (for "fire-and-forget" use)

Code fragments:

```java
    // Recommended: define as an instance variable.
    AudioCue myAudioCue;

//////
    // Recommended: preload one time only.
    // This example assumes "myAudio.wav" is located in src/main/resources folder
    // of a Maven project.    
    URL url = this.getClass().getResource("/myAudio.wav");
    // The following allows up to 4 concurrent playbacks.
    AudioCue myAudioCue = AudioCue.makeStereoCue(url, 4); 
    myAudioCue.open();

//////
    // Recommended: the play() method should be called on a preloaded 
    // instance variable. Reloading or reopening prior for successive plays
    // will add processing latency to no practical purpose.
    myAudioCue.play();  
    // See API for parameters for vol, pan, speed and number of repetitions.
    // NOTE: The play method returns immediately. Playback occurs on a
    // daemon thread, and will not hold a program open.

//////
    // To release resources when sound is no longer needed
    myAudioCue.close();
```

The following example plays an *AudioCue* via a Swing Button.

```java
	public class AudioCuePlayExample {
		public static void main(String[] args) {
			EventQueue.invokeLater(new Runnable(){
				public void run()
				{	
					DemoFrame frame = new DemoFrame();
					frame.pack;
					frame.setVisible(true);
				}
			});
		}
	}
    
	class DemoFrame extends JFrame {
		private AudioCue bell;
		public DemoFrame() {
			JPanel panel = new JPanel();
			JButton button = new JButton("Play sound");
			button.addActionListener(new ActionListener() {
				public void actionPerformed(ActionEvent e) {
					bell.play();
				}
			});
			panel.add(button);
			add(panel);
    
			// Set up the AudioCue
			URL url = this.getClass().getResource("/bell.wav");
			try {
				bell = AudioCue.makeStereoCue(url, 6);
				bell.open();
			} catch (UnsupportedAudioFileException | IOException | LineUnavailableException e) {
				e.printStackTrace();
			}
		}
	}
```

### Usage: dynamic controls

To dynamically change the playback of a sound, we need to identify
the playback *instance*. Each playback instance has its own identifier,
an `int` ranging from 0 to the number of preallocated concurrent instances minus one.
Identifiers are obtained from a pool of available instances. An instance is reserved
and its identifier is returned when the *play* method is executed:

int instanceID = myAudioCue.play();

You can also reserve an *instance* and obtain its identifier from the pool of available 
instances as follows:

int instanceID = myAudioCue.obtainInstance();

An *instance* can be started, stopped, or released by including the instance identifier 
as an argument:

```java
    myAudioCue.start(instanceID);
    myAudioCue.stop(instanceID);
    myAudioCue.releaseInstance(instanceID);
```

*Releasing* returns the instance identifier to the pool of available instances.

An important distinction exists between instances obtained from one of the 
`play` methods versus the `obtainInstance()` method.
The default value of the property `recycleWhenDone` for an instance 
obtained from `play()` is `true`. Thus, when playback completes, the instance
and its identifier will automatically be returned to the pool of available instances.

An instance arising from `obtainInstance()` has the property `recycleWhenDone`
set to `false`. In this case, when playback completes, the instance identifier
is *not* returned to the pool of available instances, and the instance remains 
receptive to additional commands. In this case, after playing through to the
end, the frame position will be that of the end of the audio-data file, and,
like a `Clip` that has played through, will require repositioning and restarting
for further plays.

Properties that can be altered for an instance include the following:

```java
    //*volume*: 
    myAudioCue.setVolume(instanceID, value); // double ranging from 0 (silent)
                                             // to 1 (full volume)
    //*panning*: 
    myAudioCue.setPan(instanceID, value); // double ranging from -1 (full left)
                                          // to 1 (full right)
    //*speed of playback*: 
    myAudioCue.setSpeed(instanceID, value); // value is a factor that is  
                                  // multiplied against the normal playback rate, e.g.,
                                  // 2 will double playback speed, 0.5 will halve it 
    
    //*position* (cannot be changed while instance is playing):
    myAudioCue.setFramePosition(instanceID, value);  // position in frames
    myAudioCue.setMillisecondPosition(instanceID, value); // position in milliseconds
    myAudioCue.setsetFractionalPosition(instanceID, value); 
                                        // value is a decimal fraction of the cue length
                                        // where 0 = start, 1 = end
    //*other*:                                                
    myAudioCue.setLooping(handle, value); // number of additional times the cue will replay
                                          // -1 = infinite looping
    myAudioCue.setRecycleWhenDone(handle, value); // boolean that determines whether or 
                                        // not the instance will be returned to the
                                        // pool of available instances when the cue
                                        // plays to completion                                
```

### Usage: output configuration

Output configuration occurs within the *AudioCue*'s `open` methods. The 
default configuration employs *javax.sound.sampled.AudioSystem*'s default
`Mixer` and a `SourceDataLine` set with a 1024-frame buffer and the highest
thread priority. A high thread priority should not affect performance of 
the rest of an application, as audio threads normally spend the vast majority 
of their time in a blocked state. The buffer size can be set to 
optimize the balance between latency and dropouts. Incidents of dropouts 
are usually lessened by increasing the buffer size.

You can override the defaults by using an alternate form of the `open()` method. For 
example:

```java
    myAudioCue.open(mixer, bufferFrames, threadPriority);
```

Each `AudioCue` can have its own configuration, and will output on its own `SourceDataLine` line.

### Usage: outputting via *AudioMixer*
Most operating systems will support multiple, concurrently playing `SourceDataLine` 
streams. But if desired, the streams can be merged into a single output line using 
`audiocue.AudioMixer`. This is accomplished by 
providing an `AudioMixer` instance as an argument to the `AudioCue` **open()** method:

```java
    myAudioCue.open(myAudioMixer);
```

Internally, this method adds the `AudioCue` to the `AudioMixer` using the interface 
*AudioMixerTrack*. If an `AudioCue` is a track on an `AudioMixer`, the `AudioCue` 
method **close()** will automatically remove the track from the `AudioMixer`.

```java
    myAudioCue.close();
```

The `AudioMixer` is configured, upon instantiation, with a default 
`javax.sound.sampled.Mixer`, with a buffer size of 8192 frames, and 
with the highest thread priority. Alternate values can be provided 
at instantiation.

All `AudioCues` routed through an `AudioMixer` will use the 
`AudioMixer's` configuration properties. Requests to add or remove `AudioCues` 
from the `AudioMixer` are concurrency safe but with a latency equal to the time
that elapses until the buffer iterates.

In the following somewhat artificial example, we create and start an 
`AudioMixer`, add an `AudioCue` track, play the cue, then shut it all down.

```java
    AudioMixer audioMixer = new AudioMixer();
    audioMixer.start();
    // At this point, AudioMixer will create and start a runnable and will
    // actively output 'silence' (zero values) on its SourceDataLine. 
    
    URL url = this.getClass().getResource("myAudio.wav");
    AudioCue myAudioCue = AudioCue.makeStereoCue(url, 1); 
    myAudioCue.open(mixer); 
    // The open method automatically adds the AudioCue to
    // the AudioMixer.
    
    myAudioCue.play();
    Thread.sleep(2000); // For purposes of the demo only, to hold the program open to give the AudioCue time
                        // to play to completion (assumes cue is shorter than 2 seconds).
    myAudioCue.close(); // will remove AudioCue from the mix                    
    audioMixer.stop();  // AudioMixer will stop outputting and will
                        // close the runnable in an 'orderly' manner.
```

Reminder, this is an artificial example: best practice is to initialize and 
open an `AudioCue` only once, and to then reuse the `AudioCue` for multiple playbacks.
Also, this example uses `Thread.sleep()` to prevent the program from advancing and 
closing before the cue finishes playing. The reason for this is that `AudioMixer`, like 
`AudioCue`, launches a *daemon* thread internally for playback, so a playing instance will 
*not* prevent a program from closing once all the program instructions are completed. Unlike this 
example, an `AudioCue` is more typically called by a GUI that remains open, or from a long-running
program, and is able to complete playing without the program closing. In this more common 
use case, pausing the thread that has the *play()* method is quite unnecessary.

### Additional functionality and examples
Additional examples and test files for *AudioCue* are available in the project [audiocue-tutorial-examples](https://github.com/philfrei/audiocue-tutorial-examples). I have a series of tutorial videos in the works which will feature the programs in this project. As they are completed (assuming I'm able to do this) links will be posted here.

There is another accompanying project [audiocue-demo](https://github.com/philfrei/audiocue-demo). However, *this code is not entirely compatible with version 2.0.0 and beyond*, and in some cases will require tinkering in order to work. This project is now obsolete, and is not being maintained.

Functionality illustrated in *audiocue-tutorial-examples* includes the following:
- a working basic example of fire-and-forget play;
- the real time response of an `AudioCue` to `JSlider`-driven changes to volume, panning and pitch;
- the use of scaling functions for enhanced control of volume and panning;
- the utilization of `AudioCueListener`, with an example where an animation reacts to the start and the completion of a playback;
- the mixing of multiple `Audiocues` in an `AudioMixer`, creating an aleatory soundscape; 
- the loading of an `AudioCue` directly with PCM data and other PCM-related utilities;
- the playback of a sound cue from a file rather than an `AudioCue` in the `AudioMixer` by implementing the `AudioMixerTrack` interface.

## Contribute to project
Please check the *Issues* area for entering or working on suggestions.

## Donate
If *AudioCue* has been helpful, it would be great to hear (by email or a 
"buy me a coffee/beer" donation).

## Contact Info

Programmer/Sound-Designer/Composer: Phil Freihofner

URL: http://adonax.com

Email: phil AT adonax.com

If using *StackOverflow* for a question, chances are highest
that I will see it if you include the tag *javasound*.

I'm happy to list links for any applications that use *AudioCue*.

Suggestions for the improvement of this README or any other aspect of the `AudioCue` are
appreciated.

AudioCue-maven

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README