Profiles
=========

Two profiles are defined to adapt for packet latency, namely WIFI, ETHERNET.
By default, `WIFI` profile is applied. `WIFI` profile is more tolerant to packet latency
To force ETHERNET profile, run

  java -DAIRPLAY_RAOP_PROFILE=ETHERNET -jar AirReceiver-1.2.one-jar.jar

AirReceiver
===========

Paul Gundarapu
Jun 2014

Added new AudioQueue implementation to make it work on Raspberry Pi.
The trade off here is that we see latency in the Audio and thereby may
not be suitable for video viewing. However, audio seems to work fine on
Pi, tested with 1000MHz CPU overclocked freq (headless with no hdmi
connection). Pi was very much responsive at all the times.

Implementation Detail:
1. We wait for a 300 frame buffer to fill before writing to the line.
2. A new LinkedSortedQueue is implemented that would work with the
order in which data is typically streamed. Queue is made completely thread-safe.
3. If the gap frames exceed 300secs, we clear the Queue i.e., drop all
packets received so far.

The new implementation decreased the processing power to all the way
of utilizing only 45% to 50% on Pi. Having said that if the line has too much
re-transmission, the older frames will be retransmitted later and the stream
insertion into the Queue will take longer, i.e., more processing power as we
ask the sorted queue to insert the new data by starting it's search at the end.
No issues on a Mac.


Florian G. Pflug <fgp [at] phlo.org>
May 2011

Overview
--------
AirReceiver is an AirPort Express emulator, i.e. it allows streaming audio
from iTunes and iOS devices to a computer running AirReceiver. It does so by
implementing a RAOP/AirTunes2 server.

Features
--------
AirReceiver is compatible with iTunes and iPhones/iPods. It implements not
only raw audio streaming but also the timing-related parts of RAOP/Airtunes2.

RAOP/AirTunes requires that the device (the computer running AirReceiver)
adapts itself to the rate at which iTunes or iOS streams the sound. AirReceiver
currently does that simply by repeating samples (in case iTunes/iOS sends
slightly slower than your sound card emits the signal) or dropping samples
(in case iTunes/iOS sends slightly faster). This can lead to audible clicks
in audio output every few seconds or every few minutes, depending in how
large the clock drift between the two devices is.

AirReceiver will hopefully eventually gain the ability to deal with drifting
clocks more gracefully by dynamically resampling the audio stream, but it
isn't there yet.

Working Platforms
-----------------
In principle, any platform for which Java 1.6 Standard Edition compatible
VM is available should work. AirReceiver contains no native (non-Java) code.

AirReceiver has been confirmed to work on Mac OS X 10.6 i386 with the 64-bit
VM and on Windows XP with the 32bit VM.

Reports of experiences with AirReceiver on other platforms are highly
appreciated!

Usage
------
If you're on Mac OS X, download the AirReceiver-app.zip from the bin/ folder
(or use the large Download button), unzip it, and launch it.

If you're on Windows or Linux, download the AirReceiver.one-jar.jar and
double-click it (or type java -jar AirReceiver.one-jar.jar on the command
line).

Either way, give it about half a minute to announce itself on the network,
then choose it as output device on your iOS device or in iTunes.

iTunes adds an icon in the bottom right corner once it has detected a
compatible device, iOS shows the icon next to the previous, pause, next
buttons.

Installation
------------
No installation is required, simply download the appropriate package
(either the app or the jar) for your platform and launch it.

License
-------
AirReceiver is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

AirReceiver is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with AirReceiver.  If not, see <http://www.gnu.org/licenses/>.

AirReceiver contains code written by soiaf, check the file license.txt
in src/main/java/com/beatofthedrum/alacdecoder

References & Acknowledgements
-----------------------------
* ShairPort written by James Laird
  http://mafipulation.org/blagoblig/reversing, https://github.com/albertz/shairport
  AirReceiver wouldn't haven been possible to write without the work James Laird
  put into reverse-engineering the protocol and encryption.
  
* ALAC Decoder written David Hammerton and ported to Java by soiaf
  https://github.com/soiaf/Java-Apple-Lossless-decoder
 
* Java mDNS - ZeroConf (Bonjour(TM) in Apple terms) implementation for Java
  http://jmdns.sourceforge.net/
  Provides AirReceiver with the ability to announce it's service on the
  local network without having to resort to platform-specific code
  like Apple's Bonjour Java bindings (which aren't available on Linux
  anyway)
 
* Netty by the JBoss Community
  http://www.jboss.org/netty
  Netty makes writing network server in Java pure joy. Writing the RTSP server
  component was a breeze with netty's built-in support for HTTP and RTSP.
  
* BouncyCastle Java Cryptography Provider
  http://www.bouncycastle.org/
  BouncyCastle included all of the RSA and AES variants used by RAOP/AirTunes2
  
* Base64 Encoder/Decoder by iharder
  http://iharder.sourceforge.net/current/java/base64/
  iharder's Base64 decode saved me a few hours it'd otherwise probably have spent
  writing and debugging an base64 encoder/decoder myself.
  
* Maven
  http://maven.apache.org/
  Hassle-free dependency management. And a helluva lot of plugins, usually
  just a few google searches away.

* OneJar packaging plugin for maven
  http://one-jar.sourceforge.net/
  Provides the double-clickable .jar files, and all that's required was adding
  a few lines to AirReceiver's .pom
  
* Mac OS X application packaging plugin for maven
  http://mojo.codehaus.org/osxappbundle-maven-plugin/
  Add a few lines to your .pom and, there, you've built a Mac OS X application
  bundle from your Java application. Cool!