README for Gnomad2

0. Easy install for distributions that already package
   Gnomad2 by default:

   Debian:
            apt-get install gnomad2
   Fedora:
            yum install gnomad2
   Gentoo:
            emerge gnomad2
   SuSE:
            use YaST?


1. Gnomad2 requires the library GTK+-2.0 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+-2.0-dev(el)
   package to enable compiling.

   Any distribution built on GNOME 2.2+ will work
   fine with Gnomad2.


2. Gnomad2 using GTK+ < 2.6 will require the library 
   libGnomeui to build. Newer versions will rely solely
   on GTK+. (Hey, this also actually works from Gnomad2
   >= 2.8.2!)

   Get it here http://developer.gnome.org/doc/API/

   Any distribution built on GNOME 2.2+ will work
   fine with Gnomad2.


3. Gnomad2 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.

   Debian: libnjb is now included in the Debian 
           distribution. You might need a newer
           library revision (subsitute the "5"
           for something higher).

           apt-get install libnjb5
           apt-get install libnjb5-dev

           should be available, and you may need later
           interface revision numbers (substitute the
           "5" for something higher).

           Notice that Debian also carries gnomad2 so
           why bother installing libnjb separately...
           When you "apt-get install gnomad2" libnjb 
           will be auto-installed anyway.

   Red Hat / Fedora Core: An RPM package of libusb is 
           included in the Red Hat / Fedora Core  
           distribution. (New versions are available
           at RawHide (beta)). It is installed by
           default, you don't have to do anything about it.

           libnjb is included in the Fedora Extras
           so simply issue:

           yum install libnjb

           as root will be likely to work. Also Fedora Extras
           carry gnomad2 packages so easy install with
           "yum install gnomad".

   SuSE:   Use YaST to satisfy the dependencies. You need
           atleast the following packages unless you already
           have them:

           popt and popt-devel
           pkg-config

           Most users will prefer to install libnjb and gnomad2
           from source. Packman has libnjb packages for SuSE
           but not for gnomad2 unfortunately.


4. Gnomad2 also requires the library libid3tag to build.

   NOTE: Gnomad has switched from using id3lib to using
         libid3tag produced by the libmad project. This
         latter library is used by e.g. gtkpod and the 
         gstreamer project use id3tag instead of id3lib. 
         These two libraries are confused all the time, so 
         please pay attention.

   Get it here: http://sourceforge.net/projects/mad/
                http://sourceforge.net/project/showfiles.php?group_id=12349

   Debian: apt-get install libid3tag0
           apt-get install libid3tag0-dev
           The versions from testing (upcoming Debian 4.0)
           are needed for gnomad2 to work.

   Red Hat/Fedora Core: The RPM of Gnomad2 now requires that
           you have the libnjb RPM installed too.

           If you want to compile from sources:
           You may as well build the libid3tag from source,
           but nice RPMs exist at livna and freshrpms.
           See the Fedora FAQ (http://www.fedorafaq.org/)

5. Gnomad2 can optionally use libmtp to access MTP devices, too!
   This is a work in progress: http://libmtp.sourceforge.net/

6. Gnomad2 can optionally use taglib:s C interface to read/write
   Ogg and FLAC tags. http://developer.kde.org/~wheeler/taglib.html
   This will only be needed if you have an MTP device that can
   play these files I suppose.

7. Gnomad2 will optionally use D-Bus and HAL to autodetect attached
   and removed devices. You'll need development files for the D-Bus
   glib bindings and hal if you want this stuff to work.

8. Install gnomad using this sequence:

   tar xvfz gnomad2-2.X.X.tar.gz
   cd gnomad2-2.X.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 / 8.0 / 9, Fedora Core, 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.

      See the README file of libnjb for instructions on how this
      works. Compiling libnjb from source will nowadays add
      hotplugging for you by default. The RPM for Gnomad2 will
      also try to add hotplugging using a script.

      * 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 uses the USB
      from userland, accessing the device through /proc/bus/usb.

      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 (the Vendor/Product ID combo can be
      found in the "nomad.usermap" file that comes with
      Gnomad2.

      If you have (very unlikely but some manage to anyway)
      actually compiled and modprobed a kernel driver for
      the jukebox, then REMOVE IT for gods sake, that old
      driver isn't used by anyone.

      OK this is quite technical but you asked for it.

3. Q: How do I use Gnomad2?

   A: Plug in your jukebox, start the program. Gnomad2 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 in the jukebox view, right clicking your 
      mouse and selectiong "Add selected to playlist" on 
      the popup menu.

6. Q: How does Gnomad2 determine metadata for a file?

   A: Gnomad2 will try to retrieve metadata from files
      in the left view of the music transfer view using
      several heuristic methods.

      For MP3 files, concerning the "Remove ID3 tag"
      option: What is shown on the screen is not primarily
      related to ID3 as a matter of fact. The "Remove ID3"
      option just removes the ID3-tag block from the
      file when transferring it, it does not avoid reading
      in the information from the file in the first place.

      Gnomad will always try everything it can to retrieve
      the metadata:

       * first it reads the ID3 info (on MP3 files) or WMA
         ASF metadata (on WMA files)
       * next it looks at the filename path to determine
         probable metadata
       * if this fails it will use the string <unknown>

      Don't use WMA. Mail Creative and tell them to include
      support for Ogg Vorbis instead.

      When transferring files from harddisk to jukebox,
      the info on the left is always added to the files in
      the view on the right. If some part of it is missing
      after a rescan, that's a bug.

7. Q: If I set Gnomad2 to open a 2900 song music dir, it takes
      12 minutes to open. If I open it up in another directory, 
      it starts in seconds. If I then change to my 2900 songs, 
      I have to wait 12 minutes again. Is this normal?

   A: Sadly yes. This is because the MP3 and the associated 
      ID3 tag format gives no good way of [quickly] determining 
      the length of the songs, so this info has to be retrieved
      from the file anew on every scan. I have evangelized the 
      use of ID3v2:s "TLEN" tag, which makes it possible to tag 
      a file with its playlength, so that gnomad and others don't 
      need to go to such extreme measures to find out how long 
      (in time) they are. Look into the file "mp3file.c" for
      details.

      I have added a "progress" dialog and cancel function though, 
      so one know what is happening...

      If you need a program to add TLEN tags to your songs then
      look into EasyTAG (http://easytag.sourceforge.net/).
      When songs are transfered from your jukebox device back
      to the host, these TLEN tags are happily added.

8. 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.

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

   A: OK so Gnomad2 is not 100% multi-threaded. Might fix it
      someday when everything that is more important has been 
      fixed. Sit back and enjoy the show.

10.Q: Gnomad2 seqfaulted/crashed on me!

   A: OK so neither Gnomad2 nor the libnjb, libmtp, 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.

      The problem can be in several different places:

      * Gnomad2
      * libnjb
      * libmtp
      * libusb
      * Your operating system

      The first task is to find out where the problem is.
      Some things are obviously in gnomad2, while others,
      especially relating to the NJB USB communications, are
      more elusive.

      To intercept the libnjb USB traffic, invoke gnomad2 with
      "gnomad2 -D7". If you think the problem is in libnjb
      join the libnjb mailing list and discuss the problem
      there.

      Error messages that explicitly say that they are USB
      errors (and this happens from time to time) may be either
      in libnjb (unlikely), libmto, libusb (more likely) or the kernel
      of your operating system (also very likely).
