positron/README

   1 positron - Neuros Synchronization Manager for Linux
   2 Version 1.1
   3
   4 Copyright 2003-2004 - Xiph.org Foundation
   5 Written and maintained by Stan Seibert <volsung@xiph.org>
   6
   7 MP3Info.py: Copyright 2002 - Vivake Gupta (vivakeATomniscia.org).
   8             All rights reserved.
   9
  10 See COPYING for software license.
  11
  12 ---------------------------------------------------------------------
  13
  14 OVERVIEW
  15
  16 Positron is a synchronization tool for the Neuros portable music
  17 player (http://www.neurosaudio.com).  Positron allows you to
  18 individually add and delete tracks from a Neuros, as well as
  19 synchronize it with a directory tree of music.
  20
  21 As far as your computer is concerned, a Neuros is just an external USB
  22 hard disk, following the USB Mass Storage standard.  You can copy
  23 any sort of file, music or otherwise, onto the Neuros.  However, only files
  24 that are listed in a special database stored on the Neuros will be
  25 playable.  This is where positron is needed.  It will both physically
  26 copy files and update the Neuros database so those files are playable.
  27
  28
  29 INSTALLATION
  30
  31 First, you need to install positron on your computer.  You can do this
  32 by installing the binary packages in the usual way:
  33
  34 For RPM-based systems   : rpm -ivh positron*.rpm
  35 For Debian-based systems:
  36    Add the following lines to your /etc/apt/sources.list:
  37       deb http://i.cantcode.com/~jack/debian unstable main contrib
  38       deb-src http://i.cantcode.com/~jack/debian unstable main contrib
  39
  40    And type:  apt-get update
  41               apt-get install positron
  42
  43 For Gentoo systems      : emerge positron
  44
  45 To install from the source tarball, unpack the positron source and
  46 cd into the resulting directory.  Then run the following commands:
  47
  48   python setup.py install
  49
  50 You will probably need to become root in order to do this.  If you want to install somewhere other than the default location of /usr you can type:
  51
  52   python setup.py install --prefix=/some/prefix
  53
  54 or:
  55
  56   python setup.py install --home=/some/prefix
  57
  58 Please see "Installing Python Modules" at
  59 http://www.python.org/doc/current/inst/inst.html
  60 for more information on how to use distutils.
  61
  62
  63 CONFIGURING
  64
  65 Next, you will need to configure your system to work with USB Mass
  66 Storage devices.  The work required to do this varies depending upon
  67 your particular distribution, but here are some general hints:
  68
  69 * You need kernel support for USB, USB Mass Storage, and SCSI drives
  70   either in the kernel or loaded as modules (usbcore, usb-storage,
  71   scsi_mod, sd_mod).  Some of these may automatically be loaded for you.
  72
  73 * Plug your Neuros into your USB port and wait a moment.  The "dmesg"
  74   command should show the Neuros being recognized by the USB subsystem
  75   and the assignment of a SCSI device (like "sda", for example).
  76
  77 * Create a directory to mount your Neuros under, like "/mnt/neuros"
  78
  79 * Now you can edit your /etc/fstab file and add a line like:
  80
  81 /dev/sda1 /mnt/neuros vfat user,noauto,umask=0  0 0
  82
  83 This is assuming that the Neuros was registered as "sda" when it was
  84 discovered by the kernel.  You may have to adjust it.  The Neuros
  85 filesystem, however, is always on partition 1.
  86
  87 * Test your setup by running "mount /mnt/neuros" as a normal user.
  88   You should be able to go browse around the contents of /mnt/neuros.
  89   (There will be something there, even if your Neuros is brand new and
  90   "empty".)
  91
  92 * Finally, run "positron config" while the Neuros is mounted and
  93   configure your personal settings.
  94
  95
  96 BACKING UP THE DATABASE
  97
  98 Given various bug reports about lockups when doing USB transfers to
  99 the Neuros in Linux, it would be best to back up the Neuros database
 100 before use.  You can do this by copying the entire "WOID_DB" directory
 101 on the Neuros to some safe location.  If you need to restore the
 102 database, just remove the "WOID_DB" directory on the Neuros and copy
 103 your backup copy of the directory in its place.
 104
 105
 106 USAGE
 107
 108 Before using positron, make sure to mount your Neuros.  And when you
 109 are done, remember to unmount it before unplugging it.  Linux buffers
 110 disk writes, and you want to make sure everything gets written to
 111 disk.
 112
 113 Most people will use "positron sync" to copy over all of their music
 114 directories (specified when you ran "positron config").  You can run
 115 this command periodically, and only new tracks will be copied.
 116
 117 If you want to add a specific track, you can use "positron add track.mp3".
 118
 119 More detail on these commands can be found using "positron help".
 120
 121
 122 IN CASE OF EMERGENCY
 123
 124 If for some reason your Neuros seems to be mysteriously locking up, or
 125 your song listing seem incorrect or unusable, you can use "positron
 126 rebuild" to recreate your database based upon the music files already
 127 on the Neuros.  Positron will try to figure out where everything
 128 should be filed, but with the following limitations:
 129
 130 * The pcaudio database will be cleared.
 131 * All HiSi clips will be marked as unidentified, even if they had been
 132   previously identified.
 133
 134 "My Neuros has locked up, and I am very angry. What now?"
 135 You can reset the unit by pressing and holding the Up and Play buttons
 136 simultaneously.
 137
 138
 139 CONTACT INFO
 140
 141 We strongly encourage bug reports and feature requests.  You can contact
 142 us in one of the following ways:
 143
 144 * To report bugs use Bugzilla at http://bugs.xiph.org. We prefer bug
 145   reports to be filed this way.  Please file them against the 'positron'
 146   product.
 147 * Mailing list: http://www.xiph.org/archives.  Look for the positron list.
 148 * IRC: #positron on irc.freenode.net.  You are also welcome to join
 149   #vorbis-talk for general talk about the Xiph.org Foundation projects.
 150 * Email: You may contact the author directly at volsung@xiph.org, but
 151   please only do this as a last resort.
 152
 153 ACKNOWLEDGEMENTS
 154
 155 Special thanks go out to:
 156
 157   * Emmett Plant
 158   * Manuel Lora
 159   * Jack Moffitt
 160
 161 and most especially:
 162   * the awesome folks at Digital Innovations, who answered many
 163     questions, and were willing to open source positron.
 164
 165 Without valuable support from all these people, this software would not have
 166 been possible.