This the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Documentation

Welcome to our project documentation page, as by now you will not find much here as it is currently being written.

1 - Overview

What and where to find it.

Welcome to the OtterCast documentation. Please see the sections below or on the left for what you are looking for. If your questions couldn’t be answered here, please check our Community page for help.

What is it?

OtterCast is an open-source audio streaming device running Linux. Based on a Sochip S3 SoC, featuring a Webinterface, shairport-sync, snapcast, Spotify Connect and pulseaudio sink/source.

Why do I want it?

Because it plays your favorite music over the air, reliably, whenever you need it.

Where should I go next?

2 - Getting Started

How to get started?

Get your device

You still need the Hardware? We are planning a small production run, but until that has happened, please refer to the production files and instructions located in our repositories.

Get the firmware

After acquiring your device, you may head to our firmware section.

Flashed, and now?

You can mount the SD-Card and change the initial configuration by edition the config.ini file, present on the first partition. You should add your Wifi credentials and give your Ottercast a lovely hostname, it will be displayed later when you are casting! If you need SSH access, you can add your public key by creating a ssh_authorized_keys file containing your key.

It works!

Great, you did it! You may now check out the supported protocols and start casting or visit your Ottercasts web-interface by typing <hostname>.local into your browsers address bar.

3 - Firmware

Details about the Firmware, Software, Webinterface

Ottercast Firmware is built using buildroot.
It’s running a mainline Linux kernel, with GNU userland, systemd, PulseAudio and Avahi.

Download ready-made images

Current firmware binaries can be found on GitHub at:
Ottercast/buildroot-ottercast-audio

Firmware images are automatically built for each commit via GitHub Actions.

Flashing the image

The procedure is identical to a Raspberry Pi. Make sure to unzip (.gz/gzip) the firmware before writing it to a card.
Firmware binaries are disk images, containing partitions and can be written directly to an SD card or eMMC flash.

Do NOT copy the file onto a SD card as a file.
It needs to be written as a disk image using a tool like Etcher, Win32 Disk Imager or dd.

Initial configuration

After flashing, you can mount the FAT32 partition and edit the config.sh and (optional) ssh_authorized_keys.
Configure your WiFi credentials, SSH public keys and a name for the device.

Building your own image

Building your own image can be done on a regular x86_64 machine running Linux.

Make sure to fulfill the buildroot dependencies:

DistributionCommand
Arch/Manjaropacman -S base-devel git wget perl unzip rsync ncurses
Debian/Ubuntu/Mintapt install build-essential git wget unzip rsync libncurses-dev

These dependency lists are untested, please report if something is missing!

mkdir ottercast
cd ottercast
git clone https://github.com/Ottercast/buildroot-ottercast-audio.git
wget https://buildroot.org/downloads/buildroot-2021.02.1.tar.gz
tar xfv buildroot-2021.02.1.tar.gz
cd buildroot-2021.02.1/
make BR2_EXTERNAL=../buildroot-ottercast-audio/buildroot/ ottercast_s3_defconfig

This will generate a config file in the buildroot folder.

(optional) Use make menuconfig to change buildroot settings (enable/disable packages, compile settings, etc.).
(optional) Use make linux-menuconfig to change kernel parameters.

Compile the firmware using make -j$(nproc).
This will take ~60min on a very fast machine with stable internet connection.
First compilation will download, compile and assemble a full Linux installation from scratch.
This can take up to several hours. Be patient! Changes will build much faster.

The resulting disk image will be located at buildroot-(version)/output/images/sdcard.img.

The external tree can be found at: https://github.com/Ottercast/buildroot-ottercast-audio.

Webinterface

The webinterface is written in PHP and running as a CGI script.
uhttpd is used as a webserver and serves /var/www on Port 80 via HTTP.
Frontend is using Bootstrap and jQuery.

4 - Supported protocols

Which audio streaming services/protocols are supported?

Ottercast is open source! If your favorite app/protocol is missing, open an Issue or integrate it yourself and send a Pull Request.

Snapcast

Snapcast is a multiroom-capable network audio player.
Ottercast can act as a Snapcast client and will connect to a Snapcast server which is streaming audio.
Multiple Ottercasts (and other Snapcast clients) can connect to the same server and will play perfectly synced audio.

Ottercast can also work as a Snapcast server and stream audio from it’s Line-In port to multiple Snapcast clients.

Spotifyd / Spotify Connect

Spotifyd is a Spotify Connect client, written in Rust, utilizing the librespot library.
Requires Spotify Premium.

Screenshot of Spotifyd

Shairport Sync / AirPlay

Shairport Sync is an open source reimplementation of the AirPlay protocol.
You can select your Ottercast as an AirPlay target on your iOS/macOS devices.
Shairport supports full audio synchronisation, which means audio/video sync will be enforced.

Screenshot of Airplay

PulseAudio Sink

Ottercast can act as a PulseAudio Sink via module-native-protocol-tcp.
Use paprefs to enable local discovery and ensure avahi-daemon is running.

Screenshot of paprefs