Various tweaks, including introductions from the README.

[nageru-docs] / intro.rst

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”.