¨

Welcome to the Firefly Music Server!

This is the 1.0 release of Firefly for Macintosh.  When you install this package, the Firefly server software will be installed, along with a System Preferences pane that allows for easy configuration of the server.

Although we have tested this software and don't anticipate problems, please keep in mind that it is always a good idea to have a current backup before installing new software.

VERY IMPORTANT
If you are currently using the 1.0b1 or 1.0b2 versions Firefly for Macintosh, the existing software must be un-installed before installing 1.0b3.  If you do not uninstall the previous version, Firefly will not work properly.  See the section "Installing Firefly" below for details.

System Requirements
This release of Firefly runs on PowerPC and Intel Macintosh computers running MacOS 10.3.9 or later.

Features of Firefly
The Firefly music server makes it possible to share your music library over the network with other computers, and with compatible devices like the Roku™ SoundBridge™ and Pinnacle™ SoundBridge™.  

The server runs in the background (with no menus or windows) when you are logged in to your computer, and does not require your music library software to be open in order to function.  All common configuration options are available from the Firefly icon that will be available in System Preferences after installation.

If you share the folder containing your iTunes library file, Firefly will read all of your playlists from the library and make them available, including your iTunes Smart Playlists and any playlists that contain Internet radio stations (SoundBridge software version 2.5.173 or later is required to play Internet radio stations displayed by Firefly).

As an option, users may enable a Status Item in the menu bar (a small icon near the right end of the menu bar) to check Firefly's status and start and stop the server.

Installing Firefly
Please follow these simple steps:

	1.	The first step depends upon which existing version of Firefly (if any) is currently installed:
	a.	If you do not have any version of Firefly installed already, proceed directly to step 2.
	b.	If you are currently running Firefly 1.0b3, double-click the "Quit Firefly" file.  This is a compiled AppleScript that will shut down the Firefly server and the background Firefly Helper utility.  Proceed to step 2.
	c.	If you are currently running Firefly 1.0b1 or 1.0b2, double-click the "Uninstall Firefly" item.  This is a compiled AppleScript that will shut down your existing Firefly installation and move all of its components to a folder called "firefly-uninstall" in the Trash.  Users of 1.0b1 or 1.0b2 must run this script, or 1.0 will not work properly.  If for some reason an error occurs when using this script, you must follow the manual uninstallation instructions, which appear later in this document.
	2.	Double-click the Firefly.prefPane icon.  This will launch the System Preferences application, which will then offer to install the Preferences pane.  The System Preferences application will ask you to choose whether to make the pane available to just the current user, or to all users.  This choice is up to you.  If you choose to make it available to all users, then any user who logs into the system will be able to configure and run Firefly for their own library.  Otherwise, only the user who installed the software will be able to run it.

After installation, the System Preferences application will open the Firefly pane, so that you may configure Firefly.  If you are installing for the first time, or if you ran the "Uninstall Firefly" script above, then Firefly will not start until you make your selections and click "Start Firefly".  If you are upgrading from 1.0b3, all your settings should still be in place, so Firefly will start right away if it had previously been set to launch at login.

By default, Firefly will choose the name "<your name>'s Firefly on <your computer>", and will look for music in the Music folder in your home directory.  It will not require a password for devices or computers to play music from your library.  And, it will be set to run whenever you are logged in.  You may change any of these options at this time, before running Firefly for the first time.  If you decide to change them later, just open System Preferences and make your changes, then click the Apply Now button.

Once you have confirmed Firefly's settings, click the Start Firefly button.  If you have set Firefly to automatically start when you are logged in, you will only need to do this step this one time.  If you choose to start Firefly manually, you will need to click this button whenever you want to start Firefly.

Note that a user must be logged in for his/her library to be shared (although, if using Fast User Switching, they need not be the active user).

A note to users of the 1.0b1 and 1.0b2 versions
Because this installation is so different from previous beta versions of Firefly, it was not feasible to try to preserve the settings from earlier versions.  Therefore, the uninstall script removes all previous Firefly files, including your stored settings.  You will need to re-enter your configuration choices after installing Firefly for Macintosh 1.0.  Happily, this is a very simple process that takes only a few seconds.  

Issues fixed since 1.0b3
This release includes some important fixes for problems that were present in 1.0b3.
	•	A performance problem when connecting to Firefly from a copy of iTunes on a Mac or PC has been fixed.
	•	A problem with playlists not being correctly ordered when using the RSP protocol has been fixed.
	•	Various other updates and fixes.

Features added since 1.0b2
This release has some exciting new features:
	•	Apple Lossless audio files can now be played to SoundBridge client.  Firefly will "transcode" (convert on the fly) these files to uncompressed audio with no loss in quality.  You will notice if you get an Apple Lossless song's information on the SoundBridge's display that they show up as "WAV audio file".  This is expected, because Firefly is transcoding to WAV format.
	•	Added the ability to show a Firefly Status Item (a small icon/menu at the right side of the menu bar) to check Firefly's status and start and stop the server, without opening the Preferences pane.  This is controlled by a check-box in the Preferences pane.
	•	Added a "Log" tab to the Preferences pane to allow viewing the detailed log information from the server (helpful to diagnose any problems that may arise)
	•	Much simpler installation process -- all Firefly server components reside within the single Firefly.prefPane file.  Please carefully follow the installation instructions above.

Issues fixed since 1.0b2
This release fixes several issues that were present in 1.0b2:
	•	The release now works on 10.3.9 as well as 10.4.  Although we had hoped to provide support on MacOS 10.2, that is no longer planned.  So much changed on MacOS between 10.2 and 10.3 that maintaining compatibility with that old system is not practical.
	•	The server installation is now one file (as noted above).
	•	The server can now be installed either for all users of the computer, or for individual users.
	•	The server can now be installed by non-admin users.
	•	The server will now work properly even if multiple users are logged into the same Macintosh,  each running their own copies of Firefly.
	•	The default name for the library now includes the user's name, in order to make it unique in cases where multiple users are logged in.
	•	The server will now return playlist contents in the correct track order
	•	Generally, the communication between the Preferences pane and the server is much more robust and tolerant of errors.  The correct status should be displayed even if the server were to be shut down by means other than the Preference pane, and so on.  The server's state is also correctly shown as "starting" during the initial scan, before the server has registered itself on the network.

Issues fixed since 1.0b1
1.0b2 fixed several issues that were present in 1.0b1, so if you are updating from 1.0b1, the following issues are also fixed:
	•	Fixed a bug that caused the Preferences pane crash if the user's library name contained a non-ASCII character.
	•	Fixed a problem where clicking the Firefly logo in the Preferences pane failed to open the fireflymediaserver.org web page.
	•	Eliminated a spurious "restarting" message if the Preferences pane was closed with unsaved changes, but the server was not running.
	•	Fixed a problem in the installer that prevented installation in non-admin accounts.  Installer now requires administrator password to install.
	•	This version of Firefly, combined with the RC3 (2.5.171) release of SoundBridge software, now properly handles protected AAC files, and will properly skip files un-checked in iTunes if that option is enabled on the SoundBridge.
	•	This version features improved performance when scanning the iTunes library XML file.
	•	The server features a new and updated web user interface.
	•	Server does not attempt to transcode Apple Lossless files when playing to an iTunes client.
	•	Various other fixes.

Known Issues
There are a small number of known limitations and issues with this version that will be addressed in a later release:
	•	The Firefly software is currently only available in English.  We plan to release a localized version at a later date.
	•	If you manually edit the configuration file to add multiple music directories, the System Preferences pane will display incorrect information in the Library Location.  However, it should not disturb your settings if you don't try to use the pane to change the location.

What is Running?
If you look at the list of running processes on your computer while Firefly is running (for example, by using the "Activity Monitor" utility) it is normal to see three Firefly-related items.  There should be a program running called "Firefly Helper", and two processes called "firefly".  These all run completely in the background, and will not show up in the Dock.  They are normally only visible in the Activity Monitor utility.

Uninstalling Firefly
If you should decide that you want to uninstall Firefly, the easiest way to do so is to simply run the "Uninstall Firefly" script that is on the installation disk image.  If, however, you need to uninstall it manually, then please follow the steps in the next section.

Manually Uninstalling Firefly
If you should decide that you want to uninstall Firefly, please follow these steps:
	•	Open System Preferences and click on the Firefly icon
	•	If Firefly is running, click "Stop Firefly"
	•	If you are running Firefly 1.0b3 or 1.0, un-check the "Show Firefly menu in menu bar" box
	•	Change the "Start Server" option to "Manually", and click Apply Now
	•	Close System Preferences
	•	In the Finder, open your home folder
	•	Open the folder called Library
	•	Open the Application Support folder
	•	Drag the Firefly folder inside Application Support to the Trash
	•	If you installed 1.0b3 or 1.0 for the current user only, or if removing 1.0b1 or 1.0b2:
	•	Go back up one level to your Library folder
	•	If you installed 1.0b3 or 1.0 for all users:
	•	Open the window for your hard disk drive, and within that window, open the Library folder
	•	Open the PreferencePanes folder
	•	Drag Firefly.prefPane to the Trash
	•	Restart your computer, or log out and log in again

A Note to Expert Users
If you have made manual changes to your configuration file and are upgrading from 1.0b1 or 1.0b2, you will need to make your changes again.  If you want to refer to your old configuration file, it's in the "firefly-uninstall" folder in the Trash.  Users upgrading from 1.0b3 should see no change.

Please note that the layout of files on disk has changed significantly since 1.0b2.  The configuration file (now called "firefly.config"), the songs database and the log file (now "firefly.log") still live in ~/Library/Application Support/Firefly, and the pane itself is either in ~/Library/PreferencePanes or /Library/PreferencePanes, depending upon whether you chose to make Firefly available to the current user or to all users, respectively.  

However, the plugins folder and the transcoding scripts and binaries are now built into the Preference pane's bundle.  To find them, open the folder containing the preference pane and either right-click or control-click on the Firefly.prefPane icon.  Choose "Show Package Contents".  Open the "Contents" folder in the resulting window.  You should see the Firefly Helper application.  Repeat this process with the Firefly Helper, to view its contents.  Within the Firefly Helper's Contents folder, in a folder called "Server", you will find all of the components of the Firefly server itself, as well as the plugins and helper binaries.  Please be careful when modifying the contents of these bundles.