Mercurial > libervia-backend

annotate doc/libervia-cli/call.rst @ 4208:fd9e78b7a0cd

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc (cli/call): add outputs documentation: outputs are now documentated, and notably the new `gui` one. fix 427
author Goffi <goffi@goffi.org>
date Sun, 11 Feb 2024 23:22:18 +0100
parents 14523ee96538
children be89ab1cbca4
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
4144
14523ee96538 doc (cli): documentation for the new `call` command:
Goffi <goffi@goffi.org>
parents:
diff changeset
1 .. _libervia-cli_call:
14523ee96538 doc (cli): documentation for the new `call` command:
Goffi <goffi@goffi.org>
parents:
diff changeset
2
14523ee96538 doc (cli): documentation for the new `call` command:
Goffi <goffi@goffi.org>
parents:
diff changeset
3 ===============
14523ee96538 doc (cli): documentation for the new `call` command:
Goffi <goffi@goffi.org>
parents:
diff changeset
4 call: A/V Calls
14523ee96538 doc (cli): documentation for the new `call` command:
Goffi <goffi@goffi.org>
parents:
diff changeset
5 ===============
14523ee96538 doc (cli): documentation for the new `call` command:
Goffi <goffi@goffi.org>
parents:
diff changeset
6
14523ee96538 doc (cli): documentation for the new `call` command:
Goffi <goffi@goffi.org>
parents:
diff changeset
7 ``call`` lets you initiate or receive calls from the terminal.
14523ee96538 doc (cli): documentation for the new `call` command:
Goffi <goffi@goffi.org>
parents:
diff changeset
8
4208
fd9e78b7a0cd doc (cli/call): add outputs documentation:
Goffi <goffi@goffi.org>
parents: 4144
diff changeset
9
fd9e78b7a0cd doc (cli/call): add outputs documentation:
Goffi <goffi@goffi.org>
parents: 4144
diff changeset
10 Common UI
fd9e78b7a0cd doc (cli/call): add outputs documentation:
Goffi <goffi@goffi.org>
parents: 4144
diff changeset
11 =========
fd9e78b7a0cd doc (cli/call): add outputs documentation:
Goffi <goffi@goffi.org>
parents: 4144
diff changeset
12
fd9e78b7a0cd doc (cli/call): add outputs documentation:
Goffi <goffi@goffi.org>
parents: 4144
diff changeset
13 There are various UI available to display a call. By default, one will be automatically
fd9e78b7a0cd doc (cli/call): add outputs documentation:
Goffi <goffi@goffi.org>
parents: 4144
diff changeset
14 selected according to platform. To select an UI, use the ``--output, -O`` option, with one
fd9e78b7a0cd doc (cli/call): add outputs documentation:
Goffi <goffi@goffi.org>
parents: 4144
diff changeset
15 of the following value:
fd9e78b7a0cd doc (cli/call): add outputs documentation:
Goffi <goffi@goffi.org>
parents: 4144
diff changeset
16
fd9e78b7a0cd doc (cli/call): add outputs documentation:
Goffi <goffi@goffi.org>
parents: 4144
diff changeset
17 default
fd9e78b7a0cd doc (cli/call): add outputs documentation:
Goffi <goffi@goffi.org>
parents: 4144
diff changeset
18 -------
fd9e78b7a0cd doc (cli/call): add outputs documentation:
Goffi <goffi@goffi.org>
parents: 4144
diff changeset
19
fd9e78b7a0cd doc (cli/call): add outputs documentation:
Goffi <goffi@goffi.org>
parents: 4144
diff changeset
20 The default value make a guess on the best output to use on the current platform.
fd9e78b7a0cd doc (cli/call): add outputs documentation:
Goffi <goffi@goffi.org>
parents: 4144
diff changeset
21
fd9e78b7a0cd doc (cli/call): add outputs documentation:
Goffi <goffi@goffi.org>
parents: 4144
diff changeset
22 .. note::
fd9e78b7a0cd doc (cli/call): add outputs documentation:
Goffi <goffi@goffi.org>
parents: 4144
diff changeset
23
fd9e78b7a0cd doc (cli/call): add outputs documentation:
Goffi <goffi@goffi.org>
parents: 4144
diff changeset
24 For the moment, ``default`` always select ``simple`` output.
fd9e78b7a0cd doc (cli/call): add outputs documentation:
Goffi <goffi@goffi.org>
parents: 4144
diff changeset
25
fd9e78b7a0cd doc (cli/call): add outputs documentation:
Goffi <goffi@goffi.org>
parents: 4144
diff changeset
26
fd9e78b7a0cd doc (cli/call): add outputs documentation:
Goffi <goffi@goffi.org>
parents: 4144
diff changeset
27 simple
fd9e78b7a0cd doc (cli/call): add outputs documentation:
Goffi <goffi@goffi.org>
parents: 4144
diff changeset
28 ------
fd9e78b7a0cd doc (cli/call): add outputs documentation:
Goffi <goffi@goffi.org>
parents: 4144
diff changeset
29
fd9e78b7a0cd doc (cli/call): add outputs documentation:
Goffi <goffi@goffi.org>
parents: 4144
diff changeset
30 During a call, a simple graphical window will be created, displaying your correspondent's
fd9e78b7a0cd doc (cli/call): add outputs documentation:
Goffi <goffi@goffi.org>
parents: 4144
diff changeset
31 video, with your own video feed in the bottom right corner.
4144
14523ee96538 doc (cli): documentation for the new `call` command:
Goffi <goffi@goffi.org>
parents:
diff changeset
32
14523ee96538 doc (cli): documentation for the new `call` command:
Goffi <goffi@goffi.org>
parents:
diff changeset
33 With the UI present (by default), there are 3 buttons:
14523ee96538 doc (cli): documentation for the new `call` command:
Goffi <goffi@goffi.org>
parents:
diff changeset
34
14523ee96538 doc (cli): documentation for the new `call` command:
Goffi <goffi@goffi.org>
parents:
diff changeset
35 - one to (un)mute video with the ``v`` key shortcut
14523ee96538 doc (cli): documentation for the new `call` command:
Goffi <goffi@goffi.org>
parents:
diff changeset
36 - one to (un)mute audio with the ``m`` key shortcut
14523ee96538 doc (cli): documentation for the new `call` command:
Goffi <goffi@goffi.org>
parents:
diff changeset
37 - one to hang up with the ``h`` key shortcut. ``Ctrl+c`` will have the same effect.
14523ee96538 doc (cli): documentation for the new `call` command:
Goffi <goffi@goffi.org>
parents:
diff changeset
38
4208
fd9e78b7a0cd doc (cli/call): add outputs documentation:
Goffi <goffi@goffi.org>
parents: 4144
diff changeset
39 gui
fd9e78b7a0cd doc (cli/call): add outputs documentation:
Goffi <goffi@goffi.org>
parents: 4144
diff changeset
40 ---
fd9e78b7a0cd doc (cli/call): add outputs documentation:
Goffi <goffi@goffi.org>
parents: 4144
diff changeset
41
fd9e78b7a0cd doc (cli/call): add outputs documentation:
Goffi <goffi@goffi.org>
parents: 4144
diff changeset
42 The ``gui`` option enables a full graphical user interface for handling calls, akin to
fd9e78b7a0cd doc (cli/call): add outputs documentation:
Goffi <goffi@goffi.org>
parents: 4144
diff changeset
43 other frontends (web, desktop). This GUI provides a comprehensive and interactive
fd9e78b7a0cd doc (cli/call): add outputs documentation:
Goffi <goffi@goffi.org>
parents: 4144
diff changeset
44 experience for call management directly from your CLI environment, ensuring quick access
fd9e78b7a0cd doc (cli/call): add outputs documentation:
Goffi <goffi@goffi.org>
parents: 4144
diff changeset
45 to the call feature from the CLI frontend.
fd9e78b7a0cd doc (cli/call): add outputs documentation:
Goffi <goffi@goffi.org>
parents: 4144
diff changeset
46
fd9e78b7a0cd doc (cli/call): add outputs documentation:
Goffi <goffi@goffi.org>
parents: 4144
diff changeset
47 This interface is accessible if your system supports X11 or Wayland and requires ``PyQt``
fd9e78b7a0cd doc (cli/call): add outputs documentation:
Goffi <goffi@goffi.org>
parents: 4144
diff changeset
48 v6 or higher. Here's how to navigate and use the GUI:
fd9e78b7a0cd doc (cli/call): add outputs documentation:
Goffi <goffi@goffi.org>
parents: 4144
diff changeset
49
fd9e78b7a0cd doc (cli/call): add outputs documentation:
Goffi <goffi@goffi.org>
parents: 4144
diff changeset
50 Call Interface
fd9e78b7a0cd doc (cli/call): add outputs documentation:
Goffi <goffi@goffi.org>
parents: 4144
diff changeset
51 ^^^^^^^^^^^^^^
fd9e78b7a0cd doc (cli/call): add outputs documentation:
Goffi <goffi@goffi.org>
parents: 4144
diff changeset
52
fd9e78b7a0cd doc (cli/call): add outputs documentation:
Goffi <goffi@goffi.org>
parents: 4144
diff changeset
53 The call interface is made with:
fd9e78b7a0cd doc (cli/call): add outputs documentation:
Goffi <goffi@goffi.org>
parents: 4144
diff changeset
54
fd9e78b7a0cd doc (cli/call): add outputs documentation:
Goffi <goffi@goffi.org>
parents: 4144
diff changeset
55 - **Video Feeds**: The main window displays the other party's video, with your video in
fd9e78b7a0cd doc (cli/call): add outputs documentation:
Goffi <goffi@goffi.org>
parents: 4144
diff changeset
56 the bottom right.
fd9e78b7a0cd doc (cli/call): add outputs documentation:
Goffi <goffi@goffi.org>
parents: 4144
diff changeset
57 - **Fullscreen Mode**: A fullscreen toggle button is located at the top right of the
fd9e78b7a0cd doc (cli/call): add outputs documentation:
Goffi <goffi@goffi.org>
parents: 4144
diff changeset
58 window.
fd9e78b7a0cd doc (cli/call): add outputs documentation:
Goffi <goffi@goffi.org>
parents: 4144
diff changeset
59 - **Controls**: The following buttons are available at the bottom of your screen:
fd9e78b7a0cd doc (cli/call): add outputs documentation:
Goffi <goffi@goffi.org>
parents: 4144
diff changeset
60
fd9e78b7a0cd doc (cli/call): add outputs documentation:
Goffi <goffi@goffi.org>
parents: 4144
diff changeset
61 - Mute/Unmute video or audio with respective buttons.
fd9e78b7a0cd doc (cli/call): add outputs documentation:
Goffi <goffi@goffi.org>
parents: 4144
diff changeset
62 - Desktop Sharing.
fd9e78b7a0cd doc (cli/call): add outputs documentation:
Goffi <goffi@goffi.org>
parents: 4144
diff changeset
63 - Hang up.
fd9e78b7a0cd doc (cli/call): add outputs documentation:
Goffi <goffi@goffi.org>
parents: 4144
diff changeset
64
fd9e78b7a0cd doc (cli/call): add outputs documentation:
Goffi <goffi@goffi.org>
parents: 4144
diff changeset
65 Desktop Sharing
fd9e78b7a0cd doc (cli/call): add outputs documentation:
Goffi <goffi@goffi.org>
parents: 4144
diff changeset
66 ^^^^^^^^^^^^^^^
fd9e78b7a0cd doc (cli/call): add outputs documentation:
Goffi <goffi@goffi.org>
parents: 4144
diff changeset
67 To share your desktop, you need to be in a supported environment (X11 or Wayland).
fd9e78b7a0cd doc (cli/call): add outputs documentation:
Goffi <goffi@goffi.org>
parents: 4144
diff changeset
68
fd9e78b7a0cd doc (cli/call): add outputs documentation:
Goffi <goffi@goffi.org>
parents: 4144
diff changeset
69 For Wayland, you'll need to have the ``xdg-desktop-portal`` package installed, along with
fd9e78b7a0cd doc (cli/call): add outputs documentation:
Goffi <goffi@goffi.org>
parents: 4144
diff changeset
70 its sibling desktop environment-specific package (e.g., ``xdg-desktop-portal-gtk`` or
fd9e78b7a0cd doc (cli/call): add outputs documentation:
Goffi <goffi@goffi.org>
parents: 4144
diff changeset
71 ``xdg-desktop-portal-kde``).
fd9e78b7a0cd doc (cli/call): add outputs documentation:
Goffi <goffi@goffi.org>
parents: 4144
diff changeset
72
fd9e78b7a0cd doc (cli/call): add outputs documentation:
Goffi <goffi@goffi.org>
parents: 4144
diff changeset
73 Once you've clicked on the desktop sharing button, you'll have to select what you want to
fd9e78b7a0cd doc (cli/call): add outputs documentation:
Goffi <goffi@goffi.org>
parents: 4144
diff changeset
74 share. It can be your entire screen or a specific application window. On X11, a simple
fd9e78b7a0cd doc (cli/call): add outputs documentation:
Goffi <goffi@goffi.org>
parents: 4144
diff changeset
75 dialog will appear, while for Wayland, a dialog provided by your environment will ask you
fd9e78b7a0cd doc (cli/call): add outputs documentation:
Goffi <goffi@goffi.org>
parents: 4144
diff changeset
76 to select what you want to share.
fd9e78b7a0cd doc (cli/call): add outputs documentation:
Goffi <goffi@goffi.org>
parents: 4144
diff changeset
77
fd9e78b7a0cd doc (cli/call): add outputs documentation:
Goffi <goffi@goffi.org>
parents: 4144
diff changeset
78 example
fd9e78b7a0cd doc (cli/call): add outputs documentation:
Goffi <goffi@goffi.org>
parents: 4144
diff changeset
79 -------
fd9e78b7a0cd doc (cli/call): add outputs documentation:
Goffi <goffi@goffi.org>
parents: 4144
diff changeset
80
fd9e78b7a0cd doc (cli/call): add outputs documentation:
Goffi <goffi@goffi.org>
parents: 4144
diff changeset
81 Pierre wants to call Louise with a GUI::
fd9e78b7a0cd doc (cli/call): add outputs documentation:
Goffi <goffi@goffi.org>
parents: 4144
diff changeset
82
fd9e78b7a0cd doc (cli/call): add outputs documentation:
Goffi <goffi@goffi.org>
parents: 4144
diff changeset
83 $ li call make louise@example.org -O gui
fd9e78b7a0cd doc (cli/call): add outputs documentation:
Goffi <goffi@goffi.org>
parents: 4144
diff changeset
84
4144
14523ee96538 doc (cli): documentation for the new `call` command:
Goffi <goffi@goffi.org>
parents:
diff changeset
85 make
14523ee96538 doc (cli): documentation for the new `call` command:
Goffi <goffi@goffi.org>
parents:
diff changeset
86 ====
14523ee96538 doc (cli): documentation for the new `call` command:
Goffi <goffi@goffi.org>
parents:
diff changeset
87
14523ee96538 doc (cli): documentation for the new `call` command:
Goffi <goffi@goffi.org>
parents:
diff changeset
88 Make a call. The primary argument is the JID of the entity you wish to call.
14523ee96538 doc (cli): documentation for the new `call` command:
Goffi <goffi@goffi.org>
parents:
diff changeset
89
14523ee96538 doc (cli): documentation for the new `call` command:
Goffi <goffi@goffi.org>
parents:
diff changeset
90 example
14523ee96538 doc (cli): documentation for the new `call` command:
Goffi <goffi@goffi.org>
parents:
diff changeset
91 -------
14523ee96538 doc (cli): documentation for the new `call` command:
Goffi <goffi@goffi.org>
parents:
diff changeset
92
14523ee96538 doc (cli): documentation for the new `call` command:
Goffi <goffi@goffi.org>
parents:
diff changeset
93 Pierre wants to call Louise::
14523ee96538 doc (cli): documentation for the new `call` command:
Goffi <goffi@goffi.org>
parents:
diff changeset
94
14523ee96538 doc (cli): documentation for the new `call` command:
Goffi <goffi@goffi.org>
parents:
diff changeset
95 $ li call make louise@example.org
14523ee96538 doc (cli): documentation for the new `call` command:
Goffi <goffi@goffi.org>
parents:
diff changeset
96
14523ee96538 doc (cli): documentation for the new `call` command:
Goffi <goffi@goffi.org>
parents:
diff changeset
97 receive
14523ee96538 doc (cli): documentation for the new `call` command:
Goffi <goffi@goffi.org>
parents:
diff changeset
98 =======
14523ee96538 doc (cli): documentation for the new `call` command:
Goffi <goffi@goffi.org>
parents:
diff changeset
99
14523ee96538 doc (cli): documentation for the new `call` command:
Goffi <goffi@goffi.org>
parents:
diff changeset
100 Receive a call. By default, you'll see a confirmation prompt when someone is calling; you
14523ee96538 doc (cli): documentation for the new `call` command:
Goffi <goffi@goffi.org>
parents:
diff changeset
101 can then use ``y`` to accept the call or ``n`` to reject it. Use the ``-a JID,
14523ee96538 doc (cli): documentation for the new `call` command:
Goffi <goffi@goffi.org>
parents:
diff changeset
102 --auto-accept JID`` option to automatically accept calls from a specific entity (can be
14523ee96538 doc (cli): documentation for the new `call` command:
Goffi <goffi@goffi.org>
parents:
diff changeset
103 used multiple times), or the ``--auto-accept-all`` to accept any incoming call.
14523ee96538 doc (cli): documentation for the new `call` command:
Goffi <goffi@goffi.org>
parents:
diff changeset
104
14523ee96538 doc (cli): documentation for the new `call` command:
Goffi <goffi@goffi.org>
parents:
diff changeset
105 .. note::
14523ee96538 doc (cli): documentation for the new `call` command:
Goffi <goffi@goffi.org>
parents:
diff changeset
106
14523ee96538 doc (cli): documentation for the new `call` command:
Goffi <goffi@goffi.org>
parents:
diff changeset
107 Accepting a call automatically activates your webcam and microphone, and shares your IP
14523ee96538 doc (cli): documentation for the new `call` command:
Goffi <goffi@goffi.org>
parents:
diff changeset
108 address with the caller. Therefore, using ``--auto-accept-all`` is a security risk. Only
14523ee96538 doc (cli): documentation for the new `call` command:
Goffi <goffi@goffi.org>
parents:
diff changeset
109 use it if you have a very good reason to do so.
14523ee96538 doc (cli): documentation for the new `call` command:
Goffi <goffi@goffi.org>
parents:
diff changeset
110
14523ee96538 doc (cli): documentation for the new `call` command:
Goffi <goffi@goffi.org>
parents:
diff changeset
111
14523ee96538 doc (cli): documentation for the new `call` command:
Goffi <goffi@goffi.org>
parents:
diff changeset
112 examples
14523ee96538 doc (cli): documentation for the new `call` command:
Goffi <goffi@goffi.org>
parents:
diff changeset
113 --------
14523ee96538 doc (cli): documentation for the new `call` command:
Goffi <goffi@goffi.org>
parents:
diff changeset
114
14523ee96538 doc (cli): documentation for the new `call` command:
Goffi <goffi@goffi.org>
parents:
diff changeset
115 Louise is expecting a call. When she receives one, a prompt will ask her to confirm and
14523ee96538 doc (cli): documentation for the new `call` command:
Goffi <goffi@goffi.org>
parents:
diff changeset
116 start it::
14523ee96538 doc (cli): documentation for the new `call` command:
Goffi <goffi@goffi.org>
parents:
diff changeset
117
14523ee96538 doc (cli): documentation for the new `call` command:
Goffi <goffi@goffi.org>
parents:
diff changeset
118 $ li call receive
14523ee96538 doc (cli): documentation for the new `call` command:
Goffi <goffi@goffi.org>
parents:
diff changeset
119
14523ee96538 doc (cli): documentation for the new `call` command:
Goffi <goffi@goffi.org>
parents:
diff changeset
120 Piotr has a device with a webcam and microphone for observing wildlife. He set the device
14523ee96538 doc (cli): documentation for the new `call` command:
Goffi <goffi@goffi.org>
parents:
diff changeset
121 to automatically accept his calls::
14523ee96538 doc (cli): documentation for the new `call` command:
Goffi <goffi@goffi.org>
parents:
diff changeset
122
14523ee96538 doc (cli): documentation for the new `call` command:
Goffi <goffi@goffi.org>
parents:
diff changeset
123 $ li call receive -a piotr@example.net
14523ee96538 doc (cli): documentation for the new `call` command:
Goffi <goffi@goffi.org>
parents:
diff changeset
124
14523ee96538 doc (cli): documentation for the new `call` command:
Goffi <goffi@goffi.org>
parents:
diff changeset
125 .. note::
14523ee96538 doc (cli): documentation for the new `call` command:
Goffi <goffi@goffi.org>
parents:
diff changeset
126
14523ee96538 doc (cli): documentation for the new `call` command:
Goffi <goffi@goffi.org>
parents:
diff changeset
127 Libervia CLI will exit once the first accepted call is terminated. Looping in a shell
14523ee96538 doc (cli): documentation for the new `call` command:
Goffi <goffi@goffi.org>
parents:
diff changeset
128 may be necessary to call the same device multiple times.
14523ee96538 doc (cli): documentation for the new `call` command:
Goffi <goffi@goffi.org>
parents:
diff changeset
129
14523ee96538 doc (cli): documentation for the new `call` command:
Goffi <goffi@goffi.org>
parents:
diff changeset
130 .. note::
14523ee96538 doc (cli): documentation for the new `call` command:
Goffi <goffi@goffi.org>
parents:
diff changeset
131
14523ee96538 doc (cli): documentation for the new `call` command:
Goffi <goffi@goffi.org>
parents:
diff changeset
132 Since using auto-accept mode activates the webcam and microphone, consider the privacy
14523ee96538 doc (cli): documentation for the new `call` command:
Goffi <goffi@goffi.org>
parents:
diff changeset
133 implications and ensure that no one will be filmed or recorded without their consent.