git.sesse.net Git - nageru-docs/blob - gettingstarted.rst

   1 Getting started
   2 ===============
   3
   4 Welcome to Nageru! For simple use, you can jump right in and make yourself
   5 comfortable (at least if you have the :doc:`hardware requirements <hardware>`
   6 in place and have `compiled it <compile>`_), but if you prefer a gentler introduction,
   7 this is the place.
   8
   9
  10 Introduction to the M/E workflow
  11 --------------------------------
  12
  13 Nageru, like most hardware video mixers, is based on the **mixer/effects**
  14 workflow, or just M/E for short. (Don't ask why “mixer” or “effects”;
  15 the name is confusing and mostly historical.)
  16
  17 The basic idea of M/E is that you have two main displays, *preview* and *live*.
  18 Every time you want to change what's shown to the viewer, you first bring it
  19 up on the preview display, verify that it indeed contains something you'd like
  20 to show to your viewers, and only then start a transition to move the preview
  21 display onto the live display (which mirrors exactly what the viewers see).
  22 After the transition is done, the preview and live displays switch, allowing
  23 the operator to either switch back or to pull a new source onto the preview
  24 display.
  25
  26 In Nageru, the available transitions at any time are governed by the
  27 :doc:`theme </theme>`. However, generally a simple cut (moving immediately
  28 from live to preview) will nearly always be an option. Other effects include
  29 fades and zooms, but availability will depend on what sources are involved in the
  30 transition.
  31
  32
  33 A brief tour of the Nageru UI
  34 -----------------------------
  35
  36 The basic Nageru UI with the default theme looks like this:
  37
  38 .. image:: images/basic-ui.png
  39
  40 First a word about user input: Nageru can be controlled by the mouse or
  41 keyboard, but most operators will prefer using both hands on the keyboard.
  42 Like on a real mixing console, you use your left hand to select sources for
  43 preview (using the 1–9 keys) and the right hand to choose a transition
  44 (using J, K or L). In addition, audio can be controlled using a MIDI controller
  45 if you want to; see the :doc:`audio <audio>` page for more information.
  46
  47
  48 Channels
  49 ''''''''
  50
  51 The preview and live displays are the most important part of the UI,
  52 and thus take up the bulk of the space. In addition, we have the list
  53 of channels and scenes (the side-by-side view and the static image)
  54 along the bottom. As you can see, we have only
  55 one (rather boring) input connected, and it is live. The other input is
  56 disconnected and thus shows only a test color. These correspond to pressing
  57 the 1 and 2 keys on the keyboard to activate preview, respectively—or you can
  58 left-click on them do achieve the same effect. (Right-clicking will bring up
  59 :ref:`the video card context menu <context-menu>`; see below.)
  60
  61 Similarly, we have a side-by-side view; it is composed of a big image of
  62 input 1 and a smaller one of input 2. (If you are unhappy which is which,
  63 you can switch the two inputs; again, see below.)
  64
  65 Finally, we have a static image. The one included with Nageru is rather
  66 bland and generic, but it works as a generic pause image when you don't
  67 really want anything on the screen.
  68
  69 For any given channel, you can see that it is active in the live or preview
  70 by looking at its border. If it's got a red border, as in the leftmost
  71 input, it's live (either on its own, or as part of the side-by-side view).
  72 Similarly, if it's got a green border, as in the second input (you can
  73 see it if you look closely; it's a somewhat lighter shade of green),
  74 it will be marked with green. On conflict, red (live) wins, since it is
  75 the most important piece of information.
  76
  77
  78 Transitions
  79 '''''''''''
  80
  81 Whenever you have a different channel pulled up on the preview from
  82 on the live display, you will see that the three buttons in the middle
  83 offer you various **transitions**. Selecting any of them (either by
  84 the displayed hotkey, or using the mouse) will *swap* the preview and
  85 live inputs, effectively making the preview live. If you use “cut”,
  86 this will happen nearly instantly; the two other options, zoom
  87 (only available with the side-by-side view) and fade (*not* available
  88 with the side-by-side view) take some time, as you can see in the live view.
  89
  90 A good operator knows to use the right transition at the right time,
  91 so that the end result does not distract from the actual message
  92 of the video. In particular, too frequent switching between sources
  93 will probably be perceived as disturbing.
  94
  95
  96 The audio strip
  97 '''''''''''''''
  98
  99 The look of the audio strip will vary significantly with what audio
 100 mode you are in; the default is the simple mode, but multichannel
 101 is much more powerful. Both modes, as well as the level meters on
 102 the right, are explained in detail in the section about :doc:`audio <audio>`.
 103
 104
 105 The menu bar
 106 ''''''''''''
 107
 108 The menu bar does not contain a lot of interesting information,
 109 but it does have a few elements that are useful for configuration.
 110 The video menu contains the following elements:
 111
 112   * **Begin new video segment:** Nageru is constantly recording
 113     your stream to disk in a near-lossless H.264 stream
 114     (you cannot turn it off, because experience shows you'd probably
 115     forget to turn it back on again in time for actual use);
 116     see :doc:`streaming` for more information. This option allows
 117     you to end the current file and begin a new one—the two files
 118     can be spliced back later for a 100% seamless result if you wish,
 119     so this is a lossless operation. It is typically useful
 120     to do this right before and after the event itself starts,
 121     so as to facilitate easier editing later.
 122
 123     You can achieve the same effect as this option by sending
 124     SIGHUP to the Nageru process.
 125
 126   * **Open frame analyzer:** See :doc:`analyzer` for more information.
 127
 128   * **Change x264 bitrate:** See :doc:`streaming` for more information.
 129
 130   * **HDMI/SDI output device, HDMI/SDI output resolution:** See :doc:`hdmisdi`
 131     for more information.
 132
 133   * **Exit:** Exits Nageru, obviously.
 134
 135 The audio menu is explained in the section on :doc:`audio <audio>`.
 136
 137 Finally, the menu bar also hosts the disk space meter. This shows
 138 how much disk you have left before Nageru will error out and die;
 139 it also tries to estimate how much real time this corresponds to,
 140 based on the last 30 seconds of recording.
 141
 142
 143 .. _context-menu:
 144
 145 The video card context menu
 146 '''''''''''''''''''''''''''
 147
 148 If you right-click on a channel that corresponds to a video input
 149 (ie., not the side-by-side view or static image), a simple context menu
 150 pops up:
 151
 152 .. image:: images/context-menu.png
 153
 154 The options presented are as follows:
 155
 156  * **Input source:** Connect this video input to a different physical card,
 157    taking effect immediately. The theme supports only two inputs
 158    at a time (you can :doc:`write your own <theme>` that support many
 159    more if you wish), but if you start Nageru with a higher value
 160    for the “--num-cards” option (aka -c), you can choose any of the
 161    available ones here. This option is also useful if you want to
 162    switch the two cards, since input 1 is bigger in side-by-side mode.
 163    (See also the “--map-signal” option, aka -m.)
 164
 165  * **Video input:** If a card supports multiple kinds of inputs
 166    (e.g. has both HDMI and analog inputs), you can select which one here.
 167
 168  * **Audio input:** Similar, just for audio. “Embedded” means
 169    an audio stream that is included in the HDMI or SDI signal.
 170
 171  * **Input mode:** Choose the video input mode to use. Note that the USB
 172    cards autodetect the mode, and you cannot override it even if you wanted to.
 173    For PCI cards, autodetection is not supported (even for the select few
 174    cards that can handle it in hardware), but a simple option (“Scan”)
 175    is available to try all modes in turn until a signal is received.
 176
 177  * **Input interpretation:** Choose how the Y'CbCr values in the input signal
 178    are to be interpreted. *Auto* will choose whatever is correct (as per the
 179    appropriate standards) for the current video mode, but occasionally,
 180    devices will get this wrong, and you will need to change this setting
 181    to get correct colors. You can use the *--input-ycbcr-interpretation=*
 182    command-line option to achieve the same effect.
 183
 184    See :doc:`analyzer` for figuring out if you need to change this.
 185    If unsure, leave it unchanged.
 186
 187  * **Use as audio source:** See the :doc:`audio <audio>` page for more
 188    information. For simple audio only; unavailable in multichannel mode.
 189
 190  * **Use as master clock:** The output stream needs exactly one stream
 191    as master clock. The frame rate and clocked will be locked exactly
 192    to it, so use the most important input here. A signal that keeps getting
 193    unplugged and replugged might not be the best candidate, although the
 194    PCI cards have fallback internal clocking when the signal is lost
 195    (the USB cards fall back to a strange mode of about 30.13 Hz).