From c79f077db7a79dd953bee68c51b1c4b863051d62 Mon Sep 17 00:00:00 2001
From: xengineering <me@xengineering.eu>
Date: Wed, 24 Jan 2024 20:43:54 +0100
Subject: doc: Switch protocol, format and codec

The following changes are included in this commit:

- multicast to unicast
- UDP to TCP
- Matroska to ogg
- MP3 to FLAC

Switching to these protocols has several advantages. Avoiding multicast
makes it unnecessary to care about the available multicast addresses in
the local network. Unicast addresses are anyway assigned by DHCP. In a
multi-room setup this has of course the disadvantage that the same data
might be streamed via separate connections. The bandwidth requirement
would be multiplied by the number of soundbox devices. But since a
stream takes around 2 Mbit/s and we live in a world where 100 Mbit/s in
a local network should not be a problem the inefficiency can be
neglected.

Switching from UDP to TCP has the advantage that the stream is
transmitted reliably. Furthermore it avoids the situation that multiple
clients stream to the same soundbox simultaneously since a
single-connection TCP server is used.

The switch from Matroska to ogg is done because the ogg format is
recommended on the FLAC homepage. FLAC is used instead of MP3 because it
is a lossless audio compression format. This is obviously superior
compared to the lossy MP3 format regarding audio quality.
---
 doc/documentation.tex | 56 ++++++++++++++++++++++++++++++++++++++++++---------
 1 file changed, 47 insertions(+), 9 deletions(-)

diff --git a/doc/documentation.tex b/doc/documentation.tex
index fe58ba6..a6ba82b 100644
--- a/doc/documentation.tex
+++ b/doc/documentation.tex
@@ -72,11 +72,15 @@ seconds a new discovery packet is emitted by soundbox. Thus it can take up to
 \section{Playing audio} \label{playing-audio}
 
 Audio can be streamed to \texttt{soundbox} devices with the \texttt{ffmpeg}
-command. Audio files or internet stream addresses can be passed as input.
+command. Audio files or internet stream addresses can be passed as input. Since
+\texttt{ffmpeg} supports multiple outputs, multiple \texttt{soundbox} devices
+can be targeted with their IP addresses.
 
 \begin{verbatim}
-ffmpeg -re -i <input> -acodec libmp3lame -f matroska \
-    udp://224.0.0.99:5316
+ffmpeg -re -i <input> \
+    -acodec flac -f ogg tcp://<ip-1>:5316 \
+    -acodec flac -f ogg tcp://<ip-2>:5316 \
+    ...
 \end{verbatim}
 
 More details about FFmpeg streaming can be read from the FFmpeg streaming
@@ -261,26 +265,60 @@ option has to be inserted instead:
 echo 'dtparam=audio=on' >> /media/mmcblk0p1/config.txt
 \end{verbatim}
 
+\subsection{soundbox script}
+
+soundbox uses the command \texttt{ffplay} for playback. A script has to be
+added to call the command over and over again to allow new connections. The
+script can be added with \texttt{echo} and is made executable with
+\texttt{chmod}. \texttt{lbu add} will make sure that the script will be made
+persistent by calling \texttt{lbu commit} later (see
+section~\ref{lbu-persistence}).
+
+\begin{verbatim}
+echo '#!/bin/ash
+
+set -e
+
+while true
+do
+    ffplay -autoexit tcp://0.0.0.0:5316?listen
+done' > /usr/local/bin/soundbox
+
+chmod 755 /usr/local/bin/soundbox
+
+lbu add /usr/local/bin/soundbox
+\end{verbatim}
+
+This makes the command \texttt{soundbox} available on the system.
+
 \subsection{Service configuration}
 
 To receive audio streams via the network it is required to run the
-\texttt{ffplay} command continuously. This is possible by creating a service
-file for the OpenRC init system with \texttt{echo} and enabling the service
-with \texttt{rc-update}.
+\texttt{soundbox} command continuously. This is possible by creating a service
+file for the OpenRC init system with \texttt{echo}, making that executable with
+\texttt{chmod} and enabling the service with \texttt{rc-update}. Also here
+\texttt{lbu add} makes sure that the service file will be made persistent later
+(see section~\ref{lbu-persistence} for details).
 
 \begin{verbatim}
 echo '#!/sbin/openrc-run
 
 name="soundbox"
-command="/usr/bin/ffplay"
-command_args="udp://224.0.0.99:5316"
+command="/usr/local/bin/soundbox"
+command_args=""
 pidfile="/run/soundbox.pid"
 command_background=true' > /etc/init.d/soundbox
 
+chmod 755 /etc/init.d/soundbox
+
 rc-update add soundbox default
+
+lbu add /etc/init.d/soundbox
 \end{verbatim}
 
-\subsection{Persistence of changes and reboot}
+This will make sure the soundbox script is run on every boot.
+
+\subsection{Persistence of changes and reboot}\label{lbu-persistence}
 
 Since a diskless Alpine Linux installation is preferred for soundbox the
 changes have to be made persistent with \texttt{lbu}. Rebooting after it makes
-- 
cgit v1.2.3-70-g09d2