
                      Audiogalaxy Satellite for RISC OS

                                by Marc Warne
                       minor changes by Justin Fletcher
                           2002 Alpha Programming


Information on v1.13
~~~~~~~~~~~~~~~~~~~~
  With this version, you have to restart Satellite when your IP address
  changes, eg. you are on a dynamic-IP ISP and you reconnect. This is
  the majority of dial-up ISPs in the UK.

What is Audiogalaxy?
~~~~~~~~~~~~~~~~~~~~
  One of the great qualities of the internet is the ability for people to
  communicate ideas and explore other people's musical collections and
  tastes in a truly global community. Audiogalaxy is committed to
  promoting and raising people's understanding of music and broaden the
  range of music available that you might not know exists through a
  community of people who have a passion for music. 
  
  (information from the Audiogalaxy website)

What is the Audiogalaxy Satellite?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  The Audiogalaxy Satellite is a small and simple program that allows you
  to share your music with friends and other users on Audiogalaxy. You
  must download [...] and run the Audiogalaxy Satellite for the system to
  work correctly.
  
  (information from the Audiogalaxy website)

Requirements
~~~~~~~~~~~~
    - RISC OS 3.5 or above
    - 160K RAM minimum (dependent on the size of the shares database)
    - AMPlayer 1.29 (available at http://www.amplayer.org/)
    - Mass storage recommended (eg. hard disc)
    - Account on Audiogalaxy

Configuration
~~~~~~~~~~~~~
  Before trying to connect to the server, you must configure the client
  with the bare minimum of your username and password. The first time
  the program is run, your favourite text editor will be invoked and
  you can edit the configuration. Add your username directly after the
  'Username:' field and your password after the 'Password:' field. You
  must save this file and reload the satellite for the changes to come
  into effect.
  
  The directory in which your MP3s are stored is by default
  <Satellite$Dir>.^.MP3s, which is the MP3s directory provided in
  the distribution. If you wish to change the location of this, eg. to
  use a long filenames system, eg. raFS, change the MP3Directory: value
  in the configuration.
  
  If you wish to share MP3s in other directories with users, you should
  enter the directory details in the configuration columns MP3SharesX:
  where X is a number between 1 and 9.
  
  You can play songs in your MP3 directories by clicking on the play icon
  in the homepage or queue page at Audiogalaxy. By default, the MP3 files
  will be played with AMPlayer, but this value can be changed by changing
  the MP3Player: field. Allowed values are AMPlayer, DiskSample (with
  AudioMPEG), Stupid and blank (i.e. you would have 'MP3Player:' with
  nothing else on the line). If the field is blank, songs cannot be
  played.
  
  The NoResume: field is described in the Receiving songs section.
  
  The ShadeIcons: field is set to Yes if you want the home page, queue
  page and directory icons in the main window to be shaded until a
  connection has been established.
  
  This client does not support the creation of new users as yet so you
  will either have to create a new user via the Windows/Linux version of
  the Satellite, or via the website at http://www.audiogalaxy.com/

Searching for songs
~~~~~~~~~~~~~~~~~~~
  The whole process of searching and queueing up songs for downloading
  is performed via the Audiogalaxy website at http://www.audiogalaxy.com/
  It is not done via this client. When the client is run, Audiogalaxy
  will automatically sort out which songs you should be receiving.

Receiving songs
~~~~~~~~~~~~~~~
  All song downloads happen completly in the background and will start
  when commands are sent from the main Audiogalaxy server. If an MP3
  file already exists in your download directory, Satellite will try to
  resume the file download from the point where you last left off.

  Warning about resuming
  ----------------------
    This version of Satellite does support resuming, but problems exist
    with the resumption of tracks. If a file is resumed, it is guaranteed
    to have the same name, and length as the original file that was
    started. The length of tracks (for constant bit-rate tracks) is
    generally the same (a 4:23 track will generally end up the same length
    for a particular bit rate). However, the encoder used may cause a
    slightly different encoding of the audio data. At the resumption point,
    if the encoder was different in the two files the audio data at that
    point will be corrupt. All remaining data will play correctly, but at
    that point a small 'blip' may occur. Depending on the location, your
    MP3 player may skip the broken section.
  
  You can disable the resuming feature by changing the value of NoResume:
  in the choices file to 'Yes'.

  This version of the Satellite supports multiple, concurrent downloads.
  This means that you can download more than one song at a time. However,
  to do this, you must be sharing at least 25 files and have the option
  set up on your member home page.

Sending songs
~~~~~~~~~~~~~
  "'cos if you ain't sharing, people ain't caring"
                                        -- Wyclef Jean, It Doesn't Matter
  
  Satellite will automaticially send songs to people if Audiogalaxy makes
  the request to your computer. This happens completly in the background
  and no intervention from the user is required. I belive that the file
  sending routines are completly secure and no files (other than your MP3
  files) can be sent to others.

  Whilst it is possible to stop the transfer of any song FROM your,
  the authors believe that this is *very* antisocial and as the program
  has been made completly free of charge to you, we would like you not to
  do this in normal use. This is especially the case if you have unmetered
  access to the Internet, eg. via a freephone number or via cable/ADSL.
  
  The Database
  ------------
    Satellite keeps a database of your shared songs so it can send details
    to the Audiogalaxy server more quickly. It does this by finding out
    ID numbers of each shared song from the Audiogalaxy server and saving
    them in a file to look up quickly. Therefore, when you initially share
    your files, it will take a while to process but from then on, it
    should be quicker. If there are ever any problems with the database,
    you can simply delete the SharesDB file from your Choices directory
    and it will be recreated.
    
    Old database entries, such as files which have been moved since the
    database was created, are automatically expired in the background.
    You may see entries in the status window such as 'Expired x cache
    entries' which confirm what has been done.

RISC OS Projects Initiative
~~~~~~~~~~~~~~~~~~~~~~~~~~~
  This program was spurred on by seeing a request on the RISC OS
  Projects Initiative. The basic idea of this is to highlight programs
  or projects which RISC OS really could do with, or those that might
  need a helping hand.
  
  It's available at http://www.chocky.org/initiative/

    
To Do
~~~~~
    - Support gold accounts properly
    - Check how Newshound uses the ppp$connected variable
    - Send correct bytes/second info to Audiogalaxy with keepalive
    - Detection of ID3v2 tags (unlikely, this is 'tricky')
    - Option to auto-connect when loaded
    - Changing icon sprites for connected, not connected and receiving
    - Closing ports if timeout
    - Allow creation of new users
    - Easier to use configuration interface (started)
    - Approximate bit rate transfer
    - Some form of bandwidth throttle (tricky)
    - Make AMPlayer independent

History
~~~~~~~
  1.00 (25-Jul-2001)
       - First version
       - Allows receiving of MP3s
  
  1.01 (25-Jul-2001)
       - Fixed bug in !Run file
       - Updated !Help file with details on the RISC OS Projects
         Initiative
  
  1.02 (29-Jul-2001)
       - Tells Audiogalaxy if a file transfer problem occurs so it
         can try and setup a new transfer
       - Supports 'Stop File Transfer' command which is sent by the
         Audiogalaxy servers
  
  1.03 (30-Jul-2001)
       - Closes connection to initial server after the redirection
         details are found
       - Solves strange problem where it would try to connect to port
         22 instead of port 21

  1.05Dev1 (06-Sep-2001)
       - Accepts files with a '@' in the song title
       - If there are problems connecting to Audiogalaxy servers or
         they take too long to respond, Satellite will try again
       - Able to launch URLs for home page, queue page and Alpha
         Programming page
       - Sends proper IP address to Audiogalaxy (still does not
         provide hostname)
       - Rudimentary support for supplying the server with shared
         file details.
         
  1.05Dev2 (30-Sep-2001) Justin Fletcher
       - When connecting we use /very/ short timeouts to attempt
         connections for testing.
       - Able to open the MP3 directory from the main window.
       - Remembers files supplied as shares so that the 'Play' button
         on the webpage functions.
       - Accepts 'Play' commands from the server.

  1.05Dev3 (30-Sep-2001)
       - Support, although quite dodgy, for a shares file database in
         order to speed up sending shared files details
       - Should no longer get 'Path variable had multiple entries and
         was used for a write operation' error when saving choices
       - Sends proper IP address and hostname to Audiogalaxy (will
         probably only work on Acorn and ANT stacks)

  1.05Dev4 (13 Oct 2001) Justin Fletcher
       - Intermediary example; demonstrating support for 0.608W protocol

  1.05Alpha (28 Oct 2001)
       - Not originally intended for public release but as now previous
         versions work with the new Audiogalaxy protocol. I felt an
         intermediary release was necessary
       - Incomplete functions such as file sharing temporarily removed

  1.05Dev5 (6 Dec 2001)
       - Sets file type to AMPEG at the correct point
       - New database routine which will not run out of memory (gerph)
       - Correctly displays MB count for sent and received data
       - Retries connection to the same server if failed (gerph)
       - MP3 playing routine now abstracted - a certain file is run which
         starts playing of MP3 file
       - Better detection of IP address
       - New Choices option, NoResume: to force no resuming for file
         receives to occur
       - Properly supports receiving files as a server
       - Supports sending files as both a server and client
       - Detects if a file is already open when receiving
       - If a passive port is currently in use, it will notify you in
         the status window instead of Wimp_ReportErroring the message
       - General bug fixes

  1.10 (13 Dec 2001)
       - Supports ImageNFS properly (gerph)
       - All transfers are stopped if master server connection is lost
       - No longer brings the transfer window to the front when a file
         transfer has ended
       - Major problem with waiting for concurrent connections fixed

  1.11dev1 (27 Dec 2001) JF
       - Pane is resizeable
       - We now pass on the client ID returned in the ActivateGo message
         to URLs we launch, ensuring that we login automatically
       - Share-speed improved by around 600%, topping out at 2500% under
         extreme experimental circumstances.
       - Tentative name translation to ensure that AG uses the right names,
         since it appears to ignore the ID3v1 tags we're supplying.
       - ShareDB checking ensures that obsolete entries are eventually
         removed when they have been moved away or removed.
       - ShareDB monitors timestamps and re-caches updated entries.
       - ShareDB is written out regularly when modified to ensure that it
         remains up to date; period between writes depends on the size of
         the share database to reduce the load when large shares are in use.
       - No longer requires debugging log directories.

  1.11dev2 (30 Dec 2001) JF
       - Disconnect option added.
       - Login option allows simple reconfiguration.
       - Iconisation uses more sensible sprite.
       - Active file tracking. During downloads, the position is recorded
         in a scrap file. On restart, this file is read and any entries
         present in it are truncated to the position specified. This ensures
         that if the machine crashes during a download, the files downloaded
         are not filled with junk.
       - Miscellaneous bugfixes

  1.12 (20 Jan 2002)
       - Closes listening port if setting up transfer was unsuccessful
       - No 'Bad ESocket' errors when setting up transfers as a listening
         socket
       - Shaded home, queue and MP3 directory icons are now optional
       - Miscellaneous bugfixes

  1.13 (01 Apr 2002)
         (Bodged version to stop connection problems)
       
       - Uses EasySockets 1.18 which fixes Internal Error bugs
       - Copyright information updated
       - Again allows passive connections when appropriate and send the
         correct IP address (problem in version 1.12 only)
       
  1.14 (whenever it's released)
       Will...
       
       - Make it so you don't have to restart Satellite when your IP address
         changes
       - Able to force Satellite to send a certain IP address to
         Audiogalaxy. Useful if, for example, you are behind a firewall and
         have a reserved LAN address (eg. 192.168.x.y) but you have enabled
         port forwarding and are able to passively open ports to the
         outside Internet
       - Sends correct file transfer aborted information to the Audiogalaxy
         server
       - Refuses to load a copy of Satellite if one is already loaded
         (optional)
         

Thanks
~~~~~~
  Mity/IWiz, mity@ropnet.ru
    For information on the Audiogalaxy Satellite Communication Protocol
    http://tudfgbqvbn.tripod.com/

  Harry McCulla aka More-Beer, harry.mcculla@blueyonder.co.uk
    For additional protocol information

  Audiogalaxy
    For providing the great server
    http://www.audiogalaxy.com/

  Chris Rogers
    For alternative Iconsprites

  Jeff Haskell, Domino
    For bug reports and feedback

  Rob Mitchelmore
    For testing file sharing by running a Windows client and fetching a
    file

Status
~~~~~~
  This program is FREEWARE. It may be freely copied as long as none of
  the files are altered in any way. I also cannot be held responsible
  if this program goes wrong in any way or does anything nasty to your
  computer, although I believe that it won't.

Contact
~~~~~~~
  Marc Warne
  9 Sandal Court           E-mail: marc@indivisibilities.com
  Shenley Church End          WWW: http://www.alpha-programming.co.uk/
  Milton Keynes               ICQ: 15168191
  MK5 6HB
