From: Andre Noll Date: Sat, 29 Apr 2017 19:51:49 +0000 (+0200) Subject: manual: Omit level 3 headers from table of contents. X-Git-Tag: v0.6.1~68^2~1 X-Git-Url: http://git.tue.mpg.de/?a=commitdiff_plain;h=60f4105f29a76b56d2c20b626945c39424cce409;p=paraslash.git manual: Omit level 3 headers from table of contents. The table of contents was rather large because it contained too much detail. This commit converts all level 3 headings to inline html which has no visible effect except that the headings no longer appear in the table of contents. --- diff --git a/web/manual.md b/web/manual.md index c8f1a9d8..0b9b0fdd 100644 --- a/web/manual.md +++ b/web/manual.md @@ -80,7 +80,7 @@ file. This information is pretty-printed in a curses window. The paraslash executables ------------------------- -### para_server ### +

para_server

para_server streams binary audio data (MP3, ...) over local and/or remote networks. It listens on a TCP port and accepts commands such @@ -148,7 +148,7 @@ The three senders of para_server correspond to network streaming protocols based on HTTP, DCCP, or UDP. This is explained in the section on [networking](#Networking). -### para_client ### +

para_client

The client program to connect to para_server. paraslash commands are sent to para_server and the response is dumped to STDOUT. This @@ -163,7 +163,7 @@ If para_client is started without non-option arguments, an interactive session (shell) is started. Command history and command completion are supported through libreadline. -### para_audiod ### +

para_audiod

The purpose of para_audiod is to download, decode and play an audio stream received from para_server. A typical setup looks as follows. @@ -216,14 +216,14 @@ para_audioc to obtain status information about para_audiod and the current audio file. Access to the local socket may be restricted by means of Unix socket credentials. -### para_audioc ### +

para_audioc

The client program which talks to para_audiod. Used to control para_audiod, to receive status info, or to grab the stream at any point of the decoding process. Like para_client, para_audioc supports interactive sessions on systems with libreadline. -### para_recv ### +

para_recv

A command line HTTP/DCCP/UDP stream grabber. The http mode is compatible with arbitrary HTTP streaming sources (e.g. icecast). @@ -234,7 +234,7 @@ 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. -### para_filter ### +

para_filter

A filter program that reads from STDIN and writes to STDOUT. Like para_recv, this is an atomic building block which can be used to @@ -243,30 +243,30 @@ different functionalities in one tool: decoders for multiple audio formats and a number of processing filters, among these a normalizer for audio volume. -### para_afh ### +

para_afh

A small stand-alone program that prints tech info about the given audio file to STDOUT. It can be instructed to print a "chunk table", an array of offsets within the audio file. -### para_write ### +

para_write

A modular audio stream writer. It supports a simple file writer output plug-in and optional WAV/raw players for ALSA (Linux) and OSS. para_write can also be used as a stand-alone WAV or raw audio player. -### para_play ### +

para_play

A command line audio player. -### para_gui ### +

para_gui

Curses-based gui that presents status information obtained in a curses window. Appearance can be customized via themes. para_gui provides key-bindings for the most common server commands and new key-bindings can be added easily. -### para_mixer ### +

para_mixer

An alarm clock and volume-fader for OSS and ALSA. @@ -282,7 +282,7 @@ source code and the steps that have to be performed in order to Requirements ------------ -### For the impatient ### +

For the impatient

git clone git://git.tuebingen.mpg.de/lopsub cd lopsub && make && sudo make install @@ -294,7 +294,7 @@ Requirements libasound2-dev libao-dev libreadline-dev libncurses-dev \ libopus-dev -### Detailed description ### +

Detailed description

In any case you will need @@ -413,7 +413,7 @@ to install executables under /usr/local/bin and the man pages under Configuration ------------- -### Create a paraslash user ### +

Create a paraslash user

In order to control para_server at runtime you must create a paraslash user. As authentication is based on the RSA crypto system you'll have @@ -457,7 +457,7 @@ Finally, tell para_client to connect to server_host: echo 'hostname server_host' > $conf -### Start para_server ### +

Start para_server

For this first try, we'll use the info loglevel to make the output of para_server more verbose. @@ -473,7 +473,7 @@ commands. Open a new shell as bar@client_host and try to retrieve the list of available commands and some server info. Don't proceed if this doesn't work. -### Create and populate the database ### +

Create and populate the database

An empty database is created with @@ -501,7 +501,7 @@ You may print the list of all known audio files with para_client ls -### Configure para_audiod ### +

Configure para_audiod

We will have to tell para_audiod that it should receive the audio stream from server_host via http: @@ -790,7 +790,7 @@ current playlist or mood. All tables are described in more detail below. -### The audio file table ### +

The audio file table

This is the most important and usually also the largest table of the AFS database. It contains the information needed to stream each audio @@ -839,7 +839,7 @@ directory. In the latter case, the directory is traversed recursively and all files which are recognized as valid audio files are added to the database. -### The attribute table ### +

The attribute table

The attribute table contains two columns, _name_ and _bitnum_. An attribute is simply a name for a certain bit number in the attribute @@ -899,7 +899,7 @@ Read the output of for more information and a complete list of command line options to these commands. -### Blob tables ### +

Blob tables

The image, lyrics, moods and playlists tables are all blob tables. Blob tables consist of three columns each: The identifier which is @@ -926,7 +926,7 @@ Note that the images and lyrics are not interpreted at all, and also the playlist and the mood blobs are only investigated when the mood or playlist is activated with the select command. -### The score table ### +

The score table

The score table describes those audio files which are admissible for the current mood or playlist (see below). The table has two columns: @@ -952,7 +952,7 @@ terms of attributes and other type of information available in the audio file table. As an example, a mood can define a filename pattern, which is then matched against the names of audio files in the table. -### Playlists ### +

Playlists

Playlists are accommodated in the playlist table of the afs database, using the aforementioned blob format for tables. A new playlist is @@ -971,7 +971,7 @@ in descending order so that files will be selected in order. If a file could not be opened for streaming, its entry is removed from the score table (but not from the playlist). -### Moods ### +

Moods

A mood consists of a unique name and its *mood definition*, which is a set of *mood lines* containing expressions in terms of attributes @@ -1046,7 +1046,7 @@ special treatment: -### List of mood_methods ### +

List of mood_methods

no_attributes_set @@ -1092,7 +1092,7 @@ if the year tag is a two-digit number. In this case either 1900 or greater than 2000 plus the current year. -### Mood usage ### +

Mood usage

To create a new mood called "my_mood", write its definition into some temporary file, say "tmpfile", and add it to the mood table @@ -1120,7 +1120,7 @@ if the "-a" switch is given: para ls -a -### Example mood definition ### +

Example mood definition

Suppose you have defined attributes "punk" and "rock" and want to define a mood containing only Punk-Rock songs. That is, an audio file should be @@ -1209,7 +1209,7 @@ Audio formats The following audio formats are supported by paraslash: -### MP3 ### +

MP3

Mp3, MPEG-1 Audio Layer 3, is a common audio format for audio storage, designed as part of its MPEG-1 standard. An MP3 file is made up of @@ -1219,7 +1219,7 @@ of channels. For a typical CD-audio file (sample rate of 44.1 kHz stereo), encoded with a bit rate of 128 kbit, an MP3 frame is about 400 bytes large. -### OGG/Vorbis ### +

OGG/Vorbis

OGG is a standardized audio container format, while Vorbis is an open source codec for lossy audio compression. Since Vorbis is most @@ -1229,7 +1229,7 @@ chunks called OGG pages. A typical OGG page is about 4KB large. The Vorbis codec creates variable-bitrate (VBR) data, where the bitrate may vary considerably. -### OGG/Speex ### +

OGG/Speex

Speex is an open-source speech codec that is based on CELP (Code Excited Linear Prediction) coding. It is designed for voice @@ -1239,7 +1239,7 @@ supported. As for Vorbis audio, Speex bit-streams are often stored in OGG files. As of 2012 this codec is considered obsolete since the Oppus codec, described below, surpasses its performance in all areas. -### OGG/Opus ### +

OGG/Opus

Opus is a lossy audio compression format standardized through RFC 6716 in 2012. It combines the speech-oriented SILK codec and the @@ -1248,7 +1248,7 @@ OGG/Vorbis and OGG/Speex, Opus data is usually encapsulated in OGG containers. All known software patents which cover Opus are licensed under royalty-free terms. -### AAC ### +

AAC

Advanced Audio Coding (AAC) is a standardized, lossy compression and encoding scheme for digital audio which is the default audio @@ -1256,7 +1256,7 @@ format for Apple's iPhone, iPod, iTunes. Usually MPEG-4 is used as the container format and audio files encoded with AAC have the .m4a extension. A typical AAC frame is about 700 bytes large. -### WMA ### +

WMA

Windows Media Audio (WMA) is an audio data compression technology developed by Microsoft. A WMA file is usually encapsulated in the @@ -1265,7 +1265,7 @@ how meta data about the file is to be encoded. The bit stream of WMA is composed of superframes, each containing one or more frames of 2048 samples. For 16 bit stereo a WMA superframe is about 8K large. -### FLAC ### +

FLAC

The Free Lossless Audio Codec (FLAC) compresses audio without quality loss. It gives better compression ratios than a general purpose @@ -1730,7 +1730,7 @@ they are usually placed directly after the decoding filter. Each sample is multiplied with a scaling factor (>= 1) which makes amp and compress quite expensive in terms of computing power. -### amp ### +

amp

The amp filter amplifies the audio stream by a fixed scaling factor that must be known in advance. For para_audiod this factor is derived @@ -1757,7 +1757,7 @@ To store V in the audio file table, the command is used. The reader is encouraged to write a script that performs these computations :) -### compress ### +

compress

Unlike the amplification filter, the compress filter adjusts the volume of the audio stream dynamically without prior knowledge about the peak @@ -2172,14 +2172,14 @@ Appendix Network protocols ----------------- -### IP ### +

IP

The _Internet Protocol_ is the primary networking protocol used for the Internet. All protocols described below use IP as the underlying layer. Both the prevalent IPv4 and the next-generation IPv6 variant are being deployed actively worldwide. -### Connection-oriented and connectionless protocols ### +

Connection-oriented and connectionless protocols

Connectionless protocols differ from connection-oriented ones in that state associated with the sending/receiving endpoints is treated @@ -2195,7 +2195,7 @@ up-to-date internal state of the connection also in general means that the sending endpoints perform congestion control, adapting to qualitative changes of the connection medium. -### Reliability ### +

Reliability

In IP networking, packets can be lost, duplicated, or delivered out of order, and different network protocols handle these @@ -2207,7 +2207,7 @@ out-of-order. Retransmission is used to guarantee loss-free delivery. Unreliable protocols, in contrast, do not guarantee ordering or data integrity. -### Classification ### +

Classification

With these definitions the protocols which are used by paraslash for steaming audio data may be classified as follows. @@ -2218,7 +2218,7 @@ steaming audio data may be classified as follows. Below we give a short descriptions of these protocols. -### TCP ### +

TCP

The _Transmission Control Protocol_ provides reliable, ordered delivery of a stream and a classic window-based congestion control. In contrast @@ -2229,7 +2229,7 @@ extensively by many application layers. Besides HTTP (the Hypertext Transfer Protocol), also FTP (the File Transfer protocol), SMTP (Simple Mail Transfer Protocol), SSH (Secure Shell) all sit on top of TCP. -### UDP ### +

UDP

The _User Datagram Protocol_ is the simplest transport-layer protocol, built as a thin layer directly on top of IP. For this reason, it offers @@ -2240,7 +2240,7 @@ means that there is no protection against packet loss or network congestion. Error checking and correction (if at all) are performed in the application. -### DCCP ### +

DCCP

The _Datagram Congestion Control Protocol_ combines the connection-oriented state maintenance known from TCP with the @@ -2257,7 +2257,7 @@ the choice of congestion control: classic, window-based congestion control known from TCP is available as CCID-2, rate-based, "smooth" congestion control is offered as CCID-3. -### HTTP ### +

HTTP

The _Hypertext Transfer Protocol_ is an application layer protocol on top of TCP. It is spoken by web servers and is most often used @@ -2267,7 +2267,7 @@ delivery of web pages only. Being a simple request/response based protocol, the semantics of the protocol also allow the delivery of multimedia content, such as audio over http. -### Multicast ### +

Multicast

IP multicast is not really a protocol but a technique for one-to-many communication over an IP network. The challenge is to deliver