.. _gerbera-ui:
.. index:: Web UI

Gerbera UI
==========


The Gerbera application provides a web browser user interface.  When you launch the Gerbera application the system
reports URL to the user interface.  The interface is available for you to maintain your media library in Gerbera.


Enable/Disable
~~~~~~~~~~~~~~

The Gerbera UI is enabled or disabled using the `config.xml` file.

.. code-block:: xml

   <config>
     <server>
       <ui enabled="no" show-tooltips="yes">
         <accounts enabled="no" session-timeout="30">
           <account user="" password=""/>
         </accounts>
       </ui>
     </server>
   </config>


When the Gerbera server starts successfully it reports the location of the web browser user interface

::

    2018-01-28 17:05:28    INFO: The Web UI can be reached by following this link: http://127.0.0.1:49152/

.. image:: _static/main-view-empty.png
   :alt: Gerbera Home Page with empty database
   :target: _static/main-view-empty.png


Login/Logout
~~~~~~~~~~~~

When the `accounts` section of the server configuration is enabled you can login to the UI with the associated user and password.

The UI supports entering the **username** and **password** in the top menu.

**Note** The system performs simple encoding of the password sent over HTTP to the Gerbera server.
Do not consider the UI a completely secure data transmission.

.. image:: _static/login-field-entry.png
   :alt: Login username and password
   :target: _static/login-field-entry.png

If you choose to have the `accounts` disabled, then the UI automatically logs in and loads a new user session.

The menu is activated with successful login and you can choose from the following menu options:

.. image:: _static/menubar.png
   :alt: Menubar
   :target: _static/menubar.png

The main view offers the same links to the sub pages as the menu. It also displays the statistics of the server's contents.

.. image:: _static/main-view.png
   :alt: Gerbera Home Page
   :target: _static/main-view.png

.. image:: _static/main-view_dark.png
   :alt: Gerbera Home Page in dark mode
   :target: _static/main-view_dark.png

* Home (Gerbera logo or server name)
    *Returns to the start page*
* Database // Browse indexed files
    *Browse the contents of the database without UPnP client*
* Search // Search indexed files
    *Search the contents of the database without UPnP client*
* Filesystem // Add some files
    *Show the filesystem tree of the server to add further contents*
* Clients // Show connected clients
    *Shows all connected clients with details*
* Config // Edit Configuration
    *View and update Gerbera settings*
* Documentation
    *Entry point to these pages*
* Report an Issue
    *Opens URL to Gerbera's GitHub Issues*

Features
~~~~~~~~

The Gerbera web UI has several features to maintain your media.

* Filesystem Items View
* Database Items View
* Search View
* Clients View
* Config View
* Item Operations
* Trail Operations
* Notifications


.. _filesystem-view:

Filesystem View
~~~~~~~~~~~~~~~

The filesystem view is accessible through the `File System` menu item. The filesystem view shows a folder tree
representing the local filesystem.  You can choose folders and items to add to your media library.

.. image:: _static/filesystem-view.png
   :alt: Filesystem view
   :target: _static/filesystem-view.png

You can add items to the database view, making them accessible to UPNP clients.  A successful addition of a filesystem
item results in that item being indexed and available in the Database view.

If the file is listed in "Database > PC Directory", then Gerbera already knows about it,
and clicking "add" does not do anything.


Database View
~~~~~~~~~~~~~

The database view is accessible through the `Database` menu item.  The view represents the (see :ref:`virtual layout <layout>`)
of your media library.  The database view displays a tree structure generated by the Gerbera `import` mechanism which either uses
a fixed builtin structure or javascript functions.  You can customize the database view structure by using the available scripts
or writing new ones (see :ref:`Scripting <scripting>`).

You can maintain the database by removing items and editing existing items to manually keep your media library up to date.  Be aware that
some changes may be overwritten by the autoscan imports.  On the other hand you can deliberately delete virtual items to allow proper reimport.

List View
---------
The list view offers full access to all modification commands.

.. image:: _static/database-view.png
   :alt: Database view
   :target: _static/database-view.png

Grid View
---------
The small grid view is designed to display many items on one screen without scrolling. To avoid critical clicks, delete and edit actions are hidden.

.. image:: _static/database-smallgrid-view_dark.png
   :alt: Database view with small grid in dark view
   :target: _static/database-smallgrid-view_dark.png

Large Grid View
----------------
The large grid view is designed to display previews on items like images. To avoid critical clicks, delete and edit actions are hidden.

.. image:: _static/database-largegrid-view.png
   :alt: Database view with large grid
   :target: _static/database-largegrid-view.png

Single Item View
----------------
The single item view is designed to display images. To avoid critical clicks, delete and edit actions are hidden.

.. image:: _static/database-single-view.png
   :alt: Database view with single item
   :target: _static/database-single-view.png


Search View
~~~~~~~~~~~

The search view allows searching the database with upnp search queries like a regular upnp client may do as well

.. image:: _static/search-view.png
   :alt: Search item
   :target: _static/search-view.png


Clients View
~~~~~~~~~~~~

The clients view is accessible through the `Clients` menu item.  The view contains details on all clients that contacted the server.
The second section contains statistics on the items played by the client groups.

.. image:: _static/clients-view_dark.png
   :alt: Clients view in dark view
   :target: _static/clients-view_dark.png


Config View
~~~~~~~~~~~

The config view is accessible through the `Config` menu item.  The view contains the current gerbera settings.

.. image:: _static/config-view.png
   :alt: Config view
   :target: _static/config-view.png

You can switch between three different levels of details. Only *expert* mode gives you all configuration values and modification options.
Be careful when changing values you do not fully understand. The server may fail to restart or become inaccessible.
The new values are stored in Gerbera database and overwrite values from ``config.xml``. If you have broken Gerbera you have to clear the database
or at least clear all entries from the table ``grb_config_value``.


Item Operations
~~~~~~~~~~~~~~~

The items list displays when a virtual item is selected in the `database view` tree.  The UI supports the following item
operations

* Download Item
* Edit Item
* Delete Item

.. image:: _static/item-operations.png
   :alt: Item operations
   :target: _static/item-operations.png

- Downloading the item retrieves the media directly from the Gerbera server.
- Deleting the item removes it from the virtual Database View.
- Editing the item updates the UPNP meta-data for the item. The edit icon is depending on

  - The item is created during import
  - An imported item was modified by the user
  - The item is created by the user

.. image:: _static/edit-item.png
   :width: 300
   :alt: Edit Item dialog
   :target: _static/edit-item.png

.. image:: _static/edit-item_dark.png
   :width: 300
   :alt: Edit Item dialog in dark mode
   :target: _static/edit-item_dark.png


.. image:: _static/edit-item-details.png
   :width: 500
   :alt: Edit Item dialog with details
   :target: _static/edit-item-details.png

.. image:: _static/edit-item-details_dark.png
   :width: 500
   :alt: Edit Item dialog with details in dark mode
   :target: _static/edit-item-details_dark.png

Item operations act upon existing database items.  You can create new custom items using the Gerbera Trail.


PC Directory
------------

When files are added to Gerbera, they first get added to "Database > PC Directory".
After that, *virtual items* are added in "Audio", "Photos" or "Video".
The virtual items reference the entries inside "PC Directory".

When deleting virtual items, only the virtual item itself is deleted.
When deleting an item inside the "PC Directory" folder, all
virtual items referencing this item are deleted.

After deleting an entry in the "PC Directory", Gerbera does not know about
the file anymore. It can be re-added in the "File System" view.

Autoscan configuration forces a reimport of these files after restarting the gerbera server.

.. _autoscan-edit:

Edit Autoscan
-------------

.. image:: _static/edit-autoscan.png
   :alt: Edit Autoscan dialog
   :target: _static/edit-autoscan.png

.. image:: _static/edit-autoscan-details.png
   :alt: Edit Autoscan dialog with details
   :target: _static/edit-autoscan-details.png

.. _tweak-edit:

Tweak Folder
------------

.. image:: _static/edit-tweak-details.png
   :alt: Edit Directory Tweaks dialog
   :target: _static/edit-tweak-details.png


Trail Operations
~~~~~~~~~~~~~~~~

The Gerbera Trail shows the current database/filesystem path and provides a number of operations.

Filesystem View
---------------

* Add Autoscan Directory/ Edit Autoscan Item
    * Configure folder as autoscan item
    * Add folder and subfolders to database
    * Triggers scan of the directory
* Scan Now
    * Triggers immediate scan of the selected directory
* Tweak Directory
    * Set special import properties for folder

.. image:: _static/trail-fs-operations.png
   :alt: Trail operations in Filesystem view
   :target: _static/trail-fs-operations.png

Database View
-------------

* Add Item
    * Create Container or Item in Virtual Layout
* Edit Item
    * Change Settings of Container
* Download as Zip
    * Download items of container in Zip (maybe large) file
    * Requires Zip support to be built into server
* Delete Container
    * Delete container and items of container
* Delete with References
    * Delete container, items and all references

.. image:: _static/trail-operations.png
   :alt: Trail operations
   :target: _static/trail-operations.png

* Export and Import changed Content
    * Select the database container in db view
    * Press `Export`
    * Copy the text to a file and save it to the disk of the server
    * After database update, enter the file path and press `Import`

.. image:: _static/content-export.png
   :alt: Export
   :target: _static/content-export.png

Config View
-----------

* Rescan Library
    * Trigger rescanning of all files
* Save Config
    * Save changed entries into database, a restart of gerbera may be necessary to activate the changes
* Clear Saved Config
    * Remove all config changes from the database

.. image:: _static/trail-config-operations.png
   :alt: Trail operations in Config view
   :target: _static/trail-config-operations.png


Notifications
~~~~~~~~~~~~~

Gerbera runs all activities asynchronously.  As you add content to the Gerbera database, the server scans and updates the
items based on the media tagging.  The Gerbera server reports busy activities to the UI in the form of 2 message bars.

* Status Message
* Task Message

The status message alerts upon operations to the server.  The server reports success and failure messages to the status
message bar at the bottom of the page.

.. image:: _static/toast-message.png
   :alt: Toast message
   :target: _static/toast-message.png


The task message bar is only visible when there is active processing on the Gerbera server.  The active tasks display in
the task message bar at the bottom of the page.

.. image:: _static/task-message_dark.png
   :alt: Task message in dark mode
   :target: _static/task-message_dark.png
