cd osl && make && sudo make install && sudo ldconfig
sudo apt-get install autoconf libssl-dev help2man gengetopt \
libmad0-dev libid3tag0-dev libasound2-dev libvorbis-dev \
- libfaad-dev libspeex-dev libFLAC-dev libsamplerate-dev \
+ libfaad-dev libspeex-dev libFLAC-dev libsamplerate-dev realpath \
libasound2-dev libao-dev libreadline-dev libncurses-dev \
libopus-dev
- XREFERENCE(http://www.underbit.com/products/mad/,
libid3tag). For version-2 ID3 tag support, you'll need
the libid3tag development package libid3tag0-dev. Without
- libid3tag, only version one tags are recognized.
+ libid3tag, only version-1 tags are recognized. The mp3 tagger
+ also needs this library for modifying (id3v1 and id3v2) tags.
- XREFERENCE(http://www.xiph.org/downloads/, ogg vorbis).
For ogg vorbis streams you'll need libogg, libvorbis,
*Step 2*: Start para_server
-Before starting the server make sure you have write permissions to
-the directory /var/paraslash that has been created during installation:
-
- sudo chown $LOGNAME /var/paraslash
-
-Alternatively, use the --afs-socket Option to specify a different
-location for the AFS command socket.
-
For this first try, we'll use the info loglevel to make the output
of para_server more verbose.
*Step 4*: Configure para_audiod
-para_audiod needs to create a "well-known" socket for the clients to
-connect to. The default path for this socket is
-
- /var/paraslash/audiod_socket.$HOSTNAME
-
-In order to make this directory writable for para_audiod, execute
-as bar@client_host
-
- sudo chown $LOGNAME /var/paraslash
-
-
-We will also have to tell para_audiod that it should receive the
-audio stream from server_host via http:
+We will have to tell para_audiod that it should receive the audio
+stream from server_host via http:
para_audiod -l info -r '.:http -i server_host'
*Troubleshooting*
-It did not work? To find out why, try to receive, decode and play the
-stream manually using para_recv, para_filter and para_write as follows.
+If you receive a socket related error on server or audiod startup,
+make sure you have write permissions to the /var/paraslash directory:
+
+ sudo chown $LOGNAME /var/paraslash
+Alternatively, use the --afs-socket (para_server) or --socket
+(para_audiod) option to specify a different socket pathname.
+
+To identify streaming problems try to receive, decode and play the
+stream manually using para_recv, para_filter and para_write as follows.
For simplicity we assume that you're running Linux/ALSA and that only
MP3 files have been added to the database.
The command
- para_client -- ls -lv
+ para_client -- ls -l=v
gives you a verbose listing of your audio files also showing which
attributes are set.
frequency ~ <num>
channels ~ <num>
num_played ~ <num>
+ image_id ~ <num>
+ lyrics_id ~ <num>
Takes a comparator ~ of the set {<, =, <=, >, >=, !=} and a number
<num>. Matches an audio file iff the condition <val> ~ <num> is
satisfied where val is the corresponding value of the audio file
-(value of the year tag, bitrate in kbit/s, frequency in Hz, channel
-count, play count).
+(value of the year tag, bitrate in kbit/s, etc.).
The year tag is special as its value is undefined if the audio file
has no year tag or the content of the year tag is not a number. Such
from the client to the server.
There is no knowledge about the server commands built into para_client,
-so it does not know about addblob commands. Instead, it inspects the
-first data package sent by the server for a magic string. If this
-string was found, it sends STDIN to the server, otherwise it dumps
-data from the server to STDOUT.
+so it does not know about addblob commands. Instead, the server sends
+a special "awaiting data" packet for these commands. If the client
+receives this packet, it sends STDIN to the server, otherwise it
+dumps data from the server to STDOUT.
Streaming protocols
~~~~~~~~~~~~~~~~~~~
operates on undecoded PCM data (visualizers, equalizers etc.). Such
filters are called _decoders_ in general, and xxxdec is the name of
the paraslash decoder for the audio format xxx. For example, the mp3
-decoder filter is called mp3dec.
+decoder is called mp3dec.
Note that the output of the decoder is about 10 times larger than
its input. This means that filters that operate on the decoded audio
Paraslash relies on external libraries for most decoders, so these
libraries must be installed for the decoder to be included in the
-para_filter and para_audiod executables. The oggdec filter depends
-on the libogg and libvorbis libraries for example.
+executables. For example, the mp3dec filter depends on the mad library.
Forward error correction
~~~~~~~~~~~~~~~~~~~~~~~~
~~~~~~~
Doxygen is a documentation system for various programming
-languages. The paraslash project uses Doxygen for generating the API
-reference on the web pages, but good source code documentation is
-also beneficial to people trying to understand the code structure
-and the interactions between the various source files.
+languages. The API reference on the paraslash web page is generated
+by doxygen.
It is more illustrative to look at the source code for examples than
-to describe the conventions for documenting the source in this manual,
-so we only describe which parts of the code need doxygen comments,
-but leave out details on documentation conventions.
+to describe the conventions in this manual, so we only describe which
+parts of the code need doxygen comments, but leave out details on
+documentation conventions.
As a rule, only the public part of the C source is documented with
Doxygen. This includes structures, defines and enumerations in header
files as well as public (non-static) C functions. These should be
-documented completely. For example each parameter and the return
-value of a public function should get a descriptive comment.
+documented completely. For example, each parameter and the return
+value of a public function should get a descriptive doxygen comment.
No doxygen comments are necessary for static functions and for
structures and enumerations in C files (which are used only within
connectionless transport, which is the reason that it is currently
only available via UDP.
+Abstract socket namespace
+~~~~~~~~~~~~~~~~~~~~~~~~~
+UNIX domain sockets are a traditional way to communicate between
+processes on the same machine. They are always reliable (see above)
+and don't reorder datagrams. Unlike TCP and UDP, UNIX domain sockets
+support passing open file descriptors or process credentials to
+other processes.
+
+The usual way to set up a UNIX domain socket (as obtained from
+socket(2)) for listening is to first bind the socket to a file system
+pathname and then call listen(2), then accept(2). Such sockets are
+called _pathname sockets_ because bind(2) creates a special socket
+file at the specified path. Pathname sockets allow unrelated processes
+to communicate with the listening process by binding to the same path
+and calling connect(2).
+
+There are two problems with pathname sockets:
+
+ * The listing process must be able to (safely) create the
+ socket special in a directory which is also accessible to
+ the connecting process.
+
+ * After an unclean shutdown of the listening process, a stale
+ socket special may reside on the file system.
+
+The abstract socket namespace is a non-portable Linux feature which
+avoids these problems. Abstract sockets are still bound to a name,
+but the name has no connection with file system pathnames.
+
License
~~~~~~~
projects / paraslash.git / blobdiff