
SPR Multimedia Jukebox - Your mIRC add-on for multimedia files
  written by SpinoC

Copyright (C) 2000 by darkrealms.org
  maintained by spradmin@spr.darkrealms.org since 2nd Dec 2000.


    To obtain the latest copy of this file, please visit our website at
    http://spr.darkrealms.org and get the newest version of SPR JukeBox.
    Thank you!



NOTE NOTE NOTE NOTE
    The /load command changed!
    We moved all .ini-files to .mrc-files; hence, the new load command is:
      /load -rs spr-jb1.mrc !!!



UPGRADING

    As with any upgrade, it is always a good idea to back up your current
    version of SPR. You should zip up your entire mIRC folder with SPR
    inside it.
    Before upgrading, it is very important for you to unload the previous
    version of SPR before you overwrite it with the new one. To do that,
    open your mIRC (if it isn't already), right-click on a nick (or in
    the channel), and go to JukeBox / SPR <version> / unload / 
    are you absolutely positively sure?
    Once that is done, unzip the contents of the SPR zip file to the main
    mIRC dir, and type the following command in any mIRC window:
      /load -rs spr-jb1.mrc


    
INSTALLATION REQUIREMENTS

    - mIRC (http://www.mirc.co.uk):
      Currently, mIRC 5.9 or higher is required for this script.
      This is due to the fact that we need hash tables, and the $read and
      $readini identifiers changed from 5.82 to 5.9. The old identifiers
      are still supported, but it's unclear for how long.
    - An mp3 player:
      Winamp (http://www.winamp.com) (v2.63 or higher) is recommended. Nad
      is compatible as well. Winplay and sonique should work, however they
      are not recommended.



NOTE NOTE NOTE NOTE

    Winzip is NOT required any more. We included a dll which has the
    capability of compressing files.



QUICK INSTALL

    Unzip the contents of the SPR zip file into the main mIRC dir. No, not
    any other directory. Yes, the main mIRC directory. Within the setup
    process, SPR will clean the mess up for you, and create a "spr"
    directory within your mIRC directory. Start mIRC (if you haven't
    already done so), and type the following command in any mIRC window:
      /load -rs spr-jb1.mrc
    Answer "yes" when you are being warned about script initialization
    (this should occurr twice).
    You will get a warning by SPR, telling you that you will have to 
    enable the "/run" command under mIRC options, "general", "lock".
    A setup dialog box should appear. Configure SPR for your system,
    update your list, and your general setup is done.



MIRC SETUP

    We need to say a few things about how to set up mIRC for best use with
    SPR. SPR is often blamed for issues that the user really has to set up
    within mIRC. An example is "Why does my mIRC with SPR not reconnect
    to the IRC Server when I get disconnected? My BorgIRC does that for
    me!". Needless to say, mIRC is a multimedia script and does not handle
    reconnection to IRC servers.
    I'll describe a few things that are important for best use with mIRC
    and SPR.

    - mIRC Options, "Connect", "Local Info":
      If you're on a local area network, you should check "Server".
      Anything else (dialup, etc) check "normal".
      If this is not set up right, DCC sends will not work. This is *NOT*
      an SPR issue. If sending files over DCC does not work and your sends
      don't start (i.e. they just wait for acknowledgement), your mIRC
      probably failed to correctly look up your IP Address. It could also
      be a problem with your firewall or router if you are behind a LAN.

    - mIRC Options, "Sounds", "Requests":
      * "Send '!nick file' as private message"
      I think having this option checked by default has caused a few
      million people headaches. If it is checked, you won't be able to
      download files in mp3 channels that use SPR, SDFind or anything like
      that, and you will most likely piss people off because the command
      typed in the channel will be sent as a private message. Also, uncheck
      "Listen for '!nick file' get requests".

    - mIRC Options, "DCC", "Options":
      * On DCC Completition, close windows: send, get.
      Check both "send" and "get", SPR relies on these to calculate slots,
      queues and a lot more.

    - mIRC Options, "Display":
      You should check "include DCC Send/Get windows".

    - mIRC Options, "General", "Lock":
      uncheck "/run" and /dll if checked. SPR needs to be able to use the /run and /dll
      command, or it won't able to play files and update your list.

    - Press "alt-s". This will open mIRC's "DCC Send" dialog box.
      Make sure to uncheck "fill spaces". If you leave it checked, it might
      annoy a lot of people: in this case, mIRC will replace spaces with
      underscores when sending files.



DETAILLED INSTALLATION INSTRUCTIONS

    Because we cannot know the level of expertise a user has with SPR or
    mIRC, this will be a step-by-step guide configuring the script.        

    Before proceeding, your system should meed the requirements mentioned
    above.
    You will need to know where your mp3 player is installed, and what's
    the main executable of the player. Winamp is usually located in
    C:\Program Files\Winamp, and you will have to look for winamp.exe.

    SPR comes within a zip-file, and if you didn't have an unzip utility,
    you would not be reading this file.
    It is very important that you unzip ALL the files available in the SPR
    zip file to your main mIRC directory. If you don't, you will most
    likely get errors when trying to set the script up. Don't worry, SPR
    will create a "spr" directory within your mIRC directory and move all
    files in there.

    Open mIRC if you haven't already done so, and type the following
    command in any mIRC window:
      /load -rs spr-jb1.mrc
    Click "yes" twice when you get a warning about script initialization.

    You will be notified that you have to check your mIRC options for SPR
    to work properly:
    Press alt-o from within your mIRC (opens mIRC options). In the
    "General" section, go to the "Lock" subsection and and uncheck
    "disable: /run". This is very important, because without it SPR
    will not be able to play files or create a file-list for you.

    [ For the following, we assume that you have winamp and mIRC
      installed and that they all work correctly. Note that mIRC has some
      problems with directories that contain spaces. We suggest you to
      move your C:\Program Files\mIRC to C:\mIRC or somewhere else. You
      have been warned.
      We will assume C:\mIRC and C:\Program Files\Winamp. ]

    You can close the window that warns you about "/run".
    You should see the SPR General Setup dialog (SPR Setup Options).
    As you can see, there are four areas: "General", "Multimedia",
    "DCC Server" and "@Find / @Locator".


    - "General Setup" Tab:
      It's divided into "Channel Setup", "Directory Setup", "Player Setup"
      and a few checkboxes.

      The "Channel Setup" lists channels where you will want to serve in,
      i.e. #mp3chat, #mp3oldies, #cablemp3z, etc. To add a channel, type
      it in the box right under "Channel Setup" and click on "ADD" on the
      right. You can repeat this step for as many channels as you want.
      Note that whatever channel you added first will be your main channel,
      and you will need to be in your main channel for SPR to work 
      properly.

      The "Directory Setup" basically tells SPR where your mp3's are.
      Don't type anything here- click on the "ADD" button, and you will be
      able to select folders from your computer. Select your mp3
      directories and add them. Note that you can add as many as you want,
      but do not add subdirectories! For example, if you added "C:\mp3",
      you don't need to add "C:\mp3\hard_rock". You can also add 
      directories with videos or wavs.
      If your list contains some files twice, the problem might be that
      you added subdirs.

      You will have to set up your player in the "Player Setup" section.
      Click on the tab, browse to your player's executable and select it.
      If you use winamp, this will be "C:\Program Files\Winamp\winamp.exe".
        
      There are a few boxes under the directory setup. Their meaning
      should be pretty self-explanatory; configure as you wish.


    - "Multimedia" Tab:
      You can add filetypes if you want to. Be careful: do NOT add ".mp3"
      as a filetype, as ".mp?" matches ".mp3" as well.
      You will only have to add stuff here if you want to serve other
      filetypes as well (videos, text files, .zip-files, etc).


    - "DCC Server" Tab:
      * Check "Auto DCC Send on !Nick".
      * Check "Queue files after slots are full".

      You should set max slots, max slots/user, max queues, max queues/user
      depending on what connection you are on, and depending on how much 
      bandwidth you want to share.

      A slot is an available send space. SPR limits the number of outgoing
      sends. This means that you can chose how much bandwidth you want to
      share with others. You can control how many sends are going, and you
      can control how many sends (slots) one user can occupy.
      A queue is a waiting loop. When all slots are occupied, users will
      have to wait for their files. Look at it as when you're going to the
      supermarket: if you have to wait, you're in a queue. If you are the
      4th in line, you're the 4th in the queue. 

      * Dialup users:
        x max slots:        2 (max. 3)
        x max slots/user:   1
        x max queues:       10-15
        x max queues/user:  1

      * Cable users:
        x max slots:        10-20
        x max slots/user:   1 or 2 (1 is recommended)
        x max queues:       10-40
        x max queues/user:  1-4

      "Send auto-resume request on get fail": If you check this box, SPR
      will try to re-request a file if the get fails.

      SPR offers a minimum CPS check. If you set it to 300 CPS, any sends
      going slower than that (falling under the limit) for a while will be
      terminated. It is STONGLY recommended not to set  this higher than
      1000 CPS!
      If you are serving large files, you can separately set another CPS
      limit for them. This is most useful if you serve mp3's and videos. A
      minimum CPS of 1000 makes no sense for files larger than 10 MB. You
      should set the minimum CPS for files larger than 10 MB to at least
      5000 CPS.

      The autoban will temporarily ban people from your server if they go
      under the min. CPS three times in an hour.

      Transfers will be terminated if the downloader leaves channels you
      are on or if they quit IRC. This can be somewhat unfair when there
      is a netsplit. If you set split/server hop time limit to 5 minutes,
      the downloader will be given 5 minutes to come back. If they don't,
      their download will be terminated.


    - "@Find/@Locator" Tab:

      @Find/@Locator enables users to search every "server" in a channel
      for certain songs he would like to download. Of course, the "servers"
      will need to have a script (such as SPR or SDFind) that supports 
      @Find / @Locator.

      * Uncheck "echo search result in active window" (only makes sense for
        small channels).

      * You can turn on "intervaled search". That way, your SPR will not
        answer to too many @Find/@Locator requests at once (and flood
        itself off).



    That should be it! Click on "OK".
    The "list options" box will open. You can chose how you would like 
    your mp3 list. Note that if you want to include ID3 Tags and have a 
    few thousand files, the list update could take quite a while.
    Also, if you are serving off networked drives, it will take even 
    longer. In this case, you should not include ID3 tag information.
    You can write a small preface for your list if you want to.
    Click on "Update".
    You may be asked if you want to send your list as a zipped file
    instead of a .txt-file. If you chose yes, SPR will zip your filelist. 

    You should get the message "Multimedia Jukebox Loaded! ..."
    Do as the message says, it will turn your server on. Be sure to be in
    your main channel.



MORE HELP

    Please try our setup section:
      http://spr.darkrealms.org/spr_s.html

    Our webboard:
      http://spr.darkrealms.org/webboard/list.php3?bn=agora_sprforum



CONTACTS

    Johannes Egger   Johannes.Egger@spr.darkrealms.org    SPR Maintainer,
                     spradmin@spr.darkrealms.org          website

    Peter Warasin    Peter.Warasin@spr.darkrealms.org     website / scripts
    Corinna Thni    Corinna.Thoeni@spr.darkrealms.org    website / design

    Tim DiSanza      Tim.DiSanza@spr.darkrealms.org       SPR skins
    Mike Evans       Mike.Evans@spr.darkrealms.org        Maintainer of this
                                                          file


    You will find more (and updated) information at:
      http://spr.darkrealms.org/contact.html

    Please contact Mike Evans if you have suggestions for this file.
    Thank you!
