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)
Raw data
{
"_id": null,
"home_page": "https://github.com/pi-top/pt-web-vnc",
"name": "pt-web-vnc",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "pi-top,raspberrypi",
"author": "pi-top (CEED Ltd)",
"author_email": "deb-maintainers@pi-top.com",
"download_url": "https://files.pythonhosted.org/packages/fe/d6/a55936913a85ef2bdbd06c5410bd4118779f9da96a51dacdf11d8e101ae3/pt-web-vnc-0.5.0.post1.tar.gz",
"platform": null,
"description": "pt-web-vnc\n==========\n\nServe a display or the window of a particular application via VNC & http using :code:`x11vnc` & :code:`novnc`.\n\nThe 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.\n\nIt'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.\n\nA python module :code:`pt_web_vnc` is also included which provides synchronous and asynchronous wrappers around the :code:`pt-web-vnc` script.\n\n\nUsage\n=====\n\n.. code-block:: bash\n\n 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\n\n where:\n COMMAND: {start, stop, url, clients}\n start: start sharing a display or app based on the given arguments.\n stop: stop sharing the given display.\n url: print the novnc URL where the provided display is being served.\n clients: print the number of clients connected to a particular display.\n --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.\n --height SCREEN_HEIGHT: integer, height in pixels for the virtual display to create. Defaults to 1080.\n --width SCREEN_WIDTH: integer, width in pixels for the virtual display to create. Defaults to 1920.\n --depth SCREEN_DEPTH: integer, pixel depth for the virtual display to create. Defaults to 24.\n --ssl-certificate SSL_CERTIFICATE: path to combined SSL certificate & key file. Optional.\n --window-title WINDOW_TITLE: Title of a window in a display to share over VNC. Optional.\n --run RUN_COMMAND: Command to run before starting VNC server.\n --background-colour COLOUR: string with a colour name to use as background for the virtual display.\n --with-window-manager: start a window manager in the specified DISPLAY_ID. For now, the window manager used is 'bspwm'.\n\n\nExamples\n========\n\nStart a virtual display with custom dimensions and background\n-------------------------------------------------------------\n\n.. code-block:: bash\n\n\t$ pt-web-vnc start --display-id 100 --height 500 --width 1000 --background-colour red\n\t# Get the URL to connect\n\t$ pt-web-vnc url --display-id 100\n\thttp://pi-top.local:61100/vnc.html?autoconnect=true\n\t$ pt-web-vnc stop --display-id 100\n\nRun an application in a virtual display and share its window\n------------------------------------------------------------\n\nBy 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.\n\n.. code-block:: bash\n\n\t# Start chromium and look for its window title\n\t$ pt-web-vnc start --display-id 50 --run 'chromium-browser' --window-title 'New Tab - Chromium'\n\t# Get the URL to connect\n\t$ pt-web-vnc url --display-id 50\n\thttp://pi-top.local:61050/vnc.html?autoconnect=true\n\t$ pt-web-vnc stop --display-id 50\n\nShare an existing display\n-------------------------\n\nIt'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`.\n\n.. code-block:: bash\n\n\t$ pt-web-vnc start --display-id 0\n\t# Get the URL to connect\n\t$ pt-web-vnc url --display-id 0\n\thttp://pi-top.local:61000/vnc.html?autoconnect=true\n\t$ pt-web-vnc stop --display-id 000\n\n\nPython module examples\n======================\n\nCreate and share a display with custom dimensions and background colour\n-----------------------------------------------------------------------\n\n.. code-block:: python\n\n >>> from pt_web_vnc import start, connection_details, stop\n >>> start(\n \tdisplay_id=50,\n \theight=500,\n \twidth=1000,\n \tbackground_colour=\"blue\",\n )\n >>> # Get connection details\n >>> details = connection_details(display_id=50)\n >>> details.url\n 'http://pi-top.local:61050/vnc.html?autoconnect=true&resize=scale'\n\n >>> # Stop sharing\n >>> stop(display_id=50)\n\n\nAsynchronously start sharing display 0\n--------------------------------------\n\n.. code-block:: python\n\n >>> import asyncio\n >>> from pt_web_vnc import async_start, async_connection_details, async_stop\n >>> # Start sharing display 0\n >>> asyncio.run(async_start(display_id=0)\n ...\n >>> # Get connection details\n >>> details = asyncio.run(async_connection_details(display_id=0))\n >>> details.url\n 'http://pi-top.local:61000/vnc.html?autoconnect=true&resize=scale'\n >>> # Returned object also contains parsed elements of the URL\n >>> details.scheme\n 'http'\n >>> details.hostname\n 'pi-top.local'\n >>> details.port\n 61000\n >>> details.path\n '/vnc.html?autoconnect=true&resize=scale'\n >>> # Stop sharing display 0\n >>> asyncio.run(async_stop(display_id=0)\n\n\n",
"bugtrack_url": null,
"license": "Apache Software License",
"summary": "pi-top Web VNC Tool",
"version": "0.5.0.post1",
"project_urls": {
"Homepage": "https://github.com/pi-top/pt-web-vnc"
},
"split_keywords": [
"pi-top",
"raspberrypi"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "69371dbc920418a8f07651d156aec5c90c58fd6de3589d086daf2498fec94a00",
"md5": "f9f4d1aa3ca8fe51f002a91a07238f34",
"sha256": "cfc049fba9a860f4715d256ab8688f0e23c23ca36ff89f280697dbbad5a086d6"
},
"downloads": -1,
"filename": "pt_web_vnc-0.5.0.post1-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "f9f4d1aa3ca8fe51f002a91a07238f34",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 13649,
"upload_time": "2023-05-04T13:15:31",
"upload_time_iso_8601": "2023-05-04T13:15:31.579461Z",
"url": "https://files.pythonhosted.org/packages/69/37/1dbc920418a8f07651d156aec5c90c58fd6de3589d086daf2498fec94a00/pt_web_vnc-0.5.0.post1-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "fed6a55936913a85ef2bdbd06c5410bd4118779f9da96a51dacdf11d8e101ae3",
"md5": "10412525e5e1610ec600c6122c9bb4a4",
"sha256": "b784395ba587048e6dec1d575b9472e539fe6db36315a81f0ea23e8a0f01afd5"
},
"downloads": -1,
"filename": "pt-web-vnc-0.5.0.post1.tar.gz",
"has_sig": false,
"md5_digest": "10412525e5e1610ec600c6122c9bb4a4",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 9335,
"upload_time": "2023-05-04T13:15:34",
"upload_time_iso_8601": "2023-05-04T13:15:34.246220Z",
"url": "https://files.pythonhosted.org/packages/fe/d6/a55936913a85ef2bdbd06c5410bd4118779f9da96a51dacdf11d8e101ae3/pt-web-vnc-0.5.0.post1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-05-04 13:15:34",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "pi-top",
"github_project": "pt-web-vnc",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pt-web-vnc"
}