X-Git-Url: http://git.tuebingen.mpg.de/?a=blobdiff_plain;f=web%2Fmanual.md;h=b5329ea07f3d8a2f9553f384c9129c4ad1a262e3;hb=HEAD;hp=78834a4d48be70f178dba5ffed88f5db8761745c;hpb=5d72d5880a6bd319a8ce2bf7dd2e4921938c77c2;p=paraslash.git diff --git a/web/manual.md b/web/manual.md index 78834a4d..0db1e22c 100644 --- a/web/manual.md +++ b/web/manual.md @@ -14,7 +14,7 @@ Introduction In this chapter we give an [overview](#Overview) of the interactions of the programs contained in the paraslash package, followed by -[brief descriptions](#The.paraslash.executables) of all executables. +[brief descriptions](#The-paraslash-executables) of all executables. Overview -------- @@ -135,7 +135,7 @@ fine-grained selection based on various properties of the audio file, including information found in (ID3) tags. Simple playlists are also supported. It is possible to store images (album covers) and lyrics in the database and associate these to the corresponding audio files. -The section on the [audio file selector](#The.audio.file.selector) +The section on the [audio file selector](#The-audio-file-selector) discusses this topic in more detail. Another component of para_server is the virtual streaming system, @@ -287,9 +287,9 @@ Requirements ------------

For the impatient

- git clone git://git.tuebingen.mpg.de/lopsub + git clone https://git.tuebingen.mpg.de/lopsub cd lopsub && make && sudo make install - git clone git://git.tuebingen.mpg.de/osl + git clone https://git.tuebingen.mpg.de/osl cd osl && make && sudo make install && sudo ldconfig sudo apt-get install autoconf libssl-dev m4 \ libmad0-dev libid3tag0-dev libasound2-dev libvorbis-dev \ @@ -306,11 +306,11 @@ option parser for subcommands generates the command line and config file parsers for all paraslash executables. Clone the source code repository with - git clone git://git.tuebingen.mpg.de/lopsub + git clone https://git.tuebingen.mpg.de/lopsub - [gcc](ftp://ftp.gnu.org/pub/gnu/gcc) or -[clang](http://clang.llvm.org). All gcc versions >= 4.2 are currently -supported. Clang version 1.1 or newer should work as well. +[clang](http://clang.llvm.org). All gcc versions >= 5.4 are currently +supported. Moderately recent versions of clang should work as well. - [gnu make](ftp://ftp.gnu.org/pub/gnu/make) is also shipped with the disto. On BSD systems the gnu make executable is often called gmake. @@ -324,11 +324,11 @@ from templates by the m4 macro processor. Optional: -- [libosl](http://people.tuebingen.mpg.de/maan/osl/). The _object +- [libosl](https://people.tuebingen.mpg.de/maan/osl/). The _object storage layer_ library is used by para_server. To clone the source code repository, execute - git clone git://git.tuebingen.mpg.de/osl + git clone https://git.tuebingen.mpg.de/osl - [openssl](https://www.openssl.org/) or [libgcrypt](ftp://ftp.gnupg.org/gcrypt/libgcrypt/). At least one @@ -339,7 +339,7 @@ to install the development package (`libssl-dev` or `libgcrypt-dev` on debian systems) as well. - [flex](https://github.com/westes/flex) and -[bison](https://www.gnu.org/software/bison) are needed to build the +[bison](https://www.gnu.org/software/bison/) are needed to build the mood parser of para_server. The build system will skip para_server if these tools are not installed. @@ -385,7 +385,7 @@ the ao writer (ESD, PulseAudio,...). Debian package: `libao-dev`. para_gui. Debian package: `libncurses-dev`. - [GNU -Readline](http://cnswww.cns.cwru.edu/php/chet/readline/rltop.html). If +Readline](https://www.gnu.org/software/readline/). If this library (`libreadline-dev`) is installed, para_client, para_audioc and para_play support interactive sessions. @@ -523,7 +523,7 @@ starts streaming. To activate streaming, execute Since no playlist has been specified yet, the "dummy" mode which selects all known audio files is activated automatically. See the -section on the [audio file selector](#The.audio.file.selector) for how +section on the [audio file selector](#The-audio-file-selector) for how to use playlists and moods to specify which files should be streamed in which order. @@ -555,12 +555,12 @@ authentication method. Authenticated connections are encrypted using the AES stream cipher in integer counter mode. In this chapter we briefly describe RSA and AES, and sketch the -[authentication handshake](#Client-server.authentication) +[authentication handshake](#Client-2d-server-authentication) between para_client and para_server. User management is discussed -in the section on [the user_list file](#The.user_list.file). +in the section on [the user_list file](#The-user_list-file). These sections are all about communication between the client and the server. Connecting para_audiod is a different matter and is described -in a [separate section](#Connecting.para_audiod). +in a [separate section](#Connecting-para_audiod). RSA and AES ----------- @@ -635,8 +635,8 @@ infeasibility to invert the hash function. Neither para_server or para_client create RSA keys on their own. This has to be done once for each user as sketched in -[Quick start](#Quick.start) and discussed in more detail -[below](#The.user_list.file). +[Quick start](#Quick-start) and discussed in more detail +[below](#The-user_list-file). The user_list file ------------------ @@ -708,13 +708,13 @@ maintains tables containing images (e.g. album cover art) and lyrics that can be associated with one or more audio files. In this chapter we sketch the setup of the [AFS -process](#The.AFS.process) during server startup and proceed with the -description of the [layout](#Database.layout) of the various database -tables. The section on [playlists and moods](#Playlists.and.moods) +process](#The-AFS-process) during server startup and proceed with the +description of the [layout](#Database-layout) of the various database +tables. The section on [playlists and moods](#Playlists-and-moods) explains these two audio file selection mechanisms in detail and contains practical examples. The way [file renames and content -changes](#File.renames.and.content.changes) are detected is discussed -briefly before the [Troubleshooting](#Troubleshooting) section +changes](#File-renames-and-content-changes) are detected is discussed +briefly before the [Troubleshooting](#Common-problems) section concludes the chapter. The AFS process @@ -774,7 +774,7 @@ entry with metadata obtained from the audio format handler is added to the database. Note that AFS employs -[libosl](http://people.tuebingen.mpg.de/maan/osl/), the object +[libosl](https://people.tuebingen.mpg.de/maan/osl/), the object storage layer library, as the database backend. This library offers functionality similar to a relational database, but is much more lightweight than a full featured database management system. @@ -1166,7 +1166,7 @@ data remains as before. It is possible to change the behaviour of the add command by using the "-l" (lazy add) or the "-f" (force add) option. -Troubleshooting +Common problems --------------- Use the debug loglevel (-l debug) to show debugging info. All paraslash @@ -1349,12 +1349,12 @@ used. For these data connections, a variety of transports (UDP, DCCP, HTTP) can be chosen. The chapter starts with the [control -service](#The.paraslash.control.service), followed by a section -on the various [streaming protocols](#Streaming.protocols) +service](#The-paraslash-control-service), followed by a section +on the various [streaming protocols](#Streaming-protocols) in which the data connections are described. The way audio file headers are embedded into the stream is discussed -[briefly](#Streams.with.headers.and.headerless.streams) before the -[example section](#Networking.examples) which illustrates typical +[briefly](#Streams-with-headers-and-headerless-streams) before the +[example section](#Networking-examples) which illustrates typical commands for real-life scenarios. Both IPv4 and IPv6 are supported. @@ -1374,7 +1374,7 @@ is unaffected if the child dies or goes crazy for whatever reason. In fact, the child process can not change address space of server process. The section on [client-server -authentication](#Client-server.authentication) above described the +authentication](#Client-2d-server-authentication) above described the early connection establishment from the crypto point of view. Here it is described what happens after the connection (including crypto setup) has been established. There are four processes involved during @@ -1442,7 +1442,7 @@ only for Linux. - UDP. Recommended for multicast LAN streaming. -See the Appendix on [network protocols](#Network.protocols) +See the Appendix on [network protocols](#Network-protocols) for brief descriptions of the various protocols relevant for network audio streaming with paraslash. @@ -1513,7 +1513,7 @@ be configured via the FEC parameters which are dictated by server and may also be configured through the "sender" command. The FEC parameters are encoded in the header of each network packet, so no configuration is necessary on the receiver side. See the section on -[FEC](#Forward.error.correction) below. +[FEC](#Forward-error-correction) below. Streams with headers and headerless streams ------------------------------------------- @@ -1653,7 +1653,7 @@ executables. For example, the mp3dec filter depends on the mad library. Forward error correction ------------------------ -As already mentioned [earlier](#Streaming.protocols), paraslash +As already mentioned [earlier](#Streaming-protocols), paraslash uses forward error correction (FEC) for the unreliable UDP and DCCP transports. FEC is a technique which was invented already in 1960 by Reed and Solomon and which is widely used for the parity @@ -1884,8 +1884,8 @@ shown by this theme. See gui_theme.c for examples. The "." and "," keys are used to switch between themes. -Examples --------- +Gui examples +------------ -> Show server info: @@ -1953,8 +1953,8 @@ from tar balls) and for contributing non-trivial changes to the paraslash project, some additional tools should be installed on a developer machine. -- [git](http://git.or.cz/). As described in more detail -[below](#Git.branches), the git source code management tool is used for +- [git](https://git-scm.com/). As described in more detail +[below](#Git-branches), the git source code management tool is used for paraslash development. It is necessary for cloning the git repository and for getting updates. @@ -1967,7 +1967,7 @@ HTML version of this manual and some of the paraslash web pages are written in the Markdown markup language and are translated into html with the converter of the *Discount* package. -- [doxygen](http://www.stack.nl/~dimitri/doxygen/). The documentation +- [doxygen](https://www.doxygen.nl/). The documentation of paraslash's C sources uses the doxygen documentation system. The conventions for documenting the source code is described in the [Doxygen section](#Doxygen). @@ -2294,54 +2294,42 @@ and contributed significant improvements. References ========== -Articles --------- -- [Polynomial Codes over Certain Finite -Fields](http://kom.aau.dk/~heb/kurser/NOTER/KOFA01.PDF) by Reed, Irving -S.; Solomon, Gustave (1960), Journal of the Society for Industrial -and Applied Mathematics (SIAM) 8 (2): 300-304, doi:10.1137/0108018) - RFCs ---- -- [RFC 768](http://www.ietf.org/rfc/rfc768.txt) (1980): User Datagram +- [RFC 768](https://www.ietf.org/rfc/rfc768.txt) (1980): User Datagram Protocol -- [RFC 791](http://www.ietf.org/rfc/rfc791.txt) (1981): Internet +- [RFC 791](https://www.ietf.org/rfc/rfc791.txt) (1981): Internet Protocol -- [RFC 2437](http://www.ietf.org/rfc/rfc2437.txt) (1998): RSA +- [RFC 2437](https://www.ietf.org/rfc/rfc2437.txt) (1998): RSA Cryptography Specifications -- [RFC 4340](http://www.ietf.org/rfc/rfc4340.txt) (2006): Datagram +- [RFC 4340](https://www.ietf.org/rfc/rfc4340.txt) (2006): Datagram Congestion Control Protocol (DCCP) -- [RFC 4341](http://www.ietf.org/rfc/rfc4341.txt) (2006): Congestion +- [RFC 4341](https://www.ietf.org/rfc/rfc4341.txt) (2006): Congestion Control ID 2: TCP-like Congestion Control -- [RFC 4342](http://www.ietf.org/rfc/rfc4342.txt) (2006): Congestion +- [RFC 4342](https://www.ietf.org/rfc/rfc4342.txt) (2006): Congestion Control ID 3: TCP-Friendly Rate Control (TFRC) -- [RFC 6716](http://www.ietf.org/rfc/rfc6716.txt) (2012): Definition +- [RFC 6716](https://www.ietf.org/rfc/rfc6716.txt) (2012): Definition of the Opus Audio Codec Application web pages --------------------- -- [paraslash](http://people.tuebingen.mpg.de/maan/paraslash/) -- [xmms](https://xmms2.org/wiki/Main_Page) +- [paraslash](https://people.tuebingen.mpg.de/maan/paraslash/) - [mpg123](http://www.mpg123.de/) - [gstreamer](https://gstreamer.freedesktop.org/) -- [icecast](http://www.icecast.org/) -- [Audio Compress](https://beesbuzz.biz/code/audiocompress.php) +- [icecast](https://www.icecast.org/) +- [Audio Compress](https://github.com/fluffy-critter/audiocompress) External documentation ---------------------- -- [The mathematics of -Raid6](https://www.kernel.org/pub/linux/kernel/people/hpa/raid6.pdf) -by H. Peter Anvin - - [Effective Erasure Codes for reliable Computer Communication Protocols](http://info.iet.unipi.it/~luigi/fec_ccr.ps.gz) by Luigi Rizzo