Better documentation of config options in cubemap.config.sample.
authorSteinar H. Gunderson <sgunderson@bigfoot.com>
Fri, 7 Aug 2015 20:54:50 +0000 (22:54 +0200)
committerSteinar H. Gunderson <sgunderson@bigfoot.com>
Fri, 7 Aug 2015 20:58:30 +0000 (22:58 +0200)
There were too many options that were basically undocumented by now;
add some hopefully helpful comments.

cubemap.config.sample

index 0953b7b..d15e861 100644 (file)
@@ -31,13 +31,63 @@ error_log type=syslog
 error_log type=console
 
 #
-# now the streams!
+# Now the streams! There are two types of streams; stream (HTTP output)
+# and udpstream (UDP output). Let's take stream first.
 #
-stream /test.flv src=http://gruessi.zrh.sesse.net:4013/test.flv force_prebuffer=1500000
+
+# A basic form of stream, with HTTP input. Often, you will need no more than this.
+# The input must be Metacube framed (VLC can produce this with an option).
+stream /test.flv src=http://gruessi.zrh.sesse.net:4013/test.flv
+
+# Streams can share the same input (the same is reused, no extra bandwidth needed).
+# force_prebuffer=<number of bytes> is a parameter where we don't start sending
+# any data to a newly connected client before we can do that many bytes at once.
+# This is useful for clients that don't properly buffer themselves before starting
+# playing, e.g., most web browsers and some Flash players when playing from HTTP
+# (e.g., JW Player).
+stream /test-jwplayer.flv src=http://gruessi.zrh.sesse.net:4013/test.flv force_prebuffer=1500000
+
+# encoding=metacube means the _output_ will be Metacube framed. This is useful
+# for sending on to another Cubemap instance.
 stream /test.flv.metacube src=http://gruessi.zrh.sesse.net:4013/test.flv encoding=metacube
+
+# UDP input. TS is the most common container to use over UDP (you cannot
+# take any arbitrary container and expect it to work).
+# backlog_size=<number of bytes> overrides the backlog, which is normally 10 MB.
+# If clients fall more behind than the backlog (plus the socket buffer),
+# they will drop data, so if you have extremely high-bitrate streams, you may want
+# to increase this. Or conversely, if you have little RAM and many streams
+# (or many servers) you can decrease it.
 stream /udp.ts src=udp://@:1234 backlog_size=1048576
+
+# An example of IPv4 multicast input. Cubemap will subscribe to the given group
+# and wait for data sent by any sender to the given port.
+# pacing_rate_kbit=<number of kilobit/sec> will ask the kernel to hard-limit
+# the TCP transfer rate, including retransmits, to the given speed. (This is a
+# no-op if you do not use the sch_fq packet scheduler, which is not the default
+# but can be set in Linux 3.13 and newer using tc.) This is extremely
+# useful for reducing packet loss and thus including throughput, since it means
+# that packets arrive smoothly instead of in tight bursts, which will often
+# overload underbuffered routers and cause drops (imagine receiving a 100 kB
+# keyframe at 10gig speeds, and then having to meter it out over 5 Mbit ADSL).
+# The rate should be a bit higher than your stream bitrate to allow for retransmits.
 stream /udp-multicast.ts src=udp://@233.252.0.2:1234 pacing_rate_kbit=2000
+
+# IPv6 SSM (Single Source Multicast) input. Subscribes to the given group and
+# waits for packets from the given sender only. SSM is nicer than ASM in that
+# it does not require a Rendezvous Point (RP) and other complexity, but is
+# often poorly supported in various network equipment.
 stream /udp-multicast-ssmv6.ts src=udp://[2001:67c:29f4::32]@[ff3e::1000:0]:1234 pacing_rate_kbit=20000
+
+# udpstream takes src= inputs just like stream does, but instead of waiting
+# for TCP connections on ports, it immediately sends the packets out over UDP.
+# (As with UDP input, this probably only works well for TS mux.)
 udpstream [2001:67c:29f4::50]:5000 src=http://pannekake.samfundet.no:9094/frikanalen.ts.metacube
-udpstream 193.35.52.50:5001 src=http://pannekake.samfundet.no:9094/frikanalen.ts.metacube
+
+# udpstream takes pacing_rate_kbit= just like stream. None of the other options
+# make sense.
+udpstream 193.35.52.50:5001 src=http://pannekake.samfundet.no:9094/frikanalen.ts.metacube pacing_rate_kbit=2000
+
+# IPv4 multicast output, to the given group. You can explicitly set the TTL
+# and/or multicast output interface, if the defaults do not suit you.
 udpstream 233.252.0.1:5002 src=http://pannekake.samfundet.no:9094/frikanalen.ts.metacube ttl=32 multicast_output_interface=eth1