From 7871f41f2e49978b8c5451516e7a464b0985828b Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Sun, 16 Apr 2006 13:34:09 +0000 Subject: add documentation for the new RTP modules git-svn-id: file:///home/lennart/svn/public/pulseaudio/trunk@731 fefdeb5f-60dc-0310-8127-8f9354f1896f --- doc/FAQ.html.in | 97 ++++++++++++++++++++++++++++++++++++++++++++-- doc/README.html.in | 3 +- doc/modules.html.in | 108 +++++++++++++++++++++++++++++++++++++++++++--------- 3 files changed, 184 insertions(+), 24 deletions(-) diff --git a/doc/FAQ.html.in b/doc/FAQ.html.in index 0e738217..7adc2441 100644 --- a/doc/FAQ.html.in +++ b/doc/FAQ.html.in @@ -67,7 +67,7 @@ realtime, or increase the fragment sizes of the audio drivers. The former will allow Polypaudio to activate SCHED_FIFO high priority scheduling (root rights are dropped - immediately after this) Keep in mind that this is a potential security hole!

+ immediately after this). Keep in mind that this is a potential security hole!

  • The polypaudio executable is installed SUID root by default. Why this? Isn't this a potential security hole?

    @@ -103,7 +103,12 @@ in ~/.polypaudio/.

  • How do I use polypaudio over the network?

    -

    Just set $POLYP_SERVER to the host name of the polypaudio server.

    +

    Just set $POLYP_SERVER to the host name of the polypaudio +server. For authentication you need the same auth cookies on all sides. For +that copy ~./polypaudio-cookie to all clients that shall +be allowed to connect.

    + +

    Alternatively the authorization cookies can be stored in the X11 server.

  • Is polypaudio capable of providing synchronized audio playback over the network for movie players like mplayer?

    @@ -126,7 +131,7 @@ connect to a running polypaudio daemon try using the following commands:

    killall -USR2 polypaudio
 bidilink unix-client:/tmp/polypaudio/cli
    -

    BTW: Someone should package that great tool for Debian!

    +

    BTW: Someone should package this great tool for Debian!

    New: There's now a tool pacmd that automates sending SIGUSR2 to the daemon and running a bidilink like tool for you.

    • @@ -146,7 +151,91 @@ bidilink unix-client:/tmp/polypaudio/cli

  • Why the heck does libpolyp link against libX11?

    -

    The Polypaudio client libraries look for some X11 root window properties for the credentials of the Polypaudio server to access. You may compile Polypaudio without X11 for disabling this.

    • +

    The Polypaudio client libraries look for some X11 root window +properties for the credentials of the Polypaudio server to access. You +may compile Polypaudio without X11 for disabling this feature.

    + +

  • How can I use Polypaudio as an RTP based N:N multicast +conferencing solution for the LAN?

    After loading all the +necessary audio drivers for recording and playback, just load the RTP +reciever and sender modules with default parameters:

    + +
    +load-module module-rtp-send
+load-module module-rtp-recv
+
    + +

    As long as the Polypaudio daemon runs, the microphone data will be +streamed to the network and the data from other hosts is played back +locally. Please note that this may cause quite a lot of traffic. Hence +consider passing rate=8000 format=ulaw channels=1 to the +sender module to save bandwith while still maintaining good quality +for speech transmission.

    • + +

  • What is this RTP/SDP/SAP thing all about?

    + +

    RTP is the Realtime Transfer Protocol. It is a well-known +protocol for transferring audio and video data over IP. SDP is the Session +Description Protocol and can be used to describe RTP sessions. SAP +is the Session Announcement Protocol and can be used to +announce RTP sessions that are described with SDP. (Modern SIP based VoIP phones use RTP/SDP for their sessions, too)

    + +

    All three protocols are defined in IETF RFCs (RFC3550, RFC3551, +RFC2327, RFC2327). They can be used in both multicast and unicast +fashions. Polypaudio exclusively uses multicast RTP/SDP/SAP containing audio data.

    + +

    For more information about using these technologies with Polypaudio have a look on the respective module's documentation. + +

  • How can I use Polypaudio to stream music from my main PC to my LAN with multiple PCs with speakers?

    + +

    On the sender side create an RTP sink:

    + +
    +load-module module-null-sink sink_name=rtp
+load-module module-rtp-send source=rtp_monitor
+set-default-sink rtp
+
    + +

    This will make rtp the default sink, i.e. all applications will write to this virtual RTP device by default.

    + +

    On the client sides just load the reciever module:

    +
    +load-module module-rtp-recv
+
    + +

    Now you can play your favourite music on the sender side and all clients will output it simultaneously.

    + + +

    BTW: You can have more than one sender machine set up like this. The audio data will be mixed on the client side.

    • + +

  • How can I use Polypaudio to share a single LINE-IN/MIC jack on the entire LAN?

    + +

    On the sender side simply load the RTP sender module:

    + +
    +load-module module-rtp-send
+
    + +

    On the reciever sides, create an RTP source:

    + +
    +load-module module-null-sink sink_name=rtp
+load-module module-rtp-recv sink=rtp
+set-default-source rtp_monitor
+
    + +

    Now the audio data will be available from the default source rtp_monitor.

    + +

  • When sending multicast RTP traffic it is recieved on the entire LAN but not by the sender machine itself!

    + +

    Pass loop=1 to the sender module!

    • + +

  • Can I have more than one multicast RTP group?

    + +

    Yes! Simply use a new multicast group address. Use +the destination/sap_address arguments of the RTP +modules to select them. Choose your group addresses from the range +225.0.0.x to make sure the audio data never leaves the LAN.

    • diff --git a/doc/README.html.in b/doc/README.html.in index 3847a9e8..0e9b8261 100644 --- a/doc/README.html.in +++ b/doc/README.html.in @@ -44,7 +44,7 @@ Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

    Thu Apr 13 2006:

    Version 0.8 released; -changes include: too many to count; many, many minor fixes.

    +changes include: too many to count - consider reading this blog entry for more information; many, many minor fixes.

    Sun Nov 21 2004:

    Version 0.7 released; @@ -152,6 +152,7 @@ available. A simple main loop implementation is available as well.

  • module-lirc: a module to control the volume of a sink with infrared remote controls supported by LIRC.
  • module-mmkbd-evdev: a module to control the volume of a sink with the special volume keys of a multimeda keyboard.
  • module-zeroconf-publish: a module to publish local sources/sinks using mDNS zeroconf.
    • +
  • module-rtp-send, module-rtp-recv: a module to implement RTP/SAP/SDP based audio streaming.

    • polypaudio is the successor of my previous, ill-fated diff --git a/doc/modules.html.in b/doc/modules.html.in index 67f0e172..54cec804 100644 --- a/doc/modules.html.in +++ b/doc/modules.html.in @@ -283,7 +283,7 @@ module and point your browser to http://localhost:4714/. This module takes the same arguments as module-cli-protocol-tcp.

    -

    Miscellaneous

    +

    X Window System

    module-x11-bell

    @@ -315,6 +315,94 @@ and import credential data from/to the X11 display.

    cookie to store in the X11 display. If ommited the cookie of an already loaded protocol module is used. +

    Volume Control

    + +

    module-mmkbd-evdev

    + +

    Adjust the volume of a sink when the special multimedia buttons of modern keyboards are pressed.

    + + + + +
    device=Linux input device ("evdev", defaults to /dev/input/event0)
    sink=The sink to control
    + +

    module-lirc

    + +

    Adjust the volume of a sink when the volume buttons of an infrared remote control are pressed (through LIRC).

    + + + + + +
    config=The LIRC configuration file
    appname=The application name to pass to LIRC (defaults to polypaudio)
    sink=The sink to control
    + + +

    RTP/SDP/SAP Transport

    + +

    Polypaudio can stream audio data to an IP multicast group via the +standard protocols RTP, +SAP +and SDP +(RFC3550, RFC3551, RFC2327, RFC2327). This can be used for multiple +different purposes: for sharing a single microphone on multiple +computers on the local LAN, for streaming music from a single +controlling PC to multiple PCs with speakers or to implement a simple +"always-on" teleconferencing solution.

    + +

    The current implementation is designed to be used exlusively in +local area networks, though Internet multicasting is theoretically +supported. Only uncompressed audio is supported, hence you won't be +able to multicast more than a few streams at the same time over a +standard LAN.

    + +

    Polypaudio implements both a sender and a reciever for RTP +traffic. The sender announces itself via SAP/SDP on the same multicast +group as it sends the RTP data to. The reciever picks up the SAP/SDP +announcements and creates a playback stream for each +session. Alternatively you can use any RTP capable client to +recieve and play back the RTP data (such as mplayer).

    + +

    module-rtp-send

    + +

    This is the sender side of the RTP/SDP/SAP implementation. It reads +audio data from an existing source and forwards it to the network +encapsulated in RTP. In addition it sends SAP packets with an SDP +session description.

    + +

    In combination with the monitor source of module-null-sink +you can use this module to create an RTP sink.

    + + + + + + + + +
    source=The source to read the audio data from. If ommited defaults to the default source.
    format=, rate=, channels=Sample format to use, defaults to the source's.
    destination=Destination multicast group for both RTP and SAP packets, defaults to 224.0.0.56
    port=Destination port number of the RTP +traffic. If ommited defaults to a randomly chosen even port +number. Please keep in mind that the RFC suggests to use only even +port numbers for RTP traffic.
    mtu=Maximum payload size for RTP packets. If ommited defaults to 1280
    loop=Takes a boolean value, specifying whether locally generated RTP traffic should be looped back to the local host. Disabled by default.
    + +

    module-rtp-recv

    + +

    This is the reciever side of the RTP/SDP/SAP implementation. It +picks up SAP session announcements and creates an RTP playback stream +for each.

    + +

    In combination with module-null-sink you can use this +module to create an RTP source.

    + + + + +
    sink=The sink to connect to. If ommited defaults to the default sink.
    sap_address=The multicast group to join for SAP announcements, defaults to 224.0.0.56.
    + +

    Miscellaneous

    +

    module-sine

    Creates a sink input and generates a sine waveform stream.

    @@ -360,24 +448,6 @@ already loaded protocol module is used.

    Publish all local sinks/sources using mDNS Zeroconf.

    -

    module-mmkbd-evdev

    - -

    Adjust the volume of a sink when the special multimedia buttons of modern keyboards are pressed.

    - - - - -
    device=Linux input device ("evdev", defaults to /dev/input/event0)
    sink=The sink to control
    - -

    module-lirc

    - -

    Adjust the volume of a sink when the volume buttons of an infrared remote control are pressed (through LIRC).

    - - - - - -
    config=The LIRC configuration file
    appname=The application name to pass to LIRC (defaults to polypaudio)
    sink=The sink to control
    Lennart Poettering <@PACKAGE_BUGREPORT@>, April 2006
    -- cgit