diff options
author | Mario Torre <neugens@limasoftware.net> | 2007-10-09 18:16:05 +0000 |
---|---|---|
committer | Mario Torre <neugens@limasoftware.net> | 2007-10-09 18:16:05 +0000 |
commit | 3bc40d9f348d317a3d34aa167207fb9e98f3783d (patch) | |
tree | 687d091ee2249d9da1044cb4b23b39e5178deb60 /README.gstreamer | |
parent | c865a3e98ef6cc114d59239867cbbd5225829f2f (diff) | |
download | classpath-3bc40d9f348d317a3d34aa167207fb9e98f3783d.tar.gz |
2007-10-09 Mario Torre <neugens@limasoftware.net>
* README.gstreamer: new file.
Diffstat (limited to 'README.gstreamer')
-rw-r--r-- | README.gstreamer | 120 |
1 files changed, 120 insertions, 0 deletions
diff --git a/README.gstreamer b/README.gstreamer new file mode 100644 index 000000000..963bd98b1 --- /dev/null +++ b/README.gstreamer @@ -0,0 +1,120 @@ +GNU Classpath GStreamer Sound Backend README - Last updated: October 8, 2007 +(for release 0.96) + +* Introduction + + From 0.96, GNU Classpath has a preliminary backend implementation for the + Java Sound API based on the GStreamer framework. + + The backend is considered unstable and is currently disabled by default. To + enable it, you should pass "--enable-gstreamer-peer" to configure. + + We suggest that you leave this option to the default on production systems, + but enable it for testing. The backend has been only tested on Linux i386 and + amd64, problems where reported on powerPC64 (see bug: + http://gcc.gnu.org/bugzilla/show_bug.cgi?id=33701) + + The peer supports any kind of stream you have a gstreamer plugin for (modulo + the eventual bugs of course!!), no special steps are needed to enable them, + the only requirement is a working installation of at least gstreamer, + gstreamer-base, gstreamer-plugins-base, all with a version number of at least + 0.10.10. + + The minor version number could eventually be lowered but the peer were + developed on a Fedora 7 machine with GStreamer 0.10.10, so they may rely on + new functions introduced during the GStreamer 0.10 timeline. GStreamer 0.8 + will most lickely not work due to API changes, but porting to the old system + should not be too hard, as the backend only uses a small subset of all the + API. + + Currently, most methods in the backend are missings or are just stubbed. + Especially the lack of event handling routines prevent this backend to be + useful other than for simple examples. + + We have included in the example directory a simple implementation for an audio + player. To run the example just type on the command line: + + $ java -cp examples/examples.zip \ + gnu.classpath.examples.sound.AudioPlayerSample audio_file + + Where "java" is a GNU Classpath based VM and audio_file can be any type of + audio file that can be read by your GStreamer installation (i.e. ogg and wav). + +* Implementation details + + Currently the backend relies on filesystem named pipes to pass data from the + java layer to the native gstreamer layer. This is because GStreamer is heavily + multi-threaded and reading requests are asynchronous and performed by the + framework. While it's possible to control this flow, we have experimented + that the best performance are when the framework itself handles all the + buffering, reading and streaming of audio data. + + The file detection routines instead read directly from an InputStream with a + special GStreamer plugin. This will change in the next few release to also use + filesystem named pipes as a more reliable way to pass data from one side of + the peer to the other as we have experimented that currently reading from a + java InputStream has few drawbacks, like sometimes data is not handled + correctly, or even introduces the risk of deadlocks (see below). + +* Know Bugs and Limitations + + * Not all the methods described by the API are implemented. + + * The peer is not currently tested on all the architectures. + + * There is a bug in the file detection code (native code) that deadlocks the + application. This is usually triggered when you obtain both an + AudioInputStream and AudioFileFormat from the same file, in (bad) code + like the following: + + AudioInputStream is = AudioSystem.getAudioInputStream(new File(file)); + + AudioFileFormat ff = AudioSystem.getAudioFileFormat(new File(file)); + + [... use ff or is at your need ...] + + This is a corner case, but indeed may happen and may also trigger the bug. + + * No event handling is implemented. We will add that in the next release. + + * The backend relies on filesystem named pipes to stream audio data and will + not work if the system is not allowed to create named pipes (for example, + when GNU Classpath is built for systems without a filesystem). + + * To allow correct behaviour of the "available" method (return the free space + in the pipeline) we misure the number of bytes currently in the pipeline for + processing and substract that to the size of the pipeline. + + Few OS allow to know in advance the size of a pipeline (usually you can + retrieve the number of bytes waiting for processing or tell if the next + write will block, but not the number of bytes you can write before + blocking), so we perform a detection of the size of the pipeline when the + backend is first used. This operation can be time consuming and so the + result is stored as a preference and then used anytime instead of detection. + + If you use the MemoryBasedPreferences preference backend, no data is + actually written in a persistent storage, so the detection routine is called + again each time the class is initialized (and that means, currently, in the + constructor! A better approach is to move this in the static initializer, + but this will be fixed in the next releases). + + The preference node for this value is: + + * gnu.javax.sound.sampled.gstreamer.lines.GStreamer + + and the key: + + * Capacity + + If you use the GConf preference backend, it's easy to edit this node, just + search for this key (assuming all the default values are used, otherwise, + pay attention to the defined root node if it's different than + "/apps/classpath"): + + * /apps/classpath/gnu/javax/sound/sampled/gstreamer/lines/GStreamer + + and edit the key Capacity. Do this only if you know the correct size of the + pipe and you think the detection code will not work reliably on your system + (for example, if you have tweaked the kernel to allow very large named pipes + the operation may require a lot of time to complete, as all that the code + does, is to write bytes on the pipe until it's full). |