Lumiera User Manual
===================

.There is no »User Manual« -- yet
The plan is to create the manual and tutorials later in a collaborative way. +
This work is postponed until the software is actually usable.

.What is »Lumiera«?
Lumiera is a Free/Open Source project to build a Non-Linear Video Editing (NLE)
and compositing application for GNU/Linux.
Its primary focus is professional editing, quality, usability and flexibility.
On the one hand, it must meet the rigours of a professional
film and video production environment; on the other hand, it must
be flexible enough to satisfy the needs of more modest single-user
equipment.

These ambitious goals have led us to a complex and flexible internal structure,
over the course of the last years. Many elements still need to be connected and
integrated, so that the functionality becomes visible and can be explored by users.
And we are a small team. Nevertheless, please be assured that work on the project is ongoing.

- Look at the https://git.lumiera.org/[Git repositories] to see current activity
- Visit the http://Lumiera.org/documentation/user/intro/intro.html[»Lumiera from Outer Space«]
  page at the https://Lumiera.org[Lumiera.org] website to read more about the Design and Vision.


UI Experiments
--------------
While most of the work is focused at the inner workings of the Render Engine
(as of Nov.2025), the User Interface has been upgraded to GTK-3 and outfitted with
some experimental connection channels, to test interplay with the application core.

After launching the `lumiera` application, a main window will be displayed.

image:{imgg}/lumiera20250823.png["Lumiera GTK UI / Screenshot 2025-08",width=650, link="{imgg}/lumiera20250823.png"]


Video Output
~~~~~~~~~~~~
The [green]#▶#_play_ / [blue]#⏸#_pause_ / [red]#⏹#_stop_ buttons will activate some video output demo code,
which is actually quite old -- it was extracted 2009 from the https://en.wikipedia.org/wiki/Kino_(software)[Kino]
video editing software and used for various experiments since then. In its current shape,
this dummy playback ensures that Lumiera is properly built and linked to use the
https://en.wikipedia.org/wiki/X_video_extension[XVideo] standard with the help of the X11 XServer.
This _archaic_ standard from 1991 presumably was the first widely available and vendor-neutral interface
for passing raw video frames to the GPU, which then scales and integrates them into the desktop display.

The video frames for this demo _are not generated by the Lumiera Render Engine_ -- and
thus this code is largely obsolete; maybe it will continue to live somewhere as a fallback
for systems without proper support of OpenGL?

The UI-Bus
~~~~~~~~~~
Instead of accessing a shared data model, the Lumiera UI is connected to the core
through an _asynchronous messaging channel,_ to dispatch command instructions into the
session and to push responses up into the UI. There is a demo to verify this setup
by pushing info and error messages into the »Info Box«

- In the ``Help'' menu, there is the entry `Help > Self Tests'
- The tab https://issues.lumiera.org/ticket/1099[#1099] in this non-modal dialog box
  allows to push notification messages into the UI-Bus...
   
  * enter some text into the input widget at the top
  * send a display message with this text at Info / Warn / or Error level
  * or push the ``mark'' button to send a `mark` message, selected from the
    drop-down

Timeline Display
~~~~~~~~~~~~~~~~
The second tab in this ``Test and Diagnostics'' dialog box (`Help > Self Tests')
allows to _Populate the Timeline Display_ with a structure corresponding to session content.
This structure is sent over the UI-Bus as a ``Diff Message'' -- basically the core can notify
the UI about changes in structured content elements, which both sides know, without ever sharing
a common data representation.

This demo engages this mechanism to _populate_ an previously empty Timeline with structured content;
the actual content is hard-wired for this test, offering two flavours (``Sequence 1'' and ``Sequence 2'').

Sequence 1::
  A single Track, with two Clips, which can be clicked and dragged; they have a fixed given length,
  but no further content.

Sequence 2::
  A complex arrangement of nested tracks, some of which are expanded, and some have overview rulers.
  Note that it is possible to scroll vertically, while the top-level overview rulers remain always
  visible and pinned on top. Note furthermore that the _Track-Head display_ in the left pane scrolles
  alongside, and remains in sync with the main content pane. Tracks can not yet be expanded / collapsed

The Button ``move elements'' is part of an ongoing experiment and currently disabled.

NOTE: the panes can be undocked and re-arranged, but retain their identity, so that
      they can be addressed via UI-Bus without knowing where they are actually located
      in the UI. [red]#And there are various known problems related to those docks...#
