doc (cli/call): add `tui` output, and document options:

fix 428

doc/libervia-cli/call.rst

@@ -21,8 +21,8 @@ The default value make a guess on the best output to use on the current platform
 
 .. note::
 
-   For the moment, ``default`` always select ``simple`` output.
-
+   For the moment, ``default`` tries ``gui`` first, and fallbacks to ``simple`` if it's
+   not possible.
 
 simple
 ------
@@ -34,7 +34,55 @@ With the UI present (by default), there are 3 buttons:
 
 - one to (un)mute video with the ``v`` key shortcut
 - one to (un)mute audio with the ``m`` key shortcut
-- one to hang up with the ``h`` key shortcut. ``Ctrl+c`` will have the same effect.
+- one to hang up with the ``h`` key shortcut. ``Ctrl+c`` will also have the same effect.
+
+The following output options can be used:
+
+- **split**: use 2 windows, one for local feedback and the other for remote video, instead of
+  the default single one with local feedback use with Picture-in-Picture.
+
+- **size=widthxheight**: specify the size of the destination windows (when **split** is
+  not used). By default, 1280x720 is used.
+
+tui
+---
+
+A Text User Interface can be used; it will then output the video streams directly in the
+terminal.
+
+To make it work, you need to have a terminal compatible with at least one image
+standard (Kitty, iTerm2, or "block", which uses Unicode half blocks and 24-bit color
+escape codes).
+
+The control buttons are the same as for the ``simple`` output.
+
+.. note::
+
+   `term-image`_ is used to display images in the terminal. Check its documentation to see
+   if your terminal is compatible with it (or just try). You can check compatibility at
+   https://term-image.readthedocs.io/en/stable/start/installation.html#supported-terminal-emulators
+
+.. note::
+
+   You need to have installed the ``term-image`` package to make it work. It is the case
+   if you have used `[TUI]` or `[all]` dependencies during Libervia installation.
+
+.. _term-image: https://term-image.readthedocs.io/en/stable/
+
+
+The following output options can be used:
+
+- **renderer=RENDERER**: Use a specific renderer. It is case-insensitive and RENDERER can
+  be one of:
+
+  - **auto** (default): selects the best possible renderer automatically
+  - **block**: uses Unicode half blocks. This option may be less resource-intensive than
+    other options (but not necessarily, depending on the implementation).
+  - **iterm2**: iTerm2 image protocol
+- **fps**: frames per second to render. It defaults to 25, you can try lower values if
+  your machine struggles to show images.
+- **size**: same as for ``simple`` output, except the default here is 640x380 for
+  performance reasons.
 
 gui
 ---
@@ -47,6 +95,11 @@ to the call feature from the CLI frontend.
 This interface is accessible if your system supports X11 or Wayland and requires ``PyQt``
 v6 or higher. Here's how to navigate and use the GUI:
 
+.. note::
+
+   You need to have installed the ``PyQt6`` package to make it work. It is the case if you
+   have used `[GUI]` or `[all]` dependencies during Libervia installation.
+
 Call Interface
 ^^^^^^^^^^^^^^
 
@@ -82,6 +135,10 @@ Pierre wants to call Louise with a GUI::
 
   $ li call make louise@example.org -O gui
 
+Louise is expecting Pierre call, and will use TUI with the ``block`` renderer to show it::
+
+  $ li call receive -a pierre@example.net -O tui --oo renderer=block
+
 make
 ====
 
@@ -131,3 +188,4 @@ to automatically accept his calls::
 
    Since using auto-accept mode activates the webcam and microphone, consider the privacy
    implications and ensure that no one will be filmed or recorded without their consent.
+