# HG changeset patch
# User Goffi <goffi@goffi.org>
# Date 1708105566 -3600
# Node ID be89ab1cbca4053f6391c86527b6e00c43bc8704
# Parent  9218d4331bb20e7ca0550060bc208cd0e3d3f8bf
doc (cli/call): add ``tui`` output, and document options:

fix 428

diff -r 9218d4331bb2 -r be89ab1cbca4 doc/libervia-cli/call.rst
--- a/doc/libervia-cli/call.rst	Fri Feb 16 18:46:06 2024 +0100
+++ b/doc/libervia-cli/call.rst	Fri Feb 16 18:46:06 2024 +0100
@@ -21,8 +21,8 @@
 
 .. 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 @@
 
 - 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 @@
 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 @@
 
   $ 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 @@
 
    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.
+