| Age | Commit message (Collapse) | Author |
|---|
|
|
|
|
|
Since the name is contained inside the mail address it is not required
to add both.
Adding the email address is important for all kinds of feedback. This
might include general reactions to the project, feature requests, legal
questions or patches for improvements.
|
|
This is very important information for every reader so it should be part
of the first section.
|
|
The text of each used license is added to the documentation PDF since
this might be passed to third parties without the source or build tree.
Adding the licenses to the PDF makes sure they are always accessible.
|
|
The CERN Open Hardware License is not restricted to mechanical or
electrical design files but instead has a very wide scope (see section
1.3 of the OHL).
Thus it can be applied to all contents of this repository. Having only
one license makes the license structure for this project way easier.
Since the OHL is written with hardware in mind it likely fits better to
this open hardware project.
|
|
The lldpd homepage [1] mentions Unix operating systems as host systems,
not only Linux. Furthermore there is a possibly working homebrew package
for MacOS.
[1]: https://lldpd.github.io
[2]: https://formulae.brew.sh/formula/lldpd#default
|
|
|
|
Since otherwise the Git describe output / version information is only
embedded into the file name the risk is given that Git version
information is lost by renaming the file.
|
|
The new format is closer to e.g. 'man 1 printf'.
|
|
This was never part of an installation but instead of a configuration
step.
|
|
This is the central reference what is required to build soundbox
devices.
|
|
The introduction was very limited so far but is important to manage
expectations regarding the device.
|
|
This new chapter should be the one with the highest level of details.
The section about versioning is also moved there with this commit.
|
|
Using the date of the build makes it not-reproducible. This should be
avoided. Furthermore the date on the front page should anyway reflect
when the source of the document was created. Not when it was converted
into a PDF.
|
|
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.
|
|
The default streaming guide is now far away from the original taken from
the FFmpeg streaming guide.
Since the command can handle a lot of inputs its also not useful to send
sine waves to soundbox devices.
|
|
|
|
This makes sure the audio-receiving software `ffplay` runs all the time.
|
|
|
|
This makes a soundbox device discoverable via the Link Layer Discovery
Protocol (LLDP). That way a client application can lookup the available
soundbox devices inside the network to display playback options.
|
|
While transcoding to a lossy formate like MP3 is not recommended [1]
forquality reasons it has the advantage that alway UPD / Matroska / MP3
is used for soundbox. That way the stream can be stopped and started at
any time without re-launching ffplay on the soundbox device. This could
make the SSH connection to the soundbox not longer needed.
[1]: https://trac.ffmpeg.org/wiki/Encode/HighQualityAudio#WhenshouldItranscodeaudio
|
|
|
|
The Matroska format has to advantage that a stream can be stopped and
the restarted at any time without executing new commands on the soundbox
device.
Since Matroska and RTP have similar / redundant features [1] the
transport protocol is switched to plain UDP.
[1]: https://en.wikipedia.org/wiki/Comparison_of_video_container_formats#cite_note-22
|
|
|
|
This allows to stream to multiple devices at the same time. Nevertheless
it still works for a point to point stream.
|
|
The soundbox software should be portable to other Raspberry Pis without
the HiFiBerry DAC too.
|
|
|
|
The music streaming documentation used to enforce re-encoding via ffmpeg
to save bandwidth. This led to pretty poor audio quality. This is not
the purpose of soundbox. It is assumed that the user wants the highest
possible audio quality as default.
|
|
Configuring the Alpine Linux operating system correctly for soundbox is
not trivial. Since it is very important it has to be documented in
detail.
|
|
The tar-based installation is more difficult to explain but has the
advantage that the partition size is maximized from the beginning. This
is way easier than resizing the partition after the installation.
|
|
This is currently the recommended OS installation for soundbox.
|
|
There used to be no extra space between paragraphs which in combination
with no indentation was not useful.
|
|
This flag makes sure the file is streamed in native frame rate and not
e.g. way faster. This is the expected behaviour.
|
|
This port should be used in the future as soundbox standard port.
|
|
This allows more testing than only streaming sine waves.
|
|
This documents a basic FFmpeg streaming example so that soundbox devices
can be tested.
|
|
This section is important to communicate how to interpret version
numbers in the context of this device repository.
|
|
This is required to build the table of contents and similar parts of the
document correctly.
|
|
Inside the artifacts folder aswell as inside the source folder adding a
'soundbox-' prefix to files is uncommon. In both cases only the root level
folder should contain the name 'soundbox' to remove redundancies.
|
|
|
|
This document will be quite long. Thus the report document class is more
suitable.
|
|
This draft should give an overview of the planned sections which is
useful to decide what should belong into the first sections and what
should be written in later ones.
|
|
The build system should convert the documentation source files
automatically to a single PDF file to make documentation generation
trivial.
|
|
This LaTeX document should contain the full device documentation for
soundbox. It will not cover aspects about the source or how to build.
This should be covered inside the README of this repository. Everything
else will be part of the resulting documentation PDF file.
|
|
This license should cover the documentation of soundbox because software
licenses like the AGPL or hardware licenses like OHL are not well
suited.
|
