Various tweaks, including introductions from the README.

diff --git a/audio.rst b/audio.rst
index 8aa2078b6dbbea43b1684943189960c7db2cc344..6a9e87d1c691768b1c450b5a8abb3cd51208ad5e 100644 (file)
--- 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 dc7f26de68450e824db401d103e0e3a0def6b07d..82b44577a263d1ab130e33ad5459e05f84b6927b 100644 (file)
--- 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 <hardware>`
-in place), but if you prefer a gentler introduction, this is the place.
+in place and have `compiled it <compile>`), 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 8a2bb06f0e801e75a04643fe646f198fc0085641..9d157807c03a6ec7d7cdd56600b1085cbd5e894a 100644 (file)
--- 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 997c152be983fa23b633c60234b3f53674471341..c6b295c8fe87369fc08e045b3a025d9c5ad2c92f 100644 (file)
--- 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 (file)
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 <sesse@google.com> (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”.