X-Git-Url: http://git.tuebingen.mpg.de/?a=blobdiff_plain;f=web%2Fmanual.md;h=b5329ea07f3d8a2f9553f384c9129c4ad1a262e3;hb=HEAD;hp=fb3a05f758ea6c3eed4e5d5cec81a4f586d66500;hpb=177ea8ea46918a925c0d2d8a07e7fbe9f478a40c;p=paraslash.git
diff --git a/web/manual.md b/web/manual.md
index fb3a05f7..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,
@@ -230,9 +230,9 @@ compatible with arbitrary HTTP streaming sources (e.g. icecast).
In addition to the three network streaming modes, para_recv can also
operate in local (afh) mode. In this mode it writes the content of
an audio file on the local file system in complete chunks to stdout,
-optionally 'just in time'. This allows to cut an audio file without
-first decoding it, and it enables third-party software which is unaware
-of the particular audio format to send complete frames in real time.
+optionally 'just in time'. This allows cutting audio files without
+decoding, and it enables third-party software which is unaware of
+the particular audio format to send complete frames in real time.
para_filter
@@ -287,13 +287,13 @@ 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 \
- libfaad-dev libspeex-dev libFLAC-dev libsamplerate-dev realpath \
+ libfaad-dev libspeex-dev libflac-dev libsamplerate-dev \
libasound2-dev libao-dev libreadline-dev libncurses-dev \
libopus-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.
@@ -358,7 +358,7 @@ recognized. The mp3 tagger also needs this library for modifying
you need libogg, libvorbis, libvorbisfile. The corresponding Debian
packages are called `libogg-dev` and `libvorbis-dev`.
-- [libfaad and mp4ff](http://www.audiocoding.com/). For aac files
+- [libfaad and mp4ff](https://sourceforge.net/projects/faac/). For aac files
(m4a) you need libfaad and libmp4ff (package: `libfaad-dev`). Note
that for some distributions, e.g. Ubuntu, mp4ff is not part of the
libfaad package. Install the faad library from sources (available
@@ -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.
@@ -446,7 +446,7 @@ following commands:
Next, change to the "bar" account on client_host and generate the
key pair with the commands
- ssh-keygen -q -t rsa -b 2048 -N '' -f $key
+ ssh-keygen -q -t rsa -b 2048 -N '' -m RFC4716
This generates the two files id_rsa and id_rsa.pub in ~/.ssh. Note
that para_server won't accept keys shorter than 2048 bits. Moreover,
@@ -488,10 +488,10 @@ An empty database is created with
para_client init
This initializes a couple of empty tables under
-~/.paraslash/afs_database-0.4. You normally don't need to look at these
+~/.paraslash/afs_database-0.7. You normally don't need to look at these
tables, but it's good to know that you can start from scratch with
- rm -rf ~/.paraslash/afs_database-0.4
+ rm -rf ~/.paraslash/afs_database-0.7
in case something went wrong.
@@ -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
-----------
@@ -613,10 +613,11 @@ while the second part is the session key.
- para_client receives the encrypted buffer and decrypts it with the
user's private key, thereby obtaining the challenge buffer and the
-session key. It sends the SHA1 hash value of the challenge back to
-para_server and stores the session key for further use.
+session key. It hashes the challenge buffer with a crytographic hash
+function, sends the hash value back to para_server and stores the
+session key for further use.
-- para_server also computes the SHA1 hash of the challenge and compares
+- para_server also computes the hash value of the challenge and compares
it against what was sent back by the client.
- If the two hashes do not match, the authentication has failed and
@@ -630,12 +631,12 @@ the session key known to both peers.
paraslash relies on the quality of the pseudo-random bytes provided
by the crypto library (openssl or libgcrypt), on the security of
the implementation of the RSA and AES crypto routines and on the
-infeasibility to invert the SHA1 function.
+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
------------------
@@ -707,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
@@ -773,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.
@@ -804,10 +805,11 @@ This is the most important and usually also the largest table of the
AFS database. It contains the information needed to stream each audio
file. In particular the following data is stored for each audio file.
-- SHA1 hash value of the audio file contents. This is computed once
-when the file is added to the database. Whenever AFS selects this
-audio file for streaming the hash value is recomputed and checked
-against the value stored in the database to detect content changes.
+- The cryptographic hash value of the audio file contents. This is
+computed once when the file is added to the database. Whenever AFS
+selects this audio file for streaming the hash value is recomputed
+and checked against the value stored in the database to detect
+content changes.
- The time when this audio file was last played.
@@ -1023,6 +1025,7 @@ Keyword | Type | Semantic value
`bitrate` | integer | The average bitrate
`frequency` | integer | The output sample rate
`channels` | integer | The number of channels
+`duration` | integer | The number of milliseconds
`is_set("foo")` | boolean | True if attribute "foo" is set.
[\*] For most audio formats, the year tag is stored as a string. It
@@ -1146,7 +1149,7 @@ if the "-a" switch is given:
File renames and content changes
--------------------------------
-Since the audio file selector knows the SHA1 of each audio file that
+Since the audio file selector knows the hash of each audio file that
has been added to the afs database, it recognizes if the content of
a file has changed, e.g. because an ID3 tag was added or modified.
Also, if a file has been renamed or moved to a different location,
@@ -1163,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
@@ -1175,14 +1178,14 @@ may refuse to start again because of "dirty osl tables". In this
case you'll have to run the oslfsck program of libosl to fix your
database:
- oslfsck -fd ~/.paraslash/afs_database-0.4
+ oslfsck -fd ~/.paraslash/afs_database-0.7
However, make sure para_server isn't running before executing oslfsck.
If you don't mind to recreate your database you can start
from scratch by removing the entire database directory, i.e.
- rm -rf ~/.paraslash/afs_database-0.4
+ rm -rf ~/.paraslash/afs_database-0.7
Be aware that this removes all attribute definitions, all playlists
and all mood definitions and requires to re-initialize the tables.
@@ -1346,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.
@@ -1371,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
@@ -1439,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.
@@ -1510,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
-------------------------------------------
@@ -1541,27 +1544,6 @@ currently running server process.
para_client si
-The sender command of para_server prints information about senders,
-like the various access control lists, and it allows to (de-)activate
-senders and to change the access permissions at runtime.
-
--> List all senders
-
- para_client sender
-
--> Obtain general help for the sender command:
-
- para_client help sender
-
--> Get help for a specific sender (contains further examples):
-
- s=http # or dccp or udp
- para_client sender $s help
-
--> Show status of the http sender
-
- para_client sender http status
-
By default para_server activates both the HTTP and th DCCP sender on
startup. This can be changed via command line options or para_server's
config file.
@@ -1570,13 +1552,6 @@ config file.
para_server -h
-All senders share the "on" and "off" commands, so senders may be
-activated and deactivated independently of each other.
-
--> Switch off the http sender:
-
- para_client sender http off
-
-> Receive a DCCP stream using CCID2 and write the output into a file:
host=foo.org; ccid=2; filename=bar
@@ -1587,20 +1562,11 @@ receiver has its own set of command line options and its own command
line parser, so arguments for the dccp receiver must be protected
from being interpreted by para_recv.
--> Start UDP multicast, using the default multicast address:
-
- para_client sender udp add 224.0.1.38
-
-> Receive FEC-encoded multicast stream and write the output into a file:
filename=foo
para_recv -r udp > $filename
--> Add an UDP unicast for a client to the target list of the UDP sender:
-
- t=client.foo.org
- para_client sender udp add $t
-
-> Receive this (FEC-encoded) unicast stream:
filename=foo
@@ -1687,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
@@ -1778,7 +1744,7 @@ These filters are rather simple and do not modify the audio stream at
all. The wav filter is only useful with para_filter and in connection
with a decoder. It asks the decoder for the number of channels and the
sample rate of the stream and adds a Microsoft wave header containing
-this information at the beginning. This allows to write wav files
+this information at the beginning. This allows writing wav files
rather than raw PCM files (which do not contain any information about
the number of channels and the sample rate).
@@ -1792,17 +1758,6 @@ Both filters require almost no additional computing time, even when
operating on uncompressed audio streams, since data buffers are simply
"pushed down" rather than copied.
-Examples
---------
-
--> Decode an mp3 file to wav format:
-
- para_filter -f mp3dec -f wav < file.mp3 > file.wav
-
--> Amplify a raw audio file by a factor of 1.5:
-
- para_filter -f amp --amp 32 < foo.raw > bar.raw
-
======
Output
======
@@ -1852,8 +1807,8 @@ emulation for backwards compatibility. This API is rather simple but
also limited. For example only one application can open the device
at any time. The OSS writer is activated by default on BSD Systems.
-- *FILE*. The file writer allows to capture the audio stream and
-write the PCM data to a file on the file system rather than playing
+- *FILE*. The file writer allows capturing the audio stream and
+writing the PCM data to a file on the file system rather than playing
it through a sound device. It is supported on all platforms and is
always compiled in.
@@ -1929,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:
@@ -1998,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.
@@ -2012,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).
@@ -2122,11 +2077,11 @@ here are the most important points.
- Don't leave whitespace at the end of lines.
- The limit on the length of lines is 80 columns.
- Use K&R style for placing braces and spaces:
-
+
if (x is true) {
we do y
}
-
+
- Use a space after (most) keywords.
- Do not add spaces around (inside) parenthesized expressions.
- Use one space around (on each side of) most binary and ternary operators.
@@ -2339,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