$Id: README,v 1.3 2007/05/09 22:18:08 buhrow Exp $ The UBT (Unix Book transfer) tool is a command-line tool which indexes text or MP3 files and generates the indices necessary for those texts or MP3 files to be recognized by the Springer Design bookCourier, or the APH Bookport. As of this writing, April 11, 2006, the tool can generate indices compatible with all versions of the Bookport or Bookcourier. Specifically, it can generate the old style indices which have certain size limitations as well as the new style indices which raise those limitations, but which are not compatible with older versions of the book readers' firmware. The ubt tool was written under NetBSD and is known to work under NetBSD, FreeBSD, and Linux. Plans are to make ubt as OS-agnostic as possible. NOT SUPPORTED BY MANUFACTURER The BookCourier is sold and supported by Springer Design. The BookPort is sold and supported by the American Printing House for the Blind. Both of these companies supply Microsoft Windows-based utilities to provide material for their devices. They do not, under any circumstances, support the use of ubt. They will not answer questions regarding your device with respect to ubt, and if you experience problems with your device, you will need to use their Windows-based utilities when troubleshooting with their support teams. Further, your book reader is not warranted to work with files produced by the ubt utility. You use the ubt utility at your own risk, and, as such, if you lose data, corrupt your flash media, or otherwise render your book reading device unusable, you ar solely responsible. Support for the ubt utility is only provided on the ubt-users mailing list, and no one on that list is responsible for the care and feeding of your book reading device. Support for ubt is provided by volunteers, and given on a "best effort" basis. HOW TO INSTALL UBT UBT has a home page at: http://www.nfbcal.org/~buhrow/ubt There you'll find access to a source distribution, a mailing list where UBT users can discuss issues with ubt, and various binary distributions for FreeBSD, NetBSD and Linux. INSTALLING FROM SOURCE To install from source, download the source tar file from the web site, above, untar it, and cd into it. Then: $make If all goes well, you should have a file called ubt when the make finishes. If you do, copy it to your favorite bin directory, /usr/local/bin, or if you are using it in your own account, copy it to your own personal bin directory. Next, copy the file ubtrc from the source distribution into a file called .ubtrc in your home directory. Read the comments in that file, and edit to taste. NOTE: You do not need to have a file called .ubtrc in your home directory in order to use the tool. The ubt tool picks reasonable default configuration options which will serve most folks fine. However, if you want to use fancy features like making sure your flash media is ready before you write to it, or the synchronize queue directory option, you'll need to install the .ubtrc file. INSTALLING FROM A BINARY DISTRIBUTION To install ubt from a binary distribution, go to the home page listed above, choose the binary distribution package that most closely fits your installation, down load the tar file, untar it, and copy the ubt program out of the extracted directory into your favorite binary location. Then, copy the ubtrc file from the distribution into a file called .ubtrc in your home directory. See the comments in the previous paragraph about the .ubtrc file. HELPER PROGRAMS AND UBT The ubt utility can work as a text file indexer on its own, but it needs the assistance of some external programs in order to properly index and identify MP3 files. The two programs it needs are: 1. mpg123, a small high performance MP3 decoder available for a variety of operating systems. 2. id3info, a program which is part of the id3lib package, again available for most operating systems. If these two programs are installed and are in your path, the UBT utility will find them and take advantage of them. If they're installed, but not in your path, edit the .ubtrc file, and change the variables "mp3_program" and "id3_program" to point at the executables you want to use. USING UBT The easiest way to use ubt is to just invoke it from the command line, like: $ubt *.txt this command will read all .txt files in the current directory and generate indexed versions of them and write those indexed versions to the current directory. For example, here is the output from a simple directory with a couple of text files. %ls brlm0406.txt kgibbs.txt vod.txt voiceover.txt %ubt *.txt ubt: Done indexing brlm0406.txt ubt: Done indexing kgibbs.txt ubt: Done indexing vod.txt ubt: Done indexing voiceover.txt %ls brlm0406.txt kgibbs.txt vod.txt voiceover.txt brlm0406.txt._DD kgibbs.txt._DD vod.txt._DD voiceover.txt._DD brlm0406.txt._IX kgibbs.txt._IX vod.txt._IX voiceover.txt._IX Notice that for each text file listed in the original ls output, there are now two additional files, each with a different additional extension. the ._IX file is the index data containing the navigational information the book readers need to navigate the text file. The ._DD file contains the text from the original txt file, slightly modified to make it more pallotable for the book readers. If you copy the ._IX and ._DD files to your book reader, you'll find the reader will recognize and read the texts just fine. The procedure for indexing an MP3 file isjust the same. You give the file you want to index on the command line, and when the ubt tool is done, you'll have two additional files, one with a ._IX extension, and one with a ._DD extension. Again, copy these to your book reader's flash card, and it will identify and play them. FANCIER FEATURES In addition to simply indexing files, the ubt tool can be configured to provide additional functionality: O It can put all indexed files in a specific directory, either specified on the command line, in the configuration file, or by a combination of the two. O It can check to make sure the flash media is ready to be used before writing any index files to it. O In the event that the flash directory is not available when you want to index a file, the ubt tool can put all indexd files in a queue directory for later transmission to the flash media when it's ready. O It can be told to write indices compatible with all book readers or indices only compatible with newer versions of the book reader firmware. For more details, see the ubtrc file in the distribution. MAILING LIST If you find the ubt tool useful, and you'd like to participate in discussions about its use, please join the ubt-users mailing list, available at the web site given at the top of this file. Brian Buhrow, April 11, 2006