git.sesse.net Git - cubemap/blob - README

   1 Cubemap is a high-performance, high-availability video reflector,
   2 specifically made for use with VLC.
   3
   4 A short list of features:
   5
   6  - High-performance, through a design with multiple worker threads,
   7    epoll and sendfile (yes, sendfile); a 2GHz quadcore can saturate
   8    10 gigabit Ethernet (even with TLS) given a modern kernel.
   9  - High-availability. You can change any part of the configuration
  10    (and even upgrade to a newer version of Cubemap) by changing cubemap.config
  11    and sending a SIGHUP; all clients will continue as if nothing had happened
  12    (unless you delete the stream they are watching, of course).
  13    Cubemap also survives the encoder dying and reconnecting.
  14  - Support for setting max pacing rate through the fq packet scheduler
  15    (depends on Linux 3.13 or newer).
  16  - Reflects anything VLC can reflect over HTTP, even the muxes VLC
  17    has problems reflecting itself (in particular, FLV).
  18  - Multicast support, both for sending and receiving (supports only protocols
  19    that can go over UDP, e.g. MPEG-TS). Supports both ASM and SSM.
  20  - TLS output support, through the TLSe library (requires libtomcrypt)
  21    and the Linux kernel's kTLS (Linux 4.17 or newer). There are a few
  22    limitations; see below.
  23  - fMP4 (HLS) output support, generating playlists on-the-fly. Note that this
  24    requires some extra metadata currently only set by Nageru (not VLC).
  25  - IPv4 support. Yes, Cubemap even supports (some) legacy protocols.
  26
  27
  28 HOWTO:
  29
  30   sudo apt install libprotobuf-dev protobuf-compiler libsystemd-dev libtomcrypt-dev pkg-config
  31   ./configure
  32   make -j4
  33
  34 If you want to use HTTP input (you probably want to), you want VLC 2.2.0
  35 or newer. Then start the VLC encoder with the “metacube” flag to the http
  36 access mux, like this:
  37
  38   cvlc [...] --sout '#std{access=http{metacube,mime=video/x-flv},mux=flv,dst=:4013/test.flv}'
  39
  40 Then look through cubemap.config.sample, copy it to cubemap.config,
  41 compile and start cubemap.
  42
  43 Nageru, my free video mixer, can also produce Metacube streams natively.
  44 See the manual at https://nageru.sesse.net/doc/ for more information.
  45
  46 If you feel very adventurous, you can use LD_PRELOAD to load
  47 ffmpeg_metacube_hack.so into an FFmpeg-using binary. (This is
  48 experimental; native Metacube support is vastly preferred.)
  49 For instance, here's one way you can use the ffmpeg(1) binary
  50 to serve your webcam to Cubemap:
  51
  52   LD_PRELOAD=ffmpeg_metacube_hack.so ffmpeg -i /dev/video0 -f mpegts -listen 1 'http://[::]:9095'
  53
  54
  55 To upgrade cubemap (after you've compiled a new binary), or to pick up new
  56 config:
  57
  58   killall -HUP cubemap
  59
  60 Cubemap will serialize itself to disk, check that the new binary and config
  61 are OK, and then exec() the new version, which deserializes everything and
  62 keeps going.
  63
  64
  65 Notes on TLS support:
  66
  67 Cubemap supports TLS on output, so that you can play video on TLS
  68 web sites without issues with mixed content. TLS on input streams is
  69 not (yet) supported.
  70
  71 TLS requires kTLS for both send and receive, ie., Linux >= 4.17 with CONFIG_TLS
  72 enabled. Only cipher suites supported by kTLS is supposed, ie., AES-128-GCM
  73 (if no such cipher suite is available, the connection will be aborted). If the
  74 server is restarted before the key exchange for a connection is completed,
  75 that connection will not survive the restart, unlike all other connections.
  76 (This is a TLSe limitation.) You can have different certificates on different
  77 ports (and have separate ports for TLS and non-TLS), but SNI is not yet
  78 supported.
  79
  80
  81 Munin plugins:
  82
  83 To activate these, symlink them into /etc/munin/plugins. If you don't put
  84 the files in the expected default locations (as done by 'make install'),
  85 you probably want some configuration in /etc/munin/plugin-conf.d/cubemap or
  86 similar, like this:
  87
  88 [cubemap*]
  89 user <something>
  90 env.cubemap_config /etc/cubemap/cubemap.config
  91 env.cubemap_stats /var/lib/cubemap/cubemap.stats
  92 env.cubemap_input_stats /var/lib/cubemap/cubemap-input.stats
  93
  94
  95 Legalese:
  96
  97 Copyright 2013 Steinar H. Gunderson <steinar+cubemap@gunderson.no>.
  98 Licensed under the GNU GPL, version 2. See the included COPYING file.
  99
 100 See tlse/LICENSE for TLSe licensing.