java-avm - Java Audio Video Media API


LGPL License

 Hosted By

What is java-avm?

java-avm (Audio Video Media) is a Java API for accessing and controlling disc drives, particularly CD-ROM and CD-R(W) drives, removable drives, and loopback devices.

java-avm does not depend on Swing or awt (except for audio playback), so it's suitable for use in server environments like JSP as well as in GUI programs. java-avm does not require the Java Media Framework (JMF).

Currently, Mac OSX, Linux (Intel only) and Windows (95, NT, etc.) are supported. Someday: Solaris, BSD, other Linux platforms.

java-avm uses JNI, Runtime.exec(), and runtime-loadable Java plugins to access local operating-system specific features, and other features not available in Java.

java-avm itself is released under the LGPL license, but some of the code it depends upon is GPL. It might be possible in the future for java-avm to not rely on any GPL software, particularly on OSX, in which case it can be used freely by commercial software.


  • Enumerate all drives and determine their types.
  • Report free space and capacity of a drive.
  • Load and eject media from drives.
  • Mount and unmount file system devices.
  • CD-ROM Specific:

  • Retrieve drive status, Table of Contents, MCN, etc. from audio CDs.
  • Control CD-Audio playback with volume adjustment.
  • Rip audio and data tracks to streams.
  • Copy raw CD data to image file.
  • Coming Soon: Select disc from changer.
  • CD-R Specific:

  • Writes data CDs, bootable data CDs, audio CDs, CD-PLUS CDs, multisession CDs.
  • Create ISO images, with multisession support.
  • Write session to CD-R from disc files, with optional CD-TEXT for audio tracks.
  • Write track to CD-R from stream.
  • Write disc image to CD-R from stream.
  • Retrieve ATIP data from disc.
  • Retrieve multisession data from disc.
  • Make a copy of a disc in a CD-ROM drive.
  • CD-RW Specific:

  • Erase media.
  • Other Features:

  • Fetch CD track information from
  • Mount and unmount ISO image files as filesystems (Linux only).
  • Play audio and video files.
  • Convert sound files from one format to another.
  • Control volume and mute settings of sound card mixer.
  • Hides API differences between Java 1.3 and 1.4 on Mac OS.
  • Requirements

  • Mac OSX 10.2.4, Linux 2.4 Intel or Windows NT/95/98/ME/2000/XP. Soon: Solaris 2.x SPARC, FreeBSD Intel.

    For Linux, RedHat 7.2 or later is recommended. The losetup program in RedHat 7.1 (losetup-2.11b-3) has a bug which is fixed in RedHat 7.2 (losetup-2.11g-5). To see if the bug exists on your system, use losetup to attach an image file (losetup /dev/loop0 /foo/bar.img), then view the device status (losetup /dev/loop0). If the pathname shown does not begin with a '/', your system has the bug.

  • Java 1.3.1 or newer. The binary distribution is compiled with 1.3.1. Java 1.4.1 or newer is recommended at runtime. Earlier versions may work but there are various platform-specific bugs. In particular, the infamous DOS-box problems on Windows (bug IDs 1245049, 4109888, etc.) were fixed in Java 1.4.
  • cdrtools-2.0. cdrtools is a part of most Linux distributions, but the installed version may be too old.
  • cdrdao.
  • lame, madplay, Vorbis Tools, and FLAC are required for file format conversion and playing audio files.
  • On Linux, each ATAPI CD drive must be remapped as a SCSI device by adding the following boot option:


    The procedure for this is explained in more detail in the CD-Writing HOWTO.
  • On Linux & OSX, it is highly recommended to install and configure sudo so that specific users can get necessary access to desktop hardware. In particular, cdrecord, cdrdao, mkisofs, cdda2wav, readcd, and losetup require root access. sudo is part of most Linux distributions and is included with OSX. Currently you must configure sudo so that it does not prompt for a password when the required programs are run. Maybe someday java-avm could have a provision to prompt the user for sudo passwords.
  • On Windows, an ASPI library is required. Also see this page for further information.
  • Optional:

  • xmms.
  • faad2, for decoding AAC files.
  • On Windows, Winamp.
  • On Linux, xanim, and cdparanoia.
  • On Windows and OSX, Apple QuickTime. Note that QuickTime is not supported for Java 1.4, so if you want to use QuickTime, you must use Java 1.3.1. Don't complain to me, complain to Apple!
  • Most of the required programs are readily available in most Linux distributions. Shell scripts to build packages containing the required programs on OSX and Windows are available via CVS. OSX users can install most of these packages using Fink, and Windows users can get them as part of Cygwin.

    Test/Example Programs

    Test programs are supplied:

  • a multi-feature command line program that exercises many of the features of the java-avm API.
  • A Swing-based CD player program.
  • A Swing-based audio mixer program.
  • Development

    Building java-avm: currently, java-avm builds on OSX. Apache Ant is required. The great difficulty in building java-avm is creating all the platform-specific libraries. The gcc cross-compiler for Windows is used for compiling the Windows JNI dll. The script is for Linux, but it also works, with minor modifications, on OSX. Scripts for creating Win32 and Linux cross-compilers for OSX are available from CVS. GNU ld does not support OSX, so OSX shared libraries cannot be cross-compiled with GNU tools. The Akrip library must be present to link java-avm's JNI code. These java libraries and tools are required for building: jd3lib, nanoxml, junit, nounit, jtestcase.

    This project is hosted at Sourceforge. The project page is here.

    This project is very early in its development. Changes to the API will happen. Many new features are planned, as time permits.


    JUnit has emerged as the testing platform of choice for Java.

    Hardware APIs are better tested using the Test Suite strategy than the Unit Testing strategy supported by JUnit, because hardware differs from machine to machine and the returned results will vary. The JTestSuite package allows test data to be placed in XML files, separated from the test code.

    The NoUnit package provides a rudimentary way to determine test coverage. It creates a list of class methods and indicates whether or not they are covered by test cases. Work is required to correlate the test results on different platforms, since some code is platform-dependent.

    Test support in java-avm currently consists of a single test program, with multiple test cases. Testing is currently limited to CD handling; more test cases will be added before the first release.

    In the future, automated line-by-line coverage detection is desired, possibly using the hansel package. Again, platform dependencies mean that the results will need to be further processed or something... No method is known for coverage detection of native JNI code, but any suggestions are welcome!

    Platform dependencies are regrettable but alas the whole point of java-avm. All that weird stuff is hidden in here so the application developer can remain blissfully unaware of the complexities beneath.


    Current plans:

    Release 0.1 - This will be the first release, real soon now!. There are many bugs, and some features are not done yet. It is quite usable, though. It's intended to support the 0.1 release of Tuneology. Prereleases are available from the download page.

    Future - Finish existing features, fix bugs, add more CODEC options, more players, more video file types, add libogg support. Remove swing dependency for audio playback. Use schily libscg SCSI API. Support rscsi for network access to SCSI devices. Support for QuickTime in Java 1.4 (as soon as Apple releases it). Detection of hot-plugged devices (USB, Firewire, etc.).


    Windows Multimedia reference.

    Windows I/O Requests for Mass-storage Drivers.

    Windows AKRip CD-DA Audio Extraction Library.

    Windows ASPI for Win32 Technical Reference.

    Linux CDROM Applications.

    A Windows cross-compiler for Debian Linux.

    Windows development tools.


    Fran Taylor