X-Git-Url: https://git.sesse.net/?p=nageru-docs;a=blobdiff_plain;f=gettingstarted.rst;h=fd6f64678965d21cc1885a707eb882993d2a215f;hp=c73686bf47158d539eebc11c6167a09cc7ed51b5;hb=2eeb492b65ccbb2e2439d9f772ebdc64f70d40ea;hpb=6991b7523d838658cba1f55140f77ce854645cb9

diff --git a/gettingstarted.rst b/gettingstarted.rst
index c73686b..fd6f646 100644
--- a/gettingstarted.rst
+++ b/gettingstarted.rst
@@ -1,2 +1,209 @@
-Getting started with the Nageru UI (not written yet)
-====================================================
+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 and have `compiled it <compile>`_), but if you prefer a gentler introduction,
+this is the place.
+
+
+Introduction to the M/E workflow
+--------------------------------
+
+Nageru, like most hardware video mixers, is based on the **mixer/effects**
+workflow, or just M/E for short. (Don't ask why “mixer” or “effects”;
+the name is confusing and mostly historical.)
+
+The basic idea of M/E is that you have two main displays, *preview* and *live*.
+Every time you want to change what's shown to the viewer, you first bring it
+up on the preview display, verify that it indeed contains something you'd like
+to show to your viewers, and only then start a transition to move the preview
+display onto the live display (which mirrors exactly what the viewers see).
+After the transition is done, the preview and live displays switch, allowing
+the operator to either switch back or to pull a new source onto the preview
+display.
+
+In Nageru, the available transitions at any time are governed by the
+:doc:`theme </theme>`. However, generally a simple cut (moving immediately
+from live to preview) will nearly always be an option. Other effects include
+fades and zooms, but availability will depend on what sources are involved in the
+transition.
+
+
+A brief tour of the Nageru UI
+-----------------------------
+
+The basic Nageru UI with the default theme looks like this:
+
+.. image:: images/basic-ui.png
+
+First a word about user input: Nageru can be controlled by the mouse or
+keyboard, but most operators will prefer using both hands on the keyboard.
+Like on a real mixing console, you use your left hand to select sources for
+preview (using the 1–9 keys) and the right hand to choose a transition
+(using J, K or L). In addition, audio can be controlled using a MIDI controller
+if you want to; see the :doc:`audio <audio>` page for more information.
+
+In some situations, like if you're producing sports, it can be useful to
+skip the preview step and cut directly to a source. Nageru supports this
+through **quick-cut keys**; if enabled, Q, W, E, etc. will have the same
+effect as pressing 1, 2, 3, etc. and then quickly J (for cut). Since it
+is easy to press such a key by mistake, this behavior is off by default,
+and must be enabled explicitly from the Video menu or through the
+“--quick-cut-keys” option.
+
+
+Channels
+''''''''
+
+The preview and live displays are the most important part of the UI,
+and thus take up the bulk of the space. In addition, we have the list
+of channels and scenes (the side-by-side view and the static image)
+along the bottom. As you can see, we have only
+one (rather boring) input connected, and it is live. The other input is
+disconnected and thus shows only a test color. These correspond to pressing
+the 1 and 2 keys on the keyboard to activate preview, respectively—or you can
+left-click on them do achieve the same effect. (Right-clicking will bring up
+:ref:`the video card context menu <context-menu>`; see below.)
+
+Similarly, we have a side-by-side view; it is composed of a big image of
+input 1 and a smaller one of input 2. (If you are unhappy which is which,
+you can switch the two inputs; again, see below.)
+
+Finally, we have a static image. The one included with Nageru is rather
+bland and generic, but it works as a generic pause image when you don't
+really want anything on the screen.
+
+For any given channel, you can see that it is active in the live or preview
+by looking at its border. If it's got a red border, as in the leftmost
+input, it's live (either on its own, or as part of the side-by-side view).
+Similarly, if it's got a green border, as in the second input (you can
+see it if you look closely; it's a somewhat lighter shade of green),
+it is the preview. On conflict, red (live) wins, since it is the most
+important piece of information.
+
+If you have many channels, the default single-row view can make for previews
+that are somewhat small. If so, you can switch to the *video grid display*;
+see :ref:`audio-views` for more information.
+
+
+Transitions
+'''''''''''
+
+Whenever you have a different channel pulled up on the preview from
+on the live display, you will see that the three buttons in the middle
+offer you various **transitions**. Selecting any of them (either by
+the displayed hotkey, or using the mouse) will *swap* the preview and
+live inputs, effectively making the preview live. If you use “cut”,
+this will happen nearly instantly; the two other options, zoom
+(only available with the side-by-side view) and fade (*not* available
+with the side-by-side view) take some time, as you can see in the live view.
+
+A good operator knows to use the right transition at the right time,
+so that the end result does not distract from the actual message
+of the video. In particular, too frequent switching between sources
+will probably be perceived as disturbing.
+
+
+The audio strip
+'''''''''''''''
+
+The look of the audio strip will vary significantly with what audio
+mode you are in; the default is the simple mode, but multichannel
+is much more powerful. Both modes, as well as the level meters on
+the right, are explained in detail in the section about :doc:`audio <audio>`.
+
+
+The menu bar
+''''''''''''
+
+The menu bar does not contain a lot of interesting information,
+but it does have a few elements that are useful for configuration.
+The video menu contains the following elements:
+
+  * **Begin new video segment:** Nageru is constantly recording
+    your stream to disk in a near-lossless H.264 stream
+    (you cannot turn it off, because experience shows you'd probably
+    forget to turn it back on again in time for actual use);
+    see :doc:`streaming` for more information. This option allows
+    you to end the current file and begin a new one—the two files
+    can be spliced back later for a 100% seamless result if you wish,
+    so this is a lossless operation. It is typically useful
+    to do this right before and after the event itself starts,
+    so as to facilitate easier editing later.
+
+    You can achieve the same effect as this option by sending
+    SIGHUP to the Nageru process.
+
+  * **Open frame analyzer:** See :doc:`analyzer` for more information.
+
+  * **Change x264 bitrate:** See :doc:`streaming` for more information.
+
+  * **HDMI/SDI output device, HDMI/SDI output resolution, Display time code:**
+    See :doc:`hdmisdi` for more information.
+
+  * **Enable quick-cut keys:** See above.
+
+  * **Exit:** Exits Nageru, obviously.
+
+The audio menu is explained in the section on :doc:`audio <audio>`.
+
+Finally, the menu bar also hosts the disk space meter. This shows
+how much disk you have left before Nageru will error out and die;
+it also tries to estimate how much real time this corresponds to,
+based on the last 30 seconds of recording. 
+
+
+.. _context-menu:
+
+The video card context menu
+'''''''''''''''''''''''''''
+
+If you right-click on a channel that corresponds to a video input
+(ie., not the side-by-side view or static image), a simple context menu
+pops up:
+
+.. image:: images/context-menu.png
+
+The options presented are as follows:
+
+ * **Input source:** Connect this video input to a different physical card,
+   taking effect immediately. The theme supports only two inputs
+   at a time (you can :doc:`write your own <theme>` that support many
+   more if you wish), but if you start Nageru with a higher value
+   for the “--num-cards” option (aka -c), you can choose any of the
+   available ones here. This option is also useful if you want to
+   switch the two cards, since input 1 is bigger in side-by-side mode.
+   (See also the “--map-signal” option, aka -m.)
+
+ * **Video input:** If a card supports multiple kinds of inputs
+   (e.g. has both HDMI and analog inputs), you can select which one here.
+
+ * **Audio input:** Similar, just for audio. “Embedded” means
+   an audio stream that is included in the HDMI or SDI signal.
+
+ * **Input mode:** Choose the video input mode to use. Note that the USB
+   cards autodetect the mode, and you cannot override it even if you wanted to.
+   For PCI cards, autodetection is not supported (even for the select few
+   cards that can handle it in hardware), but a simple option (“Scan”)
+   is available to try all modes in turn until a signal is received.
+
+ * **Input interpretation:** Choose how the Y'CbCr values in the input signal
+   are to be interpreted. *Auto* will choose whatever is correct (as per the
+   appropriate standards) for the current video mode, but occasionally,
+   devices will get this wrong, and you will need to change this setting
+   to get correct colors. You can use the *--input-ycbcr-interpretation=*
+   command-line option to achieve the same effect.
+
+   See :doc:`analyzer` for figuring out if you need to change this.
+   If unsure, leave it unchanged.
+
+ * **Use as audio source:** See the :doc:`audio <audio>` page for more
+   information. For simple audio only; unavailable in multichannel mode.
+
+ * **Use as master clock:** The output stream needs exactly one stream
+   as master clock. The frame rate and clocked will be locked exactly
+   to it, so use the most important input here. A signal that keeps getting
+   unplugged and replugged might not be the best candidate, although the
+   PCI cards have fallback internal clocking when the signal is lost
+   (the USB cards fall back to a strange mode of about 30.13 Hz).