adds mp3 support and refactors library api

Author: delthas

README.md

@@ -1,16 +1,15 @@
 # JavaMP3
 
-**Currently only supports MP1 and MP2, see Status below. Support for MP3 is planned.**
+**Currently supports MPEG-1 Layer I/II/III (that is, most MP1, MP2, and MP3 files)**
 
 ## Introduction
 
-JavaMP3 is a lightweight and fast API for decoding MP1, MP2, and MP3 files.
+JavaMP3 is a lightweight (minimalist) and fast API for decoding MP1, MP2, and MP3 files.
 
 This API lets you:
 - Decode MPEG-1/2/2.5 Layer I/II/III data (that is MP1, MP2, and MP3)
-- Get a javax.sound.sampled.AudioInputStream to easily create a Clip from the decoded data and use the javax.sound.sampled API
+- Get a javax.sound.sampled.AudioFormat to easily use the javax.sound.sampled API and play back the decoded data.
 - Get the decoded raw bytes in the format OpenAL takes so you can directly feed an OpenAL buffer with the decoded data
-- Decode the data from several types of input such as InputStream, Path, byte[], byte[] with length and offset
 
 ## Install
 
@@ -29,39 +28,60 @@ JavaMP3 requires Java >= 8 to run. You can get this library using Maven by addin
 
 ## Quick example
 
-This library is object-oriented: you can use one of the several static functions in the Sound class to get a Sound object, and then call methods on it to get data and metadata. Let's have a look at how to interact with the library.
+The only public class in this library is the Sound class. It is simply an InputStream that return decoded PCM sound samples as you read from the stream, decoded from the specified underlying stream.
 
-
-There are several ways to get a Sound object (ie decoding MPEG data) :
+There are also several metadata-related methods to be able to get the sound sampling frequency, stereo mode, ...
 
 ```java
-// Getting and decoding a sound from a file
+// Getting a Sound from a file
 Path path = Paths.get("res","crazy_dnb.mp3");
-Sound sound = Sound.createSound(path); // throws IOException if an error occured while reading the file or decoding its data
-
-// Getting and decoding a sound from a resource file in your JAR
-InputStream in = MyClass.class.getResourceAsStream("/mp3/rick_astley.mp3");
-Sound sound = Sound.createSound(in) // throws IOException if an error occured while reading the resource file or decoding its data
+try(Sound sound = new Sound(new BufferedInputStream(Files.newInputStream(path)))) {
+  // no need to buffer the SoundInputStream
+  
+  // get sound metadata
+  System.out.println(sound.getSamplingFrequency());
+  
+  // let's copy the decoded data samples into a file!
+  Files.copy(sound, Paths.get("/my/path/to/raw.raw"));
+}
+
+
+// Another example: getting and decoding a sound from a resource file in your JAR
+try(Sound sound = new Sound(new BufferedInputStream(MyClass.class.getResourceAsStream("/mp3/rick_astley.mp3")))) {
+  
+  // ...
+  
+}
 
-// You can also decode a sound from a byte array, see the library Javadoc
 ```
 
-Once you've got a Sound object, you may get the raw decoded PCM samples, or directly use the sound with the javax.sound.sampled API:
+As expected from an InputStream, the creation of the stream will **not block**, and it is only when reading bytes from the stream, that the processing will take place (for the Sound class, that is the MPEG decoding process). You may get metadata about the sound as soon as you have instantiated it.
 
+Let's have a look at some examples on how to use the decoded raw PCM sound data samples:
 
 ```java
 // Creating a Clip from the sound and play it using the plain javax.sound.sampled API
 Sound sound = /* ... */;
+// We use an array to store the produced sound data (bad code style, but is okay for short sounds)
+// (We have to store the data in order to get the number of samples in it, because of the (dumb) Java sound API)
+ByteArrayOutputStream os = new ByteArrayOutputStream();
+// Read and decode the encoded sound data into the byte array output stream (blocking)
+int read = sound.decodeFullyInto(os);
+// A sample takes 2 bytes
+int samples = read / 2;
+// Java sound API stuff ...
 Clip clip = AudioSystem.getClip();
-AudioInputStream stream = sound.newAudioInputStream();
+AudioInputStream stream = new AudioInputStream(new ByteArrayInputStream(os.toByteArray()), sound.getAudioFormat(), samples);
 clip.open(stream);
 clip.start();
 
 // Getting the raw decoded PCM samples to fill an OpenAL buffer (using LWJGL)
 Sound sound = /* ... */;
-int buffer = alGenBuffers();
-ByteBuffer data = BufferUtils.createByteBuffer(sound.getBytes().length);
-data.put(sound.getBytes()).flip(); // LWJGL needs a direct buffer, cannot simply wrap the array 
+// Let's store the whole decoded data in an array, because we need the number of samples; it's okay for short sounds
+ByteArrayOutputStream os = new ByteArrayOutputStream();
+int read = sound.decodeFullyInto(os);
+ByteBuffer data = BufferUtils.createByteBuffer(read);
+data.put(os.toByteArray()).flip(); // LWJGL needs a direct buffer, cannot simply wrap the BAOS array
 alBufferData(buffer, sound.isStereo() ? AL_FORMAT_STEREO16 : AL_FORMAT_MONO16, data, sound.getSamplingFrequency());
 
 ```
@@ -70,33 +90,35 @@ alBufferData(buffer, sound.isStereo() ? AL_FORMAT_STEREO16 : AL_FORMAT_MONO16, d
 
 The only public class is the Sound class.
 
-The javadoc for the API is located at: https://mpeg.delthas.fr/
+The javadoc for the API is located at: http://www.javadoc.io/doc/fr.delthas/javamp3/
 
-This API fully supports multithreaded calls, there is no shared static state. For example, if trying to decode multiple MPEG files from a music folder, you are encouraged to use multiple threads.
+You are encouraged to read the decoded data stream in a streaming way, and/or make use of multithreaded calls (i.e. decode the sound data in a background thread if your application needs to react in real-time to user input).
 
 ## Building
 
-Simply run ```maven package```.
+Simply run ```mvn install```.
 
 
 ## Status
 
 - [X] MPEG-1 Audio Layer I Support
 - [X] MPEG-1 Audio Layer II Support
-- [ ] MPEG-1 Audio Layer III Support
+- [X] MPEG-1 Audio Layer III Support
 - [ ] MPEG-2 Audio Layer I Support
 - [ ] MPEG-2 Audio Layer II Support
 - [ ] MPEG-2 Audio Layer II Support
 - [ ] MPEG-2.5 Audio Layer I Support
 - [ ] MPEG-2.5 Audio Layer II Support
 - [ ] MPEG-2.5 Audio Layer III Support
-- [ ] Tests
+- [X] Tests
+- [ ] Fast seeking support
+- [ ] Fast samples count fetching support
 
 ## Misceallenous
 
 ### Tech
 
-JavaMP3 uses no library except the standard Java library.
+JavaMP3 uses no library except the standard Java library, except for the compile-time JUnit dependency, for testing.
 
 ### License
 

pom.xml

@@ -53,6 +53,12 @@
   </distributionManagement>
 
   <dependencies>
+    <dependency>
+      <groupId>junit</groupId>
+      <artifactId>junit</artifactId>
+      <version>4.12</version>
+      <scope>test</scope>
+    </dependency>
   </dependencies>
 
   <build>