Metadata-Version: 2.1
Name: pt-web-vnc
Version: 0.0.1.dev1
Summary: pi-top Web VNC Tool
Home-page: https://github.com/pi-top/pt-web-vnc
Author: pi-top (CEED Ltd)
Author-email: deb-maintainers@pi-top.com
License: Apache Software License
Keywords: pi-top,raspberrypi
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Developers
Classifier: Topic :: Education
Classifier: Topic :: System :: Hardware
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: Implementation :: PyPy
Description-Content-Type: text/x-rst
Provides-Extra: test
Requires-Dist: mock ; extra == 'test'
Requires-Dist: pytest ; extra == 'test'
Requires-Dist: pytest-asyncio ; extra == 'test'
Requires-Dist: pytest-cov ; extra == 'test'
Requires-Dist: requests ; extra == 'test'
Requires-Dist: testpath ; extra == 'test'

pt-web-vnc
==========

Serve a display or the window of a particular application via VNC & http using :code:`x11vnc` & :code:`novnc`.

The script can share an existing display or create a new one, depending on the provided display id. New displays are created using :code:`Xvfb` and it's dimensions and color depth can be specified via command line arguments.

It's also possible to share particular windows from a display by using the 'window-title' argument. This will look for a window with the provided name in a given display and will only share that particular section of the display. If this argument is not provided, the whole display is shared.

A python module :code:`pt_web_vnc` is also included which provides synchronous and asynchronous wrappers around the :code:`pt-web-vnc` script.


Usage
=====

.. code-block:: bash

  pt-web-vnc <COMMAND> --display-id <DISPLAY_ID> --HEIGHT <SCREEN_HEIGHT> --WIDTH <SCREEN_WIDTH> --ssl-certificate <SSL_CERTIFICATE> --window-title <WINDOW_TITLE> --run <RUN_COMMAND> --background-colour <COLOUR> --with-window-manager

  where:
    COMMAND: {start, stop, url, clients}
      start: start sharing a display or app based on the given arguments.
      stop: stop sharing the given display.
      url: print the novnc URL where the provided display is being served.
      clients: print the number of clients connected to a particular display.
    --display-id DISPLAY_ID: integer, id for the display to use/create. If the provided display ID doesn\'t exist, a new one will be created.
    --height SCREEN_HEIGHT: integer, height in pixels for the virtual display to create. Defaults to 1080.
    --width SCREEN_WIDTH: integer, width in pixels for the virtual display to create. Defaults to 1920.
    --depth SCREEN_DEPTH: integer, pixel depth for the virtual display to create. Defaults to 24.
    --ssl-certificate SSL_CERTIFICATE: path to combined SSL certificate & key file. Optional.
    --window-title WINDOW_TITLE: Title of a window in a display to share over VNC. Optional.
    --run RUN_COMMAND: Command to run before starting VNC server.
    --background-colour COLOUR: string with a colour name to use as background for the virtual display.
    --with-window-manager: start a window manager in the specified DISPLAY_ID. For now, the window manager used is 'bspwm'.


Examples
========

Start a virtual display with custom dimensions and background
-------------------------------------------------------------

.. code-block:: bash

	$ pt-web-vnc start --display-id 100 --height 500 --width 1000 --background-colour red
	# Get the URL to connect
	$ pt-web-vnc url --display-id 100
	http://pi-top.local:61100/vnc.html?autoconnect=true
	$ pt-web-vnc stop --display-id 100

Run an application in a virtual display and share its window
------------------------------------------------------------

By using the :code:`--run` argument to start an application and providing its window title via :code:`--window-title` it's possible to share a particular window.

.. code-block:: bash

	# Start chromium and look for its window title
	$ pt-web-vnc start --display-id 50 --run 'chromium-browser' --window-title 'New Tab - Chromium'
	# Get the URL to connect
	$ pt-web-vnc url --display-id 50
	http://pi-top.local:61050/vnc.html?autoconnect=true
	$ pt-web-vnc stop --display-id 50

Share an existing display
-------------------------

It's possible to share your main display instead of creating a new one by providing its display id. In most cases, the id for your main display will be :code:`0`.

.. code-block:: bash

	$ pt-web-vnc start --display-id 0
	# Get the URL to connect
	$ pt-web-vnc url --display-id 0
	http://pi-top.local:61000/vnc.html?autoconnect=true
	$ pt-web-vnc stop --display-id 000


Python module examples
======================

Create and share a display with custom dimensions and background colour
-----------------------------------------------------------------------

.. code-block:: python

  >>> from pt_web_vnc import start, connection_details, stop
  >>> start(
  	display_id=50,
  	height=500,
  	width=1000,
  	background_colour="blue",
  )
  >>> # Get connection details
  >>> details = connection_details(display_id=50)
  >>> details.url
  'http://pi-top.local:61050/vnc.html?autoconnect=true&resize=scale'

  >>> # Stop sharing
  >>> stop(display_id=50)


Asynchronously start sharing display 0
--------------------------------------

.. code-block:: python

  >>> import asyncio
  >>> from pt_web_vnc import async_start, async_connection_details, async_stop
  >>> # Start sharing display 0
  >>> asyncio.run(async_start(display_id=0)
  ...
  >>> # Get connection details
  >>> details = asyncio.run(async_connection_details(display_id=0))
  >>> details.url
  'http://pi-top.local:61000/vnc.html?autoconnect=true&resize=scale'
  >>> # Returned object also contains parsed elements of the URL
  >>> details.scheme
  'http'
  >>> details.hostname
  'pi-top.local'
  >>> details.port
  61000
  >>> details.path
  '/vnc.html?autoconnect=true&resize=scale'
  >>> # Stop sharing display 0
  >>> asyncio.run(async_stop(display_id=0)


