Improved documentation, added usage for skipping audio streams and an…

… advanced example.

README.md

@@ -22,13 +22,39 @@ Decoding a MP3 file and writing it to a WAVE file.
 
     (-> (->stream "~/test.mp3") decode (write :wave "~/test.wav"))
 
-### Synthesizing sounds
+### Skipping Audio Streams (experimental)
+
+Skipping a specific amount of bytes.
+
+    (-> (->stream "~/test.mp3") (skip 1000) decode play)
+
+Skipping a stream with a ratio of its length.
+
+    (let [s (->stream "~/test.mp3")
+          skip (skipper s)]
+      (skip 0.5)
+      (-> s decode play))
+
+### Synthesizing Sounds (experimental)
 
 Playing the resulting stream from applying the identity function from 0
 to 99999. The given function output will be converted to bytes.
 
     (play (->stream identity 100000))
 
+### Advanced Example
+
+A simple headless [MP3 player] that support a basic set of command:
+play, stop, pause, next, previous, random and close. To use it, you'll
+need some external libraries as explained below. It should work for any
+file format given the corresponding SPI and adding their extensions to
+`music-file-extensions`.
+
+## Known Issues
+
+ * Skipping an encoded stream then writing its decoded output to a file
+   using the write function will produce an empty file.
+
 ## Installation
 
 It's too early for having a distribution right now, so the best way to
@@ -57,3 +83,4 @@ You must not remove this notice, or any other, from this software.
 [Tritonus plug-ins]: http://www.tritonus.org/plugins.html
 [JLayer]: http://www.javazoom.net/javalayer/sources.html
 [MP3SPI]: http://www.javazoom.net/mp3spi/sources.html
+[MP3 player]: http://gist.github.com/471910