X-Git-Url: https://git.sesse.net/?a=blobdiff_plain;ds=sidebyside;f=README;h=e9520d3aec889da9e53f9bad82f69352024080c3;hb=HEAD;hp=06c1c644b91ec555d190838e8d440e5d2b3329a7;hpb=32d84e70aa1f1c9cd8334aceac0a617b4a7b4b40;p=cubemap diff --git a/README b/README index 06c1c64..46a943a 100644 --- a/README +++ b/README @@ -1,7 +1,113 @@ -Cubemap is a high-performance, high-availaility video reflector, -specifically made for use with VLC. +Cubemap is a high-performance, high-availability video reflector. -Copyright 2013 Steinar H. Gunderson . -Licensed under the GNU GPL, version 2. +A short list of features: -More information to come here, later. :-) + - High-performance, through a design with multiple worker threads, + epoll and sendfile (yes, sendfile); a 2GHz quadcore can saturate + 10 gigabit Ethernet (even with TLS) given a modern kernel. + - High-availability. You can change any part of the configuration + (and even upgrade to a newer version of Cubemap) by changing cubemap.config + and sending a SIGHUP; all clients will continue as if nothing had happened + (unless you delete the stream they are watching, of course). + Cubemap also survives the encoder dying and reconnecting. + - Support for setting max pacing rate through the fq packet scheduler. + - Reflects anything VLC can reflect over HTTP, even the muxes VLC + has problems reflecting itself (in particular, FLV). Can also + call out to external programs to receive or fetch streams in arbitrary + ways (e.g. through SRT), although of course they do not necessarily + have the same intrinsic high-availability reconfiguration support. + - Multicast support, both for sending and receiving (supports only protocols + that can go over UDP, e.g. MPEG-TS). Supports both ASM and SSM. + - TLS output support, through the TLSe library (requires libtomcrypt) + and the Linux kernel's kTLS (Linux 4.17 or newer). There are a few + limitations; see below. + - fMP4 (HLS) output support, generating playlists on-the-fly. Note that this + requires some extra metadata currently only set by Nageru (not VLC). + - IPv4 support. Yes, Cubemap even supports (some) legacy protocols. + + +HOWTO: + + sudo apt install libprotobuf-dev protobuf-compiler libsystemd-dev libtomcrypt-dev pkg-config autoconf + sudo apt install libavformat-dev libavutil-dev # Optional + autoreconf -I . + ./configure + make -j4 + +Cubemap does not in itself understand the format of video streams; +it requires HTTP input that is already delineated into headers and blocks, +so that it knows what parts of the stream to skip to clients that +connect after the stream has been. (The exception is self-synchronizing +streams with no headers, such as MPEG-TS. These can also be sent or +received over UDP) The input format is specific to Cubemap and is called +Metacube (technically, Metacube2, but Metacube1 is long gone and nothing +uses it anymore). Currently, you have three options to create Metacube +video streams: VLC, Nageru or FFmpeg with a hack. + +For VLC, start the VLC encoder with the “metacube” flag to the http +access mux, like this: + + cvlc [...] --sout '#std{access=http{metacube,mime=video/x-flv},mux=flv,dst=:4013/test.flv}' + +Then look through cubemap.config.sample, copy it to cubemap.config, +compile and start cubemap. + +Nageru, my free video mixer, can also produce Metacube streams natively, +and so can its included transcoder/remuxer Kaeru. See the manual +at https://nageru.sesse.net/doc/ for more information. + +If you feel very adventurous, you can use LD_PRELOAD to load +ffmpeg_metacube_hack.so into an FFmpeg-using binary. (This is +experimental; native Metacube support is vastly preferred.) +For instance, here's one way you can use the ffmpeg(1) binary +to serve your webcam to Cubemap: + + LD_PRELOAD=ffmpeg_metacube_hack.so ffmpeg -i /dev/video0 -f mpegts -listen 1 'http://[::]:9095' + + +To upgrade cubemap (after you've compiled a new binary), or to pick up new +config: + + killall -HUP cubemap + +Cubemap will serialize itself to disk, check that the new binary and config +are OK, and then exec() the new version, which deserializes everything and +keeps going. + + +Notes on TLS support: + +Cubemap supports TLS on output, so that you can play video on TLS +web sites without issues with mixed content. TLS on input streams is +not (yet) supported. + +TLS requires kTLS for both send and receive, ie., Linux >= 4.17 with CONFIG_TLS +enabled. Only cipher suites supported by kTLS is supposed, ie., AES-128-GCM +(if no such cipher suite is available, the connection will be aborted). If the +server is restarted before the key exchange for a connection is completed, +that connection will not survive the restart, unlike all other connections. +(This is a TLSe limitation.) You can have different certificates on different +ports (and have separate ports for TLS and non-TLS), but SNI is not yet +supported. + + +Munin plugins: + +To activate these, symlink them into /etc/munin/plugins. If you don't put +the files in the expected default locations (as done by 'make install'), +you probably want some configuration in /etc/munin/plugin-conf.d/cubemap or +similar, like this: + +[cubemap*] +user +env.cubemap_config /etc/cubemap/cubemap.config +env.cubemap_stats /var/lib/cubemap/cubemap.stats +env.cubemap_input_stats /var/lib/cubemap/cubemap-input.stats + + +Legalese: + +Copyright 2013 Steinar H. Gunderson . +Licensed under the GNU GPL, version 2. See the included COPYING file. + +See tlse/LICENSE for TLSe licensing.