release/src/router/udpxy/README

   1 #
   2 # Copyright 2008-2011 Pavel V. Cherenkov (pcherenkov@gmail.com)
   3 #
   4 #  This file is part of udpxy.
   5 #
   6 #  udpxy is free software: you can redistribute it and/or modify
   7 #  it under the terms of the GNU General Public License as published by
   8 #  the Free Software Foundation, either version 3 of the License, or
   9 #  (at your option) any later version.
  10 #
  11 #  udpxy is distributed in the hope that it will be useful,
  12 #  but WITHOUT ANY WARRANTY; without even the implied warranty of
  13 #  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14 #  GNU General Public License for more details.
  15 #
  16 #  You should have received a copy of the GNU General Public License
  17 #  along with udpxy.  If not, see <http://www.gnu.org/licenses/>.
  18 #
  19
  20 Summary
  21 --------------
  22
  23 udpxy is a UDP-to-HTTP multicast traffic relay daemon:
  24 it forwards UDP traffic from a given multicast subscription
  25 to the requesting HTTP client.
  26
  27 udpxy is released under GPL v.3
  28
  29 Building and installing
  30 --------------
  31
  32 Untar the *.tgz source distribution into a directory of your choice by
  33 running
  34         tar -xzvf udpxy.X.Y-ZZ.tgz
  35     or
  36         gzip -dc udpxy.X.Y-ZZ.tgz | tar -xvf -
  37
  38 Make sure make and gcc are available (gcc 3.x and up should work, lower
  39 versions are not guaranteed to build the source correctly); for compilers
  40 other than gcc alterations to makefile might be needed.
  41
  42 Running 'make' without a target will build the 'release' version of
  43 udpxy (no asserts, no debug symbols, verbose mode on).
  44
  45 Other make targets are:
  46     debug (asserts, debug symbols, verbose mode on);
  47     lean  (no asserts, no debug symbols, verbose mode off)
  48
  49 Once the make has succeeded, the udpxy executable file could be
  50 copied to a location of one's choice and run from there - no additional
  51 installation steps are required.
  52
  53 udpxy can be started with a number of configuration parameters,
  54 such as listening address/port, multicast interface name, etc.
  55 A brief usage summary is provided when udpxy is invoked from command line
  56 without parameters.
  57
  58 HTTP commands
  59 --------------
  60
  61 udpxy responds to HTTP (GET) commands to receive data from
  62 a dedicated multicast group and forward it to the initiating (HTTP)
  63 connection.
  64
  65 The command to relay traffic is in the format as below:
  66
  67 http://address:port/cmd/mgroup_address[SEP]mgroup_port/
  68
  69 [SEP] ::= :|%|~|+|-|^
  70 i.e:
  71     http://ip:port/cmd/mgroup_address:mgroup_port/
  72     http://ip:port/cmd/mgroup_address%mgroup_port/
  73     http://ip:port/cmd/mgroup_address~mgroup_port/
  74     ......
  75     http://ip:port/cmd/mgroup_address^mgroup_port/
  76
  77 are acceptable and should all work in the same manner.
  78
  79 cmd ::= udp | rtp
  80
  81 where address and port match the listening address/port combination of udpxy,
  82 and mgroup_address:mgroup_port identify the multicast group to subscribe to.
  83
  84 Using 'udp' command will instruct udpxy to probe for known types of payload
  85 (such as MPEG-TS and RTP over MPEG-TS); using 'rtp' makes udpxy assume RTP
  86 over MPEG-TS payload, thus skipping the probes.
  87
  88 udpxy will start a 'client' process for each new relay request as long as
  89 their number would not exceed a pre-set maximum (see usage summary).
  90
  91 udpxy also supports a few additional HTTP requests, such as:
  92
  93 http://address:port/status/  - to display basic daemon's statistics
  94 http://address:port/restart/ - to close all active connections and restart
  95
  96 Payload types and handling
  97 --------------
  98
  99 udpxy recognizes MPEG-TS and RTP (over MPEG-TS) payloads within relayed packets;
 100 if udpxy encounters RTP payload it automatically 'translates' it to MPEG-TS so that
 101 media players not recognizing RTP on TCP could still play back the stream.
 102
 103 So far, no translation is performed for other payload types.
 104
 105 Recording MPEG traffic
 106 --------------
 107 udpxy (in builds >33) includes functionality to record captured traffic as
 108 raw MPEG-TS stream into a file. This functionality is enabled through udpxrec:
 109 a bundled-in application that is linked together with udpxy (as one executable).
 110
 111 udpxrec is invoked by a symbolic link (named udpxrec) to the udpxy executable
 112 (NB: do not rename udpxy executable).
 113
 114 udpxrec creates MPEG files encapsulating MPEG-TS segments; most media players
 115 will *NOT* play such files; to make them playable the stream must be transcoded
 116 to MPEG-PS; vlc knows how to do such transcoding, here is a command-line example:
 117
 118 vlc input-ts.mpg --sout="#std{access=file,mux=ps,dst=out-ps.mpg}"
 119
 120 The resulting PS file can be played back by most media players.
 121
 122 Portability
 123 --------------
 124 udpxy was written to run on 'POSIX-compliant' systems;
 125 so far all builds have been tested to build and run on Linux 2.4, 2.6 (IA32, ARM)
 126 and *some* (but not all) on HP-UX 11.11 (PA-RISC 1.1, 2.0w).
 127
 128 Build 12 of version 1.0 (Chipmunk) was ported to compile under FreeBSD 7.1
 129 using GNU make 3.8
 130
 131 --EOF--
 132