--- /dev/null
+HTML inputs
+===========
+
+HTML inputs are used for on-the-fly generated graphics, ie. typically animated
+overlay graphics that cannot be simple still pictures. They allow you to write graphics
+in full HTML5 (including JavaScript) by way of `Chromium Embedded Framework
+<https://bitbucket.org/chromiumembedded/cef/>`_ (CEF for short), a library that
+basically embeds a full copy of the Chromium web browser into Nageru.
+
+HTML inputs are available from Nageru 1.7.0 onwards, but note that they are an
+optional component, since many distributions don't carry CEF. Thus, your copy
+of Nageru may not support them. See :ref:`compiling` for information on how to
+build Nageru with CEF.
+
+Due to CEF performance issues, Nageru does not currently run CEF with GPU
+rendering enabled, even though the rest of Nageru is very much centered around
+the GPU. In particular, this means you do not currently have WebGL support.
+
+
+Basic HTML inputs
+-----------------
+
+In many ways, HTML inputs are similar to :doc:`video inputs <video>`, so you should
+probably understand how they work first. An HTML input is created by way of instantiating
+the *HTMLInput* class::
+
+ local html_input = HTMLInput.new("file:///path/to/graphics/foo.html")
+
+Any regular URL is acceptable, and the sandbox is turned off for convenience,
+so that you can load remote resources from local files. (If you wish to locate
+your HTML path by way of the theme, the variable Nageru.THEME_PATH could prove
+useful, as it contains the absolute path to the theme in current use.)
+
+You can then add this HTMLInput to a chain (or multiple chains if you'd like),
+using code like::
+
+ local image = chain:add_html_input(html_input)
+
+Like video inputs, you can call *get_signal_num()* on the HTML input to get
+its signal number, for getting its resolution etc. (see below for changing
+it). Also like video inputs, there is no audio support (although you may find audio
+played by the web page coming out your regular speakers, not controlled by
+Nageru!). This may change in the future.
+
+
+Controlling HTML inputs
+-----------------------
+
+Generally, HTML inputs run in a background thread and deliver frames
+asynchronously to Nageru. Due to the way CEF works, there is unfortunately no
+obvious way of getting frame-perfect sync between graphics and overlay
+(there can always be a frame or two of lag between the two);
+however, this is normal even in a hardware chain, and most overlay graphics
+does not need to be timed to the input more than through a few frames.
+
+This, and the fact that the theme can not present a very detailed UI
+(short of :ref:`simple menus <menu>`), means that it can be hard to
+exert detailed control over the graphics using Nageru alone—you will
+probably want to have the theme contact some non-Nageru backend (possibly over
+WebSockets) from where it can take detailed instructions.
+
+However, the theme *can* ask the HTML input to run arbitrary JavaScript,
+by calling *html_input:execute_javascript_async("your code here")*, which allows
+you to bring at least some loose coupling between the two. (The “async”
+part is to emphasize that you cannot necessarily expect the effects of
+the code to be visible on the same frame as you start them. The JavaScript
+still runs on the regular UI thread, so if you want to run longer jobs,
+you should use a web worker or similar.) There is currently no way to run
+Lua code from JavaScript, though.
+
+Finally, you can change the URL by using *html_input:set_url("new_url")*,
+or reload the current one using *html_input:reload()*. It can be especially
+useful to bind the latter to a menu entry, in case you want to modify your
+HTML code without restarting Nageru.
+
+
+Changing the resolution and frame rate
+--------------------------------------
+
+By default, HTML inputs try to run at the CEF maximum of 60 frames per second
+(CEF does not support non-integer frame rates), but if you wish to conserve
+CPU, or if you run at PAL rates, you can ask for a lower maximum frame rate using
+e.g. *html_input:set_max_fps(15)*. Also, you can change the resolution from
+the default (which is to match your output stream's resolution), using
+*html_input:resize(width, height)*.
hdmisdi
theme
video
+ html
monitoring
:ref:`search`
- Working OpenGL; Movit works with almost any modern OpenGL implementation.
Nageru has been tested with Intel on Mesa (you want 11.2 or newer, due
to critical stability bugfixes), and with NVIDIA's proprietary drivers.
- AMD's proprietary drivers (fglrx) are known not to work due to driver bugs;
- I am in contact with AMD to try to get this resolved.
+ The status of AMD's proprietary drivers is currently unknown.
- libzita-resampler, for resampling sound sources so that they are in sync
between sources, and also for oversampling for the peak meter.
- - Lua, for driving the theme engine.
+ - LuaJIT, for driving the theme engine.
- libpci, for printing friendly PCI device names in an error message.
+ - Optional: CEF (Chromium Embedded Framework), for HTML graphics.
+ If you build without CEF, the HTMLInput class will not be available from
+ the theme. You can get binary downloads of CEF from
+
+ http://opensource.spotify.com/cefbuilds/index.html
+
+ Simply download the right build for your platform (the “minimal” build
+ is fine) and add CEF_DIR=<path>/cef_binary_X.XXXX.XXXX.XXXXXXXX_linux64
+ on the make command line (substituting X with the real version as required).
+
If on Debian stretch or something similar, you can install everything you need
with:
apt install qtbase5-dev libqt5opengl5-dev qt5-default libqcustomplot-dev \
- pkg-config libmicrohttpd-dev libusb-1.0-0-dev liblua5.2-dev \
+ pkg-config libmicrohttpd-dev libusb-1.0-0-dev libluajit-5.1-dev \
libzita-resampler-dev libva-dev libavcodec-dev libavformat-dev \
libswscale-dev libavresample-dev libmovit-dev libegl1-mesa-dev \
libasound2-dev libx264-dev libbmusb-dev protobuf-compiler \
libprotobuf-dev libpci-dev
-Exceptions as of July 2017:
+Exceptions as of February 2018:
- You will need Movit from unstable; stretch only has 1.4.0.
- You will need bmusb from unstable; stretch only has 0.5.4.
+ - Debian does not carry CEF (but it is optional).
+
+
The patches/ directory contains a patch that helps zita-resampler performance.
It is meant for upstream, but was not in at the time Nageru was released.
It is taken to be by Steinar H. Gunderson <sesse@google.com> (ie., my ex-work
Integration with CasparCG
-------------------------
-`CasparCG <http://casparcg.com/>`_ is an open-source broadcast graphics system,
-originally written by SVT, the Swedish public TV broadcaster. (In this
-context, “graphics” refers mostly to synthetically generated content,
-such as the score box in a sporting match.) With some coaxing, it is possible
-to integrate CasparCG with Nageru, so that Nageru does the mixing of the video
-sources and CasparCG generates graphics—CasparCG can also work as a standalone
-mixer indepedently of Nageru, but this will not be covered here.
-
-The most straightforward use of CasparCG is to use it to generate an overlay,
-which is then taken in as a video input in Nageru. To achieve this, the simplest
-solution is to send raw BGRA data over a UNIX domain socket [#rawvideo]_, which involves
-adding an FFmpeg output to your CasparCG configuration. This can either be done
-by modifying your casparcg.config to open up a socket in your home directory
-(you shouldn't use /tmp on a multi-user machine, or you may open up a security
-hole)::
-
- <consumers>
- <ffmpeg>
- <device>1</device>
- <path>unix:///home/user/caspar.sock</path>
- <args>-c:v rawvideo -vf format=pix_fmts=bgra -f nut -listen 1</args>
- </ffmpeg>
- <system-audio></system-audio>
- </consumers>
-
-or by setting it up on-the-fly through ACMP::
-
- add 1 stream unix:///home/user/caspar.sock -c:v rawvideo -vf format=pix_fmts=bgra -f nut -listen 1
-
-You can then use *unix:///home/user/caspar.sock* as a video input to Nageru on the
-same machine, and then use e.g. *OverlayEffect* to overlay it on your video chains.
-(Remember to set up the video as BGRA and not Y'CbCr, so that you get alpha.)
-
-CasparCG and Nageru does not run with synchronized clocks, so you will not get
-frame-perfect synchronization between graphics and overlay; however, this is normal
-even in a hardware chain, and most overlay graphics does not need to be timed
-to the input more than through a few frames. However, note that it is possible
-that Nageru lags behind CasparCG's graphics production after a while (typically
-on the order of hours) due to such clock skew; the easiest solution to this is
-just to use *change_rate(2.0)* or similar on the input, so that Nageru will consume
-CasparCG's frames as quickly as they come in without waiting any further.
-
-There's also one usability stumbling block: *CasparCG's FFmpeg
-streams are one-shot, and so are FFmpeg's UNIX domain sockets.* This means that,
-in practice, if Nageru ever disconnects from CasparCG for any reason, the socket
-is “used up”, and you will need to recreate it somehow (e.g., by restarting CasparCG).
-Also note that the old socket still lingers in place even after being useless,
-so you will *first* need to remove it, and CasparCG does not do this for you.
-The simplest way to deal with this is probably to have a wrapper script of some
-sort that orchestrates Nageru, CasparCG and your client for you, so that everything
-is taken up and down in the right order; it may be cumbersome and require some
-tweaking for oyur specific case, but it's not a challenging problem per se.
-
-Nageru does not have functionality to work as a CasparCG client in itself,
-nor can your theme present a very detailed UI to do so. However, do note that
-since the theme is written in unrestricted Lua, so you can use e.g.
-`lua-http <https://github.com/daurnimator/lua-http>`_ to send signals
-to your backend (assuming it speaks HTTP) on e.g. transition changes.
-With some creativity, this allows you to at least bring some loose coupling
-between the two.
-
-In general, the integration between Nageru and CasparCG leaves a bit to be
-desired, and in general, the combination of CasparCG + Nageru will require
-a beefier machine than Nageru alone. However, it also provides a much richer
-environment for graphics, so for many use cases, it will be worth it.
-
-.. [#rawvideo] Good video codecs that support alpha are rare, so as long as CasparCG
- and Nageru are running on the same machine, raw video is probably your
- best bet. Even so, note that FFmpeg's muxers are not really made for
- such large amounts of data that raw HD video produces, so there will
- be some performance overhead on both sides of the socket.
+This section has been removed, as since 1.7.0, Nageru has :ref:`native support
+for HTML5 inputs <html>`, obsoleting CasparCG integration.
projects / nageru-docs / commitdiff