Read Me

------------------------------------------------------------------------------
README
------------------------------------------------------------------------------
version 1.0, written by Kai Widmann, nastunes@high-fidelity.net, 16th May 2009

------------------------------------------------------------------------------
WHAT IS NASTUNES
------------------------------------------------------------------------------
nasTunes streams music and videos from your NAS (or any computer in your
network) to your iPhone or iPod Touch (or any device with a web browser).
Since nasTunes doesn't need any media server like Firefly or SqeezeCenter to
run, it's fast even on low budget devices.

nasTunes runs or your NAS and since it's accessed with Safari or any web
browser you don't need any special app to listen to your music or watch your
videos. If you have access to your NAS through the internet (for example by
way of DynDNS), you can access your media from any web browser anywhere in the
world (though as of yet the interface is optimized for iPhone/iPod Toch use
only).

What you need
-------------
 - Wireless LAN and a NAS device or any computer running a web server like
   lighttpd or Apache and PHP. Many NAS devices use Linux, so even if there's
   no web server or PHP preinstalled, it can be done on many devices.
 - A music library that's stored in a specific directory structure (one folder
   for each artist, one subfolder for each record, that's the iTunes standard
   structure many people use for their library).
 - An iPhone or iPod Touch, Safari (or any device with web browser) for
   accessing the nasTunes web interface.

What you get
------------
 - A fast way to browse your music and video library without the need to sync
   your iPhone/iPod Touch
 - Playback your music in any room of your home using the WIFI network and an 
   iPod dock. No need for expansive hardware. If you have access to your NAS
   through the internet you can even access your media files anywhere in the
   world (as long as you're online).
 - Full text search for artists
 - Covers and ID3 info (artist, album name, year, genre) will be shown - if
   existent - for albums. nasTunes uses the library getID3() by James Heinrich
   to access ID3-data.
 - List of recently played albums
 - Playback options for albums: Loop, Shuffle, play from specific track, play
   selected tracks, loop selected tracks, shuffle selected tracks.
 - Parental control: For those who don't want to share everything in their
   library there's the possibility to hide artists and albums. If you use http
   authentication there's the possibility to define a superuser who can see
   all items.

What you don't get (yet)
------------------------
Since nasTunes was specifically developed for low budget NAS devices and speed
was the prime concern, there are some functions missing that one can usually
find in similar software. These features may be implemented in future releases
of nasTunes.

 - Search for albums and songs: All the artist, album and song information is
   read from the file system. So as of yet there's is no search function for
   albums or songs, since it would just be too slow to get that kind of
   functionality without the use of a database.
 - Support for playlists has not been implemented yet.


------------------------------------------------------------------------------
WHY NASTUNES
------------------------------------------------------------------------------
Some time ago I was lucky enough to get my hands on a cheap iPod Touch. I
already had a NAS that was used to backup my iTunes library. So I thought "I
have all my media on the NAS, the NAS can be accessed through WLAN, the iPod
touch has built in WLAN; so it should be possible to listen to all my music
and watch all my videos on the iPod Touch without any syncing (Why use cables
when there's WLAN?)".

So I installed an iTunes server (Firefly) on my NAS. I was quite disappointed
to find out that streaming from an iTunes server to the iPod Touch doesn't
work. Why on earth is that not possible? The iPod touch has WLAN access, I
have an iTunes server running within my WLAN and yet I can't access it.
Incredible.

Then I thought that I surely am not the only person who wants to do this. A
few googles later I had found out that there's a UPNP AV Server that can be
installed on my NAS and a UPNP AV client for the iPod Touch. Well, I tried
that and it was so slow, that it just wasn't usable. Same result with
Squeezeserver / Squeezecenter. Oh so slow. Back to Firefly, this time paired
with Crossfire, a PHP Firefly client that runs on the NAS and can be accessed
from the iPod Touch using Safari. Again Same result. Way too slow for my
taste. 

But with Crossfire i had made an important discovery: It's possible to use PHP
to stream music and video files to Safari on the iPod Touch. I used to program
in PHP some six years ago (I'm a professional Java programmer now), so I got
reacquainted with PHP, I delved into research about Apple's Quicktime plugin
that's used by Safari to play music and videos over the network and finally I
started hacking code into my keyboard. After two days of fanatic coding I had
an ugly prototype up and running. After a few more days it wasn't that ugly
anymore.

I've been using nasTunes for a few weeks now, listening to music and watching
videos almost every day. And now I think it is ready to be given to the
freeware community. It's my first freeware project and I'm not sure if anyone
is interested in it, but since you are reading this, there seems to be at
least one person who is willing to give it a try.

Feel free to contact me by mail (nastunes@high-fidelity.net) or post to the
forums at sourceforge.net (https://sourceforge.net/forum/?group_id=258477) if
you have any questions or suggestions. 


------------------------------------------------------------------------------
HOW TO INSTALL NASTUNES
------------------------------------------------------------------------------

The Installation in a nutshell
------------------------------
Do the following on your NAS:
 - install and configure a web server (lighttpd or apache or any other web 
   server)
 - install and configure PHP 5.x
 - copy the nasTunes sources to your document root (or to a subfolder if you
   want)
 - configure nasTunes by editing the file nastunes/conf/config.inc


INSTALLATION DETAILS
------------------------------------------------------------

If you already have a webserver and PHP running on your NAS you can skip to
chapter 2.

1 INSTALLATION OF A WEBSERVER AND PHP
-------------------------------------

These instructions are valid for the following devices:
 - Conceptronic CH3SNAS
 - D-Link DNS-323

The CH3SNAS and the DNS-323 are compatile. I own the CH3SNAS so this is the
only device I can use to test nasTunes and the only device I can use as
reference for these instructions.
There are many sites on the web explaining how to get lighttpd or apache and
PHP up and running on specific devices. Just use the search engine of your 
choice and search for "apache OR lighttpd OR webserver php" plus the name of
your device.

The CH3SNAS is running Linux. To install lighttpd and PHP there's a special
plugin needed called "ffp" developed by fonz. The ffp homepage is located at
http://www.inreto.de/dns323/fun-plug/0.5/. There's also a WIKI page at 
http://wiki.dns323.info/howto:ffp. 

The ffp plugin should work with the following devices:
 - Acer Aspire EasyStore
 - Conceptronic CH3SNAS
 - D-Link DNS-323
 - D-Link DNS-343
 - Linksys WRT 350N
 - MRT 35HD-Dual-NAS-E
 - PCI MZK-NAS01SG
 - PCI MZK-NAS02SG
 - Raidsonic IB-4220-B
 - Zyxel NSA-220
The following instructions should be valid for all of these devices, but since
I only own the CH3SNAS I can't guarantee it will work (and I won't guarantee
that it will work on the CH3SNAS either, but it works on mine).

1.1 Install ffp
---------------
Follow the instructions on http://nas-tweaks.net/CH3SNAS:Tutorials/fun_plug
There's also a site in german describing the installation:
http://wolf-u.li/1426/fun_plug-05-auf-dem-conceptronic-ch3snas-bzw-d-link-dns-323-installieren/
I used wolf-u.li's great instructions for my first steps with ffp. If you 
happen to speak german I really recommend that you have a look at his site.
He's writing about a lot of tweaks for the CH3SNAS (and therefore also for the
DNS-323).

1.2 Install lighttpd and PHP
----------------------------
 - Download lighttpd-1.4.22-1.tgz and php-5.2.6-3.tgz from fonz' repository at
   http://www.inreto.de/dns323/fun-plug/0.5/
 - Put the downloaded files in the directory /ffp/pkg/packages in the Volume_1
   share on your NAS
 - log in to your NAS and install the packages using the following commands
   - funpkg.sh /ffp/pkg/packages/lighttpd-1.4.22-1.tgz
   - funpkg.sh /ffp/pkg/packages/php-5.2.6-3.tgz
 - rename the file /ffp/etc/lighttpd.conf-with-php-sample in the Volume_1
   share on your NAS to lighttpd.conf
 - if you want you can change the webserver's document root by editing
   lighttpd.conf. The default document root is /mnt/HD_a2/www/pages/
 - configure auto start for lighttpd: log in to your NAS again, go to 
   /ffp/start, execute the command "chmod a+x lighttpd.sh" (without the
   quotes).
 - start lighttpd with the command "./lighttpd.sh start" (again without
   the quotes) or by rebooting your NAS

Again there's a tutorial on how to setup lighttpd and PHP in german by 
wolf-u.li:
http://wolf-u.li/760/webserver-lighttpd-mit-php52-auf-dem-conceptronic-ch3snas-installieren/


2 INSTALL AND CONFIGURE NASTUNES
--------------------------------

2.1 Assign a static IP to your NAS
----------------------------------
nasTunes needs to run on a NAS with a static IP. So the first thing to do is 
to assign a static IP to your NAS in your router's configuration. See your 
router's documentation on how to do that.

2.2 Copy nasTunes to your NAS
-----------------------------
Place the nasTunes folder with all its contents in your webservers's document
root. 

2.3 Configure nasTunes
----------------------
Edit the file [document root]/nastunes/conf/config.inc and adjust the settings
to your needs. The file is well documented, every option should be explained
well enough for you to understand what to do. If you have questions about the
configuration please post them in the help forum on sourceforge.net:
https://sourceforge.net/forum/forum.php?thread_id=3275403&forum_id=937924

2.4 Use nasTunes
----------------
To run nasTunes open Safari on you iPhone/iPod Touch and go to 
http://[IP of your NAS]/nastunes. You should see the nasTunes start screen.
Enjoy!