README for GNOMAD

1. GNOMAD requires the library GTK+ to build.

   Get it here: http://www.gtk.org/

   This comes by default on most systems by the way.
   You mostly only need to install a gtk+-dev(el)
   package to start compiling.

2. GNOMAD also requires the library libnjb 
   to build.

   Get it here: http://sourceforge.net/projects/libnjb/

   Pay attention to the notes in the libnjb README file 
   for underlying functionality requirements and 
   troubleshooting.

   libnjb may in turn require libusb if you're building
   under Linux. Find libusb here:

   Debian: apt-get install libusb0
           apt-get install libusb-dev

           libnjb is not included in the Debian 
           distribution, you have to build it from
           source!

           apt-get install libnjb0
           apt-get install libnjb-dev

           will soon be available.

   RedHat: an RPM package of libusb is available at
           http://freshrpms.net/

           I am not aware of any RPM of the libnjb
           library. You have to build it from source.

3. GNOMAD also requires the library id3lib to build.

   Get it here: http://id3lib.sourceforge.net/

   Debian: apt-get install libid3
           apt-get install libid3-dev
           NOTE: do NOT install libid3tag0!!

   RedHat: Get the latest id3lib RPM package from
           the Easytag project at:
           http://easytag.sourceforge.net/
           (download section)

           Do not use any other id3lib packages! I
           have seen erroneous RPMs of id3lib out
           there. Especially the Mandrake id3lib
           package is flawed, unistall and use these
           packages instead if you don't want to
           install id3lib from source.

4. Install gnomad using this sequence:

   tar xvfz gnomad-1.X.tar.gz
   cd gnomad-1.X
   ./configure
   make
   make install

   (make may be named gmake on some systems)


FAQ:

1. Q: Hey, it starts, but it doesn't connect to the jukebox!

   A: First, do you have USB support in your kernel, with
      the usbfs filesystem activated?

      /proc/bus/usb/ is a virtual file system implemented 
      (usbfs) in the 2.4.x versions of the Linux kernel that 
      represents the USB port. So this info is worthless for 
      BSD users.

      In the Linux kernel USB is used in user mode by 
      accessing this virtual file system. Devices that have
      kernel drivers appear here, and devices that haven't
      atleast appear in /proc/usb/001/... etc. And this is 
      how libusb access your USB port.

      * Distributions with hotplugging:
        (Eg: RedHat 7.2 / 7.3, Debian)

      This is info for distributions with hotplugging enabled
      for USB / PCI devices. This typically means you have
      something i /etc/hotplug and that hotplugging is started
      when you boot your machine in a script named 
      /etc/init.d/hotplug or similar.

      If you have a distro with hotplugging enabled (like in
      RedHat 7.2/3) try this as root: chmod -R a+w /proc/bus/usb
      (brutal eh?) You have to do this again every time you
      unplug/replug your USB cable or restart the jukebox,
      every time you quit GNOMAD and restart it, etc etc etc
      an alternative is to run GNOMAD as root which works just
      fine. The problem is to somehow assure that you (ie the
      current user) always has write access on /proc/bus/usb/*

      What you really want to do is for hotplug to create your
      device with global write permissions in 
      /proc/bus/usb/00x/... so add the following to the file
      /etc/hotplug/usb.usermap:

      nomadjukebox 0x0000 0x0471 0x0222 0x0000 0x0000 0x00 
      0x00 0x00 0x00 0x00 0x00 0x00000000

      All of that should be on one long row. Adding this to
      usb.usermap will make the hotplugging system call a
      script called /etc/hotplug/usb/nomadjukebox every time
      you plug in your jukebox. So create an executable file
      called /etc/hotplug/usb/nomadjukebox and type in
      something like this:

          #!/bin/sh
          chown root $DEVICE
          chmod a+w $DEVICE

      You could of course set permissions for a special group
      like "audio" if you want to, eg:

          #!/bin/sh
          chown root:audio $DEVICE
          chmod 660 $DEVICE

      This is not so elegant as I cannot install it for you
      automatically, but in the future, I think this will be
      simpler. (Thanks to David A Knight for sorting out the
      hotplugging issue for me.)

      * Other distributions:

      This is if you don't have hotplugging enabled and do not
      want to set it up on your machine either. You want to
      mount the usbfs manually.

      According to Tim Pepper, this should work in your 
      /etc/fstab:

      none  /proc/bus/usb  usbdevfs noauto,devmode=0666 0 0

      You can find the Linux hotplug project at:
      http://linux-hotplug.sourceforge.net/

   A: Check out the libusb homepage for more information on
      USB problems that might be caused by USB stuff, and check
      out: http://www.linux-usb.org/FAQ.html

2: Q: My kernel does not find a driver for the jukebox!

   A: So I guess you're using Linux. libnjb doesn't use a 
      kernel driver for the jukebox anyway. It might do so 
      in the future, or atleast support one. But it's not
      for certain.

      The important thing for you is to see that if you write
      cat /prob/bus/usb/devices you find your jukebox among
      the listed devices (Vendor ID: 0x0471, Product ID: 0x0222)

      OK this is quite technical but you asked for it.

3. Q: How do I use GNOMAD?

   A: Plug in your jukebox, start the program. GNOMAD will
      locate and scan your jukebox for files. (If it fails
      you may use the "rescan contents" option in the
      Jukebox menu, or the popups in the jukebox file lists.)

4. Q: How do I select multiple files?

   A: Click first file, then hold down CTRL and click
      additional files. To select a large region of files,
      click top file, hold down SHIFT and click bottom file.
      Easy, see? (You really ought to know this behaviour
      from other applications.)

5. Q: How do I add some tracks in the jukebox library to a
      playlist?

   A: OK this might be not-so-logical: you add the files
      in the music transfer frame, by selecting the files
      you want, right clicking your mouse and selectiong
      "Add selected to playlist" on the popup menu.

6. Q: But how do I...

   A: Hey! did you try selecting something and clicking the
      right mousebutton? Different popups may appear 
      depending on what is selected. Notably in the playlist.

7. Q: Sometimes the graphics freeze for example when I delete
      some files on the jukebox.

   A: OK so GNOMAD is not 100% multi-threaded. Might fix it
      someday when everything that is more important has been 
      fixed.

8. Q: GNOMAD seqfaulted/crashed on me!

   A: OK so neither GNOMAD nor the libnjb, libusb or id3lib
      are entirely stable. Please start up you GDB and help
      us find the error and submit patches to respective
      maintainer, thats how it works.
