call: A/V Calls

call lets you initiate or receive calls from the terminal.

Common UI

There are various UI available to display a call. By default, one will be automatically selected according to platform. To select an UI, use the --output, -O option, with one of the following value:

default

The default value make a guess on the best output to use on the current platform.

Note

For the moment, default tries gui first, and fallbacks to simple if it’s not possible.

simple

During a call, a simple graphical window will be created, displaying your correspondent’s video, with your own video feed in the bottom right corner.

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 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.

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

The gui option enables a full graphical user interface for handling calls, akin to other frontends (web, desktop). This GUI provides a comprehensive and interactive experience for call management directly from your CLI environment, ensuring quick access 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

The call interface is made with:

  • Video Feeds: The main window displays the other party’s video, with your video in the bottom right.

  • Fullscreen Mode: A fullscreen toggle button is located at the top right of the window.

  • Controls: The following buttons are available at the bottom of your screen:

    • Mute/Unmute video or audio with respective buttons.

    • Desktop Sharing.

    • Hang up.

Desktop Sharing

To share your desktop, you need to be in a supported environment (X11 or Wayland).

For Wayland, you’ll need to have the xdg-desktop-portal package installed, along with its sibling desktop environment-specific package (e.g., xdg-desktop-portal-gtk or xdg-desktop-portal-kde).

Once you’ve clicked on the desktop sharing button, you’ll have to select what you want to share. It can be your entire screen or a specific application window. On X11, a simple dialog will appear, while for Wayland, a dialog provided by your environment will ask you to select what you want to share.

no_ui

Sometimes you don’t want Libervia to create a user interface. This can be because you want to pipe the stream to other software or use a custom GStreamer pipeline.

With no_ui output, no user interface will be created. If you don’t specify audio or video pipeline options (see below), automatic sinks will be used, except when stdout is redirected (e.g., via a pipe), in which case playback is not shown at all.

The following output options can be used:

  • audio=AUDIO_PIPELINE: Set a GStreamer pipeline description for audio.

  • video=VIDEO_PIPELINE: Set a GStreamer pipeline description for video.

Custom Pipelines

Custom GStreamer pipelines can be used as sources for outgoing streams using -V, --video VIDEO and/or -A, --audio AUDIO. You can use GStreamer pipeline descriptions (the same as with the gst-launch command).

For sinks (to handle incoming streams), use the no_ui output with the audio and video options as explained in Call Interface.

Stdin/Stdout redirection

You can redirect stdin and/or stdout (e.g., using pipes or file redirection).

For stdin, the stream format will be autodetected, and if it can be read, it will be sent to your peer.

For stdout, the incoming stream will be copied there in WebM format. This can be used with file redirection to record a call.

Note

If you record a call, be sure you have the consent of your peer.

examples

Pierre wants to call Louise with a GUI:

$ li call make louise@example.org -O gui

Louise is expecting Pierre’s call and will use TUI with the block renderer to display it:

$ li call receive -a pierre@example.net -O tui --oo renderer=block

Louise wants to show a movie trailer to Pierre:

$ li call make pierre@example.net < ~/blender/Agent\ 327\ -\ Operation\ Barbershop.webm

make

Make a call. The primary argument is the JID of the entity you wish to call.

example

Pierre wants to call Louise:

$ li call make louise@example.org

receive

Receive a call. By default, you’ll see a confirmation prompt when someone is calling; you can then use y to accept the call or n to reject it. Use the -a JID, --auto-accept JID option to automatically accept calls from a specific entity (can be used multiple times), or the --auto-accept-all to accept any incoming call.

Note

Accepting a call automatically activates your webcam and microphone, and shares your IP address with the caller. Therefore, using --auto-accept-all is a security risk. Only use it if you have a very good reason to do so.

examples

Louise is expecting a call. When she receives one, a prompt will ask her to confirm and start it:

$ li call receive

Piotr has a device with a webcam and microphone for observing wildlife. He set the device to automatically accept his calls:

$ li call receive -a piotr@example.net

Note

Libervia CLI will exit once the first accepted call is terminated. Looping in a shell may be necessary to call the same device multiple times.

Note

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.