search

JorenSix / TarsosDSP

A Real-Time Audio Processing Framework in Java
http://0110.be/tag/TarsosDSP
GNU General Public License v3.0
1.97k stars 472 forks source link

readme

!https://github.com/JorenSix/TarsosDSP/actions/workflows/gradle.yml/badge.svg(TarsosDSP build status)!

h1. TarsosDSP

TarsosDSP is a Java library for audio processing. Its aim is to provide an easy-to-use interface to practical music processing algorithms implemented, as simply as possible, in pure Java and without any other external dependencies. The library tries to hit the sweet spot between being capable enough to get real tasks done but compact and simple enough to serve as a demonstration on how DSP algorithms works.

TarsosDSP features an implementation of a percussion onset detector and a number of pitch detection algorithms: YIN, the Mcleod Pitch method and a “Dynamic Wavelet Algorithm Pitch Tracking” algorithm. Also included is a Goertzel DTMF(Dual tone multi frequency) decoding algorithm, a time stretch algorithm (WSOLA), resampling, filters, simple synthesis, some audio effects, and a pitch shifting algorithm.

To show the capabilities of the library, "TarsosDSP example applications":http://0110.be/tag/TarsosDSP are available. Head over to the "TarsosDSP release directory":http://0110.be/releases/TarsosDSP/ for freshly baked binaries and code smell free (that is the goal anyway), oven-fresh sources.

h2. Quickly Getting Started with TarsosDSP

The source code of TarsosDSP is compatible with Java 11.

Add this to your build.gradle file:

repositories {
    maven {
        name = "TarsosDSP repository"
        url = "https://mvn.0110.be/releases"
    }
}
dependencies {
    implementation 'be.tarsos.dsp:core:2.5'
    implementation 'be.tarsos.dsp:jvm:2.5'
}

Add this to your pom.xml file:


  be.0110.repo-releases
  0110.be repository
  https://mvn.0110.be/releases


  be.tarsos.dsp
  core
  2.5


  be.tarsos.dsp
  jvm
  2.5

h2. Citing TarsosDSP

Some information about TarsosDSP can be found in the paper "TarsosDSP, a Real-Time Audio Processing Framework in Java":http://0110.be/files/attachments/411/aes53_tarsos_dsp.pdf, by Joren Six, Olmo Cornelis, and Marc Leman, in Proceedings of the 53rd AES Conference (AES 53rd), 2014. If you use TarsosDSP in academic research, please cite this paper.

bc. @inproceedings{six2014tarsosdsp, author = {Joren Six and Olmo Cornelis and Marc Leman}, title = {{TarsosDSP, a Real-Time Audio Processing Framework in Java}}, booktitle = {{Proceedings of the 53rd AES Conference (AES 53rd)}}, year = 2014 }

h3. Building TarsosDSP with Gradle

To build TarsosDSP from source the @gradlew@ script should get you started. The following commands fetch the source and builds the library: 

git clone --depth 1 https://JorenSix@github.com/JorenSix/TarsosDSP.git
cd TarsosDSP
./gradlew build

h2. Source Code Organization & Developing

The library is separated into three module folders: 1) the main core functionality is found in @core/src/main/java@, TarsosDSP example applications are found in @examples/src/main/java@, JVM audio I/O in @jvm/examples/src/main@.

h2. TarsosDSP Examples

To see TarsosDSP in action thre are a number of examples. These examples have either a graphical user interface or a command line interface. To see a window in which you can start all GUI examples the jar file needs to be started without arguments:

gradle shadowJar
java -jar examples/build/libs/examples-all.jar

To use the command line examples, execute the jar with the example name as first argument. For example @java -jar examples/build/libs/examples-all.jar feature_extractor pitch audio.mp3@ starts the @feature_extractor@ application to extract pitch from an audio file.

To get a list of all command line examples: @java -jar examples/build/libs/examples-all.jar list@

h2. Credits

"TarsosDSP":http://0110.be/tag/TarsosDSP was developed at "University College Ghent, School of Arts":http://schoolofartsgent.be between 2009 and 2013, from late 2013 the project is supported by "University Ghent, IPEM":http://www.ipem.ugent.be.

The TarsosDSP borrows algorithms from various other libraries or research paper. Below a complete list of credits can be found.

h2. Changelog

Version 1.0
2012-04-24
First release which includes several pitch trackers and a time stretching algorithm, amongst other things. Downloads and javadoc API can be found at the "TarsosDSP release directory":http://0110.be/releases/TarsosDSP/
Version 1.1
2012-06-4
Changed how the audio dispatcher stops. Added StopAudioProcessor. Added FastYin implementation by Matthias Mauch Added AMDF pitch estimator by Eder Souza
Version 1.2
2012-08-21
Modified the interface of PitchDetector to return a more elaborate result structure with pitch, probability and a boolean "is pitched". Added an implementation of an envelope follower or envelope detector.
Version 1.3
2012-09-19
TarsosDSP can do audio synthesis now. The first simple unit generators are included in the library. It has a new audio feature extraction feature, implemented in the FeatureExtractor example. Added ASCII-art to the source code (this is the main TarsosDSP 1.3 feature).
Version 1.4
2012-10-31
Included a resample feature, implemented by libresample4j. Together with the WSOLA implementation, it can be used for pitch shifting (similar to Phase Vocoding). A pitch shifting example (both with a CLI and a UI) is added in the 1.4 version of the TarsosDSP library as well.
Version 1.5
2013-04-30
Converted TarsosDSP to maven. This is known as the Malaryta-release. The "Malaryta" release is provided to you by "RikkiMongoose":http://github.com/rikkimongoose (idea, documents, git things) and "Ultar":http://github.com/ultar (converting to maven, refactoring). Malaryta is the capital of Malaryta Raion, Brest Region in the Republic of Belarus. Both of developers spent their childhood in Brest, and think that title Malaryta is as strange as Ubuntu or Whistler. The 1.5 release also includes various FFT window functions from the cool "Minim project":http://code.compartmental.net/tools/minim/ by Damien Di Fede.
Version 1.6
2013-06-12
This release features practical onset and beat detection algorithms. A complex domain onset detection and a spectral flux onset detection algorithm are added. This release also includes a way to guess a beat from onsets. Parts of the "BeatRoot system":http://www.eecs.qmul.ac.uk/~simond/beatroot/, by Simon Dixon, are included to this end. Also included in this release is an implementation of the Constant-Q transform.
Version 1.7
2013-10-08
This release adds the ability to extract the MFCC from an audio signal. Also an example of the Constant-Q transform is added, together with a reusable visualization class library. The build system is reverted back to pure ANT
Version 1.8
2014-04-10
With this release it is possible to extract spectral peaks from an FFT and get precise frequency estimates using phase info. An example application called SpectralPeaks is added as well.
Version 1.9
2014-08-10
This release includes a Haar Wavelet Transform and an example of an audio compression algorithm based on Haar Wavelets. It also includes a significant change in package naming.
Version 2.0
2014-08-13
The 2.0 version is worth the major version update since it offers out-of-the-box support for Android. The release has no more dependencies on the parts of the java runtime that are not included in Android. To offer this support some packages have been shifted around. The code that does I/O is dependent on the runtime (JVM or Dalvik) and is abstracted using the @be.tarsos.dsp.io@ package.
Version 2.1
2015-03-03
The 2.1 version restructures some of the source files. All source can now be found in src. The ant build file is adapted to reflect this change. This version also includes an STFT pitch shifter. There was already a time domain pitch shifter included and now a frequency domain implementation is present as well.
Version 2.2
2015-03-03
The 2.2 version includes a new @AudioDispatcher@. It has been reviewed toroughly and now behaves predictably for the first and last buffers as well. To prevent compatibility issues the version has been changed.
Version 2.3
2015-09-01
The 2.3 version includes improved Android support: "audio decoding on Android":http://0110.be/posts/Decode_MP3s_and_other_Audio_formats_the_easy_way_on_Android can be done using a provided, statically compiled ffmpeg binary. The ffmpeg decoding functionality for JVM has been improved as well. If no ffmpeg executable is found it is downloaded automatically from "here":http://0110.be/releases/TarsosDSP/TarsosDSP-static-ffmpeg.
Version 2.4
2016-12-01
Some small changes to the pipe decoder. Now it is possible to set a start and duration for the incoming decoded audio from ffmpeg.
Version 2.5
2023-01-09
Changes to the build system: moved from ant to gradle. Better documentation, testing and CI with github actions. Release of maven packages.