shairport-sync

AirPlay and AirPlay 2 audio player

7,152

568

7,152

View on GitHub

Top Related Projects

AirConnect

3,500

Use AirPlay to stream to UPnP/Sonos & Chromecast devices

Multitrack Web Audio editor and player with canvas waveform preview. Set cues, fades and shift multiple tracks in time. Record audio tracks or provide audio annotations. Export your mix to AudioBuffer or WAV! Add effects from Tone.js. Project inspired by Audacity.

Quick Overview

Shairport Sync is an open-source AirPlay audio player for Linux and other POSIX systems. It allows you to stream audio from iOS devices, macOS, and iTunes to any device running the software, effectively turning it into an AirPlay receiver.

Pros

Supports high-quality audio streaming, including lossless formats
Offers advanced features like metadata display and remote control
Compatible with a wide range of hardware, from Raspberry Pi to high-end audio systems
Actively maintained with regular updates and improvements

Cons

Setup can be complex for non-technical users
Limited to audio streaming only (no video support)
May require additional configuration for optimal performance on some systems
Occasional compatibility issues with certain AirPlay sources or network setups

Getting Started

To install Shairport Sync on a Debian-based system:

sudo apt-get update
sudo apt-get install build-essential git autoconf automake libtool libpopt-dev libconfig-dev libasound2-dev avahi-daemon libavahi-client-dev libssl-dev libsoxr-dev
git clone https://github.com/mikebrady/shairport-sync.git
cd shairport-sync
autoreconf -i -f
./configure --with-alsa --with-avahi --with-ssl=openssl --with-metadata --with-soxr --with-systemd
make
sudo make install
sudo systemctl enable shairport-sync
sudo systemctl start shairport-sync

After installation, your device should appear as an AirPlay target on your network. For more detailed configuration options, refer to the project's documentation on GitHub.

Competitor Comparisons

snapcast

6,082

Synchronous multiroom audio player

Pros of Snapcast

Multi-room audio synchronization across various devices and platforms
Supports multiple audio sources, including Spotify, MPD, and custom streams
Flexible client-server architecture allowing for easy scalability

Cons of Snapcast

Requires more setup and configuration compared to Shairport-sync
May have higher latency in some network configurations
Lacks native AirPlay support, requiring additional software for AirPlay functionality

Code Comparison

Snapcast (server setup):

Stream *stream = new Stream("pipe:///tmp/snapfifo?name=default", CODEC_PCM);
streamServer->addStream(stream);

Shairport-sync (configuration):

static int init(int argc, char **argv) {
  config.port = 5000;
  config.output_name = "alsa";
  return 0;
}

Both projects use C/C++ for core functionality, but Snapcast's modular approach allows for more flexible stream handling, while Shairport-sync focuses on AirPlay-specific implementation.

Snapcast offers broader multi-room audio capabilities, supporting various sources and platforms. Shairport-sync excels in providing a straightforward AirPlay receiver solution with potentially lower latency for Apple ecosystem users. The choice between them depends on specific use cases and desired features.

AirConnect

3,500

Use AirPlay to stream to UPnP/Sonos & Chromecast devices

Pros of AirConnect

Supports multiple streaming protocols (AirPlay, UPnP/DLNA, Sonos, Chromecast)
Can bridge between different streaming ecosystems
Works with a wider range of devices, including smart speakers and TVs

Cons of AirConnect

Less focused on high-quality audio output compared to Shairport-sync
May have higher latency due to protocol bridging
Less extensive metadata support for AirPlay streams

Code Comparison

Shairport-sync (audio processing):

int32_t endianness = 0x11223344;
char *pe = (char *)&endianness;
if (pe[0] == 0x11)
  host_endianness = SS_LITTLE_ENDIAN;
else
  host_endianness = SS_BIG_ENDIAN;

AirConnect (device discovery):

void *MRDeviceCreate(log_level level, void *owner, int max_volume, char *name, char *uuid, char *model)
{
	struct sMRDevice *p = malloc(sizeof(struct sMRDevice));
	p->magic = MAGIC;
	p->owner = owner;
	p->max_volume = max_volume;

Both projects aim to enable AirPlay functionality on various devices, but they differ in their approach and scope. Shairport-sync focuses on high-quality audio output and extensive AirPlay features, while AirConnect prioritizes compatibility across multiple streaming protocols and device types. The code snippets highlight their different emphases: Shairport-sync's attention to audio processing details, and AirConnect's focus on device discovery and management across various protocols.

librespot

4,702

Open Source Spotify client library

Pros of librespot

Native Spotify support, allowing direct streaming from Spotify's servers
Cross-platform compatibility (Linux, macOS, Windows, and more)
Supports Spotify Connect protocol for remote control

Cons of librespot

Limited to Spotify ecosystem, not compatible with other streaming services
Requires Spotify Premium account for full functionality
May have higher resource usage due to more complex features

Code Comparison

shairport-sync

int audio_play(void *buf, int samples) {
    return audio_backend->play(buf, samples);
}

librespot

pub fn play(&mut self) -> Result<(), Error> {
    self.player.play()?;
    Ok(())
}

Summary

shairport-sync focuses on AirPlay compatibility, providing a lightweight solution for streaming from Apple devices. librespot, on the other hand, specializes in Spotify integration, offering a more feature-rich experience for Spotify users. While shairport-sync is more versatile in terms of audio sources, librespot provides deeper integration with Spotify's ecosystem. The code snippets highlight the different approaches: shairport-sync uses C for low-level audio handling, while librespot employs Rust for a more modern, safe implementation.

waveform-playlist

1,452

Pros of waveform-playlist

Focuses on audio waveform visualization and playlist management
Provides a web-based interface for audio editing and playback
Supports multiple audio tracks and advanced editing features

Cons of waveform-playlist

Limited to web-based applications, unlike shairport-sync's system-level functionality
Requires more setup and integration for use in projects
May have higher resource usage for complex audio visualizations

Code Comparison

waveform-playlist (JavaScript):

var playlist = WaveformPlaylist.init({
  samplesPerPixel: 3000,
  mono: true,
  container: document.getElementById("playlist")
});

playlist.load([
  {src: "audio/track1.mp3"},
  {src: "audio/track2.mp3"}
]).then(function() {
  // playlist loaded
});

shairport-sync (C):

int main(int argc, char **argv) {
  // ...
  config.output = &audio_dummy;
  config.output_name = "dummy";
  config.output_device = "dummy";
  // ...
  shairport_startup_complete();
  // ...
}

The code snippets highlight the different focus areas of the two projects. waveform-playlist emphasizes audio visualization and web-based playlist management, while shairport-sync deals with system-level audio streaming and output configuration.

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

Shairport Sync

Shairport Sync is an AirPlay audio player for Linux, FreeBSD and OpenBSD. It plays audio streamed from Apple devices and from AirPlay sources such as OwnTone (formerly forked-daapd).

Shairport Sync can be built as an AirPlay 2 player (with some limitations) or as "classic" Shairport Sync â a player for the older, but still supported, AirPlay (aka "AirPlay 1") protocol.

Metadata such as artist information and cover art can be requested and provided to other applications. Shairport Sync can interface with other applications through MQTT, an MPRIS-like interface and D-Bus.

Shairport Sync does not support AirPlay video or photo streaming.

Quick Start

A building guide is available here.
A Docker image is available on the Docker Hub. Also see docker/README.md.
Next Steps and Advanced Topics are here.
Runtime settings are documented here.
Build configuration options are detailed in CONFIGURATION FLAGS.md.
The man page, detailing command line options, is here.
Some advanced topics and developed in ADVANCED TOPICS.

Features

Outputs AirPlay audio to ALSA, sndio, PulseAudio, Jack Audio, to a unix pipe or to STDOUT. It also has experimental support for PipeWire and limited support for libao and for libsoundio.
Metadata â Shairport Sync can deliver metadata supplied by the source, such as Album Name, Artist Name, Cover Art, etc. through a pipe or UDP socket to a recipient application program â see https://github.com/mikebrady/shairport-sync-metadata-reader for a sample recipient. Sources that supply metadata include iTunes and the Music app in macOS and iOS.
An interface to MQTT, a popular protocol for Inter Process Communication, Machine-to-Machine, Internet of Things and Home Automation projects. The interface provides access to metadata and artwork, and has limited remote control.
Digital Signal Processing facilities â please see the DSP Wiki Page Guide. (Thanks to Yann PomarÃ¨de for the code and to Paul Wieland for the guide.)
An MPRIS-like interface, partially complete and very functional, including access to metadata and artwork, and limited remote control.
A native D-Bus interface, including access to metadata and artwork, limited remote control and system settings.
Better Volume Control â Shairport Sync offers finer control at very top and very bottom of the volume range. See http://tangentsoft.net/audio/atten.html for a good discussion of audio "attenuators", upon which volume control in Shairport Sync is modelled. See also the diagram of the volume transfer function in the documents folder. In addition, Shairport Sync can offer an extended volume control range on devices with a restricted range.
Support for the Apple ALAC decoder (library available here).
Output bit depths of 8, 16, 24 and 32 bits, rather than the standard 16 bits.
Output frame rates of 44,100, 88,200, 176,000 or 352,000 frames per second.

Some features require configuration at build time â see CONFIGURATION FLAGS.md.

Status

Shairport Sync was designed to run best on stable, dedicated, stand-alone low-power "headless" systems with ALSA as the audio system and with a decent CD-quality Digital to Analog Converter (DAC).

Shairport Sync runs on recent (2018 onwards) Linux systems, FreeBSD from 12.1 onwards and OpenBSD. It requires a system with the power of a Raspberry Pi 2 or a Pi Zero 2 or better.

Classic Shairport Sync runs on a wider variety of Linux sytems, including OpenWrt and Cygwin and it also runs on OpenBSD. Many embedded devices are powerful enough to power classic Shairport Sync.

Heritage and Acknowledgements

The functionality offered by Shairport Sync is the result of study and analysis of the AirPlay and AirPlay 2 protocols by many people over the years. These protocols have not been officially published, and there is no assurance that Shairport Sync will continue to work in future.

Shairport Sync is a substantial rewrite of the fantastic work done in Shairport 1.0 by James Wah (aka abrasive), James Laird and others â please see this list of the contributors to Shairport 1.x and Shairport 0.x. From a "heritage" point of view, Shairport Sync is a fork of Shairport 1.0.

For the development of AirPlay 2 support, special thanks are due to:

JD Smith for really thorough testing, support and encouragement.
ejurgensen for advice and code to deal with pairing and encryption.
ckdo for pointing the way, particularly with pairing and encryption protocols, with a functional Python implementation of AirPlay 2.
invano for showing what might be possible and for initial Python development.
Charles Omer for Docker automation, repository management automation, testing, encouragement, enthusiasm.

Much of Shairport Sync's AirPlay 2 functionality is based on ideas developed at the openairplay airplay2-receiver repository. It is a pleasure to acknowledge the work of the contributors there.

Thanks to everyone who has supported and improved Shairport Sync over the years.

More about Shairport Sync

The audio that Shairport Sync receives is sent to the computer's sound system, to a named unix pipe or to STDOUT. By far the best sound system to use is ALSA. This is because ALSA can give direct access to the Digital to Analog Converter (DAC) hardware of the machine. Audio samples can be sent through ALSA directly to the DAC, maximising fidelity, and accurate timing information can be obtained from the DAC, maximising synchronisation. Direct access to hardware is given through ALSA devices with names beginning with hw:.

Synchronised Audio

Shairport Sync offers full audio synchronisation. Full audio synchronisation means that audio is played on the output device at exactly the time specified by the audio source. To accomplish this, Shairport Sync needs access to audio systems â such as ALSA on Linux and sndio on FreeBSD and OpenBSD â that provide very accurate timing information about audio being streamed to output devices. Ideally, Shairport Sync should have direct access to the output device used, which should be a real sound card capable of working with 44,100, 88,200 or 176,400 samples per second, interleaved PCM stereo of 8, 16, 24 or 32 bits. Using the ALSA sound system, Shairport Sync will choose the greatest bit depth available at 44,100 samples per second, resorting to multiples of 44,100 if it is not available. You'll get a message in the log if there's a problem. With all other sound systems, a sample rate of 44,100 is chosen with a bit depth of 16 bit.

Shairport Sync works well with PulseAudio, a widely used sound server found on many desktop Linuxes. While the timing information is not as accurate as that of ALSA or sndio, it is often impractical to remove or disable PulseAudio.

For other use cases, Shairport Sync can provide synchronised audio output to a unix pipe or to STDOUT, or to audio systems that do not provide timing information. This could perhaps be described as partial audio synchronisation, where synchronised audio is provided by Shairport Sync, but what happens to it in the subsequent processing chain, before it reaches the listener's ear, is outside the control of Shairport Sync.

Latency, "Stuffing", Timing

AirPlay protocols use an agreed latency â a time lag or delay â between the time represented by a sound sample's timestamp and the time it is actually played by the audio output device, typically a Digital to Audio Converter (DAC). Latency gives players time to compensate for network delays, processing time variations and so on. The latency is specified by the audio source when it negotiates with Shairport Sync. AirPlay sources set a latency of around 2.0 to 2.25 seconds. AirPlay 2 can use shorter latencies, around half a second.

As mentioned previously, Shairport Sync implements full audio synchronisation when used with ALSA, sndio or PulseAudio audio systems. This is done by monitoring the timestamps present in data coming from the audio source and the timing information coming back from the audio system itself. To maintain the latency required for exact synchronisation, if the output device is running slow relative to the source, Shairport Sync will delete frames of audio to allow the device to keep up. If the output device is running fast, Shairport Sync will insert ("stuff") extra frames to keep time. The number of frames inserted or deleted is so small as to be almost inaudible on normal audio material. Frames are inserted or deleted as necessary at pseudorandom intervals. Alternatively, with libsoxr support, Shairport Sync can resample the audio feed to ensure the output device can keep up. This is less obtrusive than insertion and deletion but requires a good deal of processing power â most embedded devices probably can't support it. If your computer is fast enough, Shairport Sync will, by default, automatically choose this method.

Stuffing is not done for partial audio synchronisation â the audio samples are simply presented at exactly the right time to the next stage in the processing chain.

Timestamps are referenced relative to the source computer's clock â the "source clock", but timing must be done relative to the clock of the computer running Shairport Sync â the "local clock". So, Shairport Sync synchronises the source clock and the local clock, usually to within a fraction of a millisecond. In AirPlay 2, this is done with the assistance of a companion application called NQPTP using a PTP-based timing protocol. In classic AirPlay, a variant of NTP synchronisation protocols is used.

Top Related Projects

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot