From f9b943358dae95111268ede9c793f78683ac8827 Mon Sep 17 00:00:00 2001 From: "Steinar H. Gunderson" Date: Fri, 18 Nov 2016 23:13:16 +0100 Subject: [PATCH] Various tweaks, including introductions from the README. --- audio.rst | 2 +- gettingstarted.rst | 3 +- hardware.rst | 17 ++++++++++ index.rst | 14 +++----- intro.rst | 85 ++++++++++++++++++++++++++++++++++++++++++++++ 5 files changed, 110 insertions(+), 11 deletions(-) create mode 100644 intro.rst diff --git a/audio.rst b/audio.rst index 8aa2078..6a9e87d 100644 --- a/audio.rst +++ b/audio.rst @@ -284,7 +284,7 @@ effect as pulling the fader all the way down, ie., it will make the bus go all silent. Then there's the **peak meter** to the left of that. For each bus, unlike -for the meters used for mastering (see :ref:`audio meters`), +for the meters used for mastering (see :ref:`audio-meters`), you don't want to know loudness; you want to know recording levels, so this is a peak meter, *not* a loudness meter. (There's some holdoff so you can see the actual peaks over a short period.) In particular, diff --git a/gettingstarted.rst b/gettingstarted.rst index dc7f26d..82b4457 100644 --- a/gettingstarted.rst +++ b/gettingstarted.rst @@ -3,7 +3,8 @@ Getting started Welcome to Nageru! For simple use, you can jump right in and make yourself comfortable (at least if you have the :doc:`hardware requirements ` -in place), but if you prefer a gentler introduction, this is the place. +in place and have `compiled it `), but if you prefer a gentler introduction, +this is the place. Introduction to the M/E workflow diff --git a/hardware.rst b/hardware.rst index 8a2bb06..9d15780 100644 --- a/hardware.rst +++ b/hardware.rst @@ -122,3 +122,20 @@ account for clock and jitter). Nageru works in 16-bit floating-point RGBA internally. High-quality conversion to and from subsampled Y'CbCr (typically 4:2:2 for inputs and 4:2:0 for outputs) is done transparently on the GPU. + + +Performance tips +---------------- + +It is strongly recommended to have the rights to run at real-time priority; +it will make the USB3 threads do so, which will make them a lot more stable. +(A reasonable hack for testing is probably just to run it as root using sudo, +although you might not want to do that in production, but instead grant +your regular user permissions in /etc/security/limits.conf.) Note also that if you +are running a desktop compositor, it will steal significant amounts of GPU +performance. The same goes for PulseAudio. + +Nageru tries to lock itself into RAM if it has the permissions to do +so, for better realtime behavior. (Writing the stream to disk tends to +fill the buffer cache, eventually paging less-used parts of Nageru out.) +Again, this is something you can set in limits.conf. diff --git a/index.rst b/index.rst index 997c152..c6b295c 100644 --- a/index.rst +++ b/index.rst @@ -1,25 +1,21 @@ Welcome to Nageru's documentation! ================================== -The documentation is still incomplete. Be sure to also read the README -and ideally also the NEWS file between each version. +Nageru is a live video mixer, based around the standard M/E workflow. +This online documentation aims to give a comprehensive introduction +to all of Nageru's features. Contents: .. toctree:: :maxdepth: 2 + intro gettingstarted hardware audio streaming theme - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` +:ref:`search` diff --git a/intro.rst b/intro.rst new file mode 100644 index 0000000..1f02179 --- /dev/null +++ b/intro.rst @@ -0,0 +1,85 @@ +Introduction +============ + +Nageru is a live video mixer, based around the standard M/E workflow. + +Features: + + * High performance on modest hardware (720p60 with two input streams + on my Thinkpad X240 [1]_); almost all pixel processing is done on the GPU. + + * High output quality; Lanczos3 scaling, subpixel precision everywhere, + white balance adjustment, mix of 16- and 32-bit floating point + for intermediate calculations, dithered output. + + * Proper sound support: Syncing of multiple unrelated sources through + high-quality resampling, multichannel mixing with separate effects + per-bus, cue out for headphones, dynamic range compression, + three-band graphical EQ (pluss a fixed low-cut), level meters conforming + to EBU R128, automation via MIDI controllers. + + * Theme engine encapsulating the design demands of each individual + event; Lua code is responsible for setting up the pixel processing + pipelines, running transitions etc., so that the visual look is + consistent between operators. + +.. [1] For reference, that is: Core i7 4600U (dualcore 2.10GHz, clocks down + to 800 MHz after 30 seconds due to thermal constraints), Intel HD Graphics + 4400 (ie., without the extra L4 cache from Iris Pro), single-channel DDR3 RAM + (so 12.8 GB/sec theoretical memory bandwidth, shared between CPU and GPU). + +.. _compile: + +Compiling +--------- + +The preferred way of getting Nageru is usually from your Linux distribution +of choice, but you can of course also compile it yourself (which will also +usually give you a newer version). It currently need: + + - Movit, my GPU-based video filter library (https://movit.sesse.net). + You will need at least version 1.3.1, but at least 1.4.0 is recommended. + + - Qt 5.5 or newer for the GUI. + + - libmicrohttpd for the embedded web server. + + - x264 for encoding high-quality video suitable for streaming to end users. + + - ffmpeg for muxing, and for encoding audio. You will need at least + version 3.1. + + - 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. + + - 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. + + - libpci, for printing friendly PCI device names in an error message. + + +If on Debian stretch or something similar, you can install everything you need +with: + + apt install qtbase5-dev libqt5opengl5-dev qt5-default pkg-config libmicrohttpd-dev \ + libusb-1.0-0-dev liblua5.2-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 November 2016: + + - libusb 1.0.21 is not yet in stretch; you need to fetch it from sid. + Same with a bmusb version built against it. + +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 (ie., my ex-work +email), and under the same license as zita-resampler itself. + +To start it, just hook up your equipment, type “make” and then “./nageru”. -- 2.39.2