summaryrefslogtreecommitdiff
path: root/doc
AgeCommit message (Collapse)Author
2024-02-02doc: Replace author name by email addressxengineering
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.
2024-02-02doc: Mention license in introduction textxengineering
This is very important information for every reader so it should be part of the first section.
2024-02-02doc: Add license text as appendixxengineering
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.
2024-02-02Switch completely to CERN-OHL-Sxengineering
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.
2024-01-30doc: Restrict lldpd to Unix OS not Linuxxengineering
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
2024-01-30doc: Add section 'Getting soundbox'xengineering
2024-01-30doc: Add version information to PDF title pagexengineering
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.
2024-01-30doc: Reformulate variadic command definitionxengineering
The new format is closer to e.g. 'man 1 printf'.
2024-01-30doc: Move 'setup-alpine' to configuration sectionxengineering
This was never part of an installation but instead of a configuration step.
2024-01-30doc: Add section 'Bill of materials'xengineering
This is the central reference what is required to build soundbox devices.
2024-01-30doc: Rewrite introductionxengineering
The introduction was very limited so far but is important to manage expectations regarding the device.
2024-01-28doc: Add new chapter 'Developer documentation'xengineering
This new chapter should be the one with the highest level of details. The section about versioning is also moved there with this commit.
2024-01-27doc: Use Git-provided commit date for PDFxengineering
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.
2024-01-27doc: Switch protocol, format and codecxengineering
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.
2024-01-21doc: Rework user guide for streamingxengineering
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.
2024-01-20doc: Add user guide for device discoveryxengineering
2024-01-20doc: Add OpenRC service configurationxengineering
This makes sure the audio-receiving software `ffplay` runs all the time.
2024-01-20doc: Split configuration section into subsectionsxengineering
2024-01-20doc: Add lldpd configurationxengineering
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.
2024-01-14doc: Always use MP3 as audio codecxengineering
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
2024-01-14doc: Simplify streaming commandsxengineering
2024-01-14doc: Switch from RTP to Matroska and UDPxengineering
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
2024-01-14doc: Fix duplicated periodxengineering
2024-01-14doc: Switch to multicast for streamingxengineering
This allows to stream to multiple devices at the same time. Nevertheless it still works for a point to point stream.
2024-01-14doc: Explain how to enable default RPi audioxengineering
The soundbox software should be portable to other Raspberry Pis without the HiFiBerry DAC too.
2024-01-14doc: Unify replacable parts of streaming commandxengineering
2024-01-14doc: Use native audio codec for streamingxengineering
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.
2024-01-14doc: Add Alpine Linux config guidexengineering
Configuring the Alpine Linux operating system correctly for soundbox is not trivial. Since it is very important it has to be documented in detail.
2024-01-14doc: Switch to tar-based installationxengineering
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.
2024-01-12doc: Add Alpine Linux installation instructionsxengineering
This is currently the recommended OS installation for soundbox.
2024-01-06doc: Change paragraph distancexengineering
There used to be no extra space between paragraphs which in combination with no indentation was not useful.
2024-01-05doc: Fix missing `-re` flag for ffmpeg streamingxengineering
This flag makes sure the file is streamed in native frame rate and not e.g. way faster. This is the expected behaviour.
2024-01-05doc: Switch from UDP port 1234 to UDP port 5316xengineering
This port should be used in the future as soundbox standard port.
2024-01-05doc: Add example for FFMpeg MP3 streamingxengineering
This allows more testing than only streaming sine waves.
2024-01-05doc: Add section 'Playing audio'xengineering
This documents a basic FFmpeg streaming example so that soundbox devices can be tested.
2024-01-05doc: Write section 'Versioning'xengineering
This section is important to communicate how to interpret version numbers in the context of this device repository.
2024-01-05doc: Build twice with LaTeXxengineering
This is required to build the table of contents and similar parts of the document correctly.
2024-01-05doc: Remove 'soundbox-' prefix from doc PDFxengineering
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.
2024-01-03doc: Add brief description for first chapterxengineering
2024-01-03doc: Switch from LaTeX article to reportxengineering
This document will be quite long. Thus the report document class is more suitable.
2024-01-03doc: Draft structure for PDF documentationxengineering
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.
2024-01-03doc: Add automated PDF generationxengineering
The build system should convert the documentation source files automatically to a single PDF file to make documentation generation trivial.
2024-01-03doc: Add soundbox-documentation.texxengineering
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.
2024-01-03doc: Add folder and CC BY-SA 4.0 licensexengineering
This license should cover the documentation of soundbox because software licenses like the AGPL or hardware licenses like OHL are not well suited.