.. _org.freedesktop.impl.portal.ScreenCast:

======================================
ScreenCast
======================================

-----------
Description
-----------

.. _org.freedesktop.impl.portal.ScreenCast Description:

Screen cast portal backend interface

The Screen cast portal allows to create screen cast sessions.

This documentation describes version 5 of this interface.



.. _org.freedesktop.impl.portal.ScreenCast Properties:

----------
Properties
----------

.. _org.freedesktop.impl.portal.ScreenCast:AvailableSourceTypes:

org.freedesktop.impl.portal.ScreenCast:AvailableSourceTypes
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

    AvailableSourceTypes readable u


A bitmask of available source types. Currently defined types are:

- ``1``: MONITOR: Share existing monitors
- ``2``: WINDOW: Share application windows
- ``4``: VIRTUAL: Extend with new virtual monitor




.. _org.freedesktop.impl.portal.ScreenCast:AvailableCursorModes:

org.freedesktop.impl.portal.ScreenCast:AvailableCursorModes
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

    AvailableCursorModes readable u


Available cursor mode values:

- ``1``: Hidden. The cursor is not part of the screen cast stream.
- ``2``: Embedded: The cursor is embedded as part of the stream buffers.
- ``4``: Metadata: The cursor is not part of the screen cast stream, but sent as PipeWire stream metadata.




.. _org.freedesktop.impl.portal.ScreenCast:version:

org.freedesktop.impl.portal.ScreenCast:version
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

    version readable u




.. _org.freedesktop.impl.portal.ScreenCast Methods:

-------
Methods
-------

.. _org.freedesktop.impl.portal.ScreenCast.CreateSession:

org.freedesktop.impl.portal.ScreenCast.CreateSession
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

    CreateSession (
      IN handle o,
      IN session_handle o,
      IN app_id s,
      IN options a{sv},
      OUT response u,
      OUT results a{sv}
    )



Create a screen cast session.

The following results get returned in the ``results`` vardict:

* ``session_id`` (``s``)

  The session id. A string representing the created screen cast session.



handle
  Object path for the :ref:`org.freedesktop.impl.portal.Request` object representing this call

session_handle
  Object path for the :ref:`org.freedesktop.impl.portal.Session` object representing the session being created

app_id
  App id of the application

options
  Vardict with optional further information

response
  Numeric response

results
  Vardict with the results of the call



.. _org.freedesktop.impl.portal.ScreenCast.SelectSources:

org.freedesktop.impl.portal.ScreenCast.SelectSources
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

    SelectSources (
      IN handle o,
      IN session_handle o,
      IN app_id s,
      IN options a{sv},
      OUT response u,
      OUT results a{sv}
    )



Configure what the screen cast session should record.

Supported keys in the ``options`` vardict include:

* ``types`` (``u``)

  Bitmask of what type of content to record. Default is MONITOR.

* ``multiple`` (``b``)

  Whether to allow selecting multiple sources. Default is no.

* ``cursor_mode`` (``u``)

  Determines how the cursor will be drawn in the screen cast stream. It must be
  one of the cursor modes advertised in
  #org.freedesktop.portal.impl.ScreenCast.AvailableCursorModes. Setting a cursor
  mode not advertised will cause the screen cast session to be closed. The default
  cursor mode is 'Hidden'.

  This option was added in version 2 of this interface.

* ``restore_data`` (``(suv)``)

  The data to restore from a previous session.

  If the stored session cannot be restored, this value is ignored
  and the user will be prompted normally. This may happen when, for
  example, the session contains a monitor or a window that is not
  available anymore, or when the stored permissions are withdrawn.

  The restore data is composed of the vendor name (e.g. "GNOME" or
  "KDE"), the version of the implementation-specific private data,
  and the implementation-specific private data itself.

  This option was added in version 4 of this interface.

* ``persist_mode`` (``u``)

  How this session should persist. Default is 0. Accepted values are:

  - ``0``: Do not persist (default)
  - ``1``: Permissions persist as long as the application is running
  - ``2``: Permissions persist until explicitly revoked

  If the permission for the session to persist is granted,
  "persist_mode" will be returned in the results of the
  `org.freedesktop.impl.portal.ScreenCast.Start`_ method.

  This option was added in version 4 of this interface.

For available source types, see the AvailableSourceTypes property.



handle
  Object path for the :ref:`org.freedesktop.impl.portal.Request` object representing this call

session_handle
  Object path for the :ref:`org.freedesktop.impl.portal.Session` object representing the session

app_id
  App id of the application

options
  Vardict with optional further information

response
  Numeric response

results
  Vardict with the results of the call



.. _org.freedesktop.impl.portal.ScreenCast.Start:

org.freedesktop.impl.portal.ScreenCast.Start
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

    Start (
      IN handle o,
      IN session_handle o,
      IN app_id s,
      IN parent_window s,
      IN options a{sv},
      OUT response u,
      OUT results a{sv}
    )



Start the screen cast session. This will typically result the portal presenting
a dialog letting the user do the selection set up by SelectSources.

The following results get returned in the ``results`` vardict:

* ``streams`` (``a(ua{sv})``)

  An array of PipeWire streams. Each stream consists of a PipeWire
  node ID (the first element in the tuple, and a Vardict of
  properties.

  The array will contain a single stream if 'multiple' (see
  SelectSources) was set to 'false', or at least one stream if
  'multiple' was set to 'true' as part of the SelectSources method.

  Each stream contains the following properties:

  * ``position`` (``(ii)``)

    A tuple consisting of the position (x, y) in the compositor
    coordinate space. Note that the position may not be equivalent to a
    position in a pixel coordinate space. Only available for monitor
    streams.

  * ``size`` (``(ii)``)

    A tuple consisting of (width, height). The size represents the size
    of the stream as it is displayed in the compositor coordinate
    space. Note that this size may not be equivalent to a size in a
    pixel coordinate space. The size may differ from the size of the
    stream.

  * ``source_type`` (``u``)

    The type of the content which is being screen casted.
    For available source types, see the AvailableSourceTypes property.

    This property was added in version 3 of this interface.

  * ``mapping_id`` (``s``)

    An optional identifier used to map different aspects of the
    resource this stream corresponds to.

    When used in a remote desktop session, the mapping_id can be used to
    match a libei region of absolute libei devices. There may be
    multiple absolute libei devices, and each device may have multiple
    regions, but a mapping_id will only match one of these regions per
    device.

    This property was added in version 5 of this interface.

* ``persist_mode`` (``u``)

  Portal implementations can optionally offer ways to "reduce" the
  persist mode, for example by explicitly asking the user. See the
  'persist_mode' option of SelectSources for a list of possible
  values.

  If no persist mode is returned by the Start request, it is assumed
  to be the same persist mode received during SelectSources.

  This option was added in version 4 of this interface.

* ``restore_data`` (``(suv)``)

  The data to be restored. This is the data that a portal
  implementation sent in reaction to transient or persistent
  modes.

  This data will be stored in the permission store if the effective
  persist mode is 2, and may be passed in the future as part of the
  SelectSources() method call. The portal backend should store enough
  information in 'restore_data' to be able to restore the session
  later. The portal backend can deal with unavailable sources however
  they see fit.

  Data generated by a portal implementation must be consumable by
  the same portal implementation, but not necessarily by others.
  Thus, it is important to properly handle 'restore_data' not being
  in a valid format. This may happen when, e.g., the user switched
  to another desktop environment, or is using a different portal
  implementation.

  This response option was added in version 4 of this interface.



handle
  Object path for the :ref:`org.freedesktop.impl.portal.Request` object representing this call

session_handle
  Object path for the :ref:`org.freedesktop.impl.portal.Session` object representing the session

app_id
  App id of the application

parent_window
  Identifier for the application window, see :doc:`window-identifiers`

options
  Vardict with optional further information

response
  Numeric response

results
  Vardict with the results of the call


