# Plover WebSocket Server
[](https://github.com/CosmicDNA/plover-websocket-server/actions/workflows/pytest.yml)
[](https://pypi.python.org/pypi/plover-websocket-server/)
A WebSocket server for exposing [Plover](https://github.com/openstenoproject/plover) events
and controlling Plover from an external program.
This plugin is available on [GitHub](https://github.com/CosmicDNA/plover-websocket-server)
and [PyPI](https://pypi.org/project/plover-websocket-server/) (under the name `plover-websocket-server`).
Report all bugs on GitHub.
## Installation
Download the latest version of Plover for your operating system from the [releases page](https://github.com/openstenoproject/plover/releases). Only versions 4.0.0.dev8 and higher are supported.
1. Open Plover
2. Navigate to the Plugin Manager tool
3. Select the "plover-websocket-server" plugin entry in the list
4. Click install
5. Restart Plover
The same method can be used for updating and uninstalling the plugin.
## Configuration
A file named `plover_websocket_server_config.json` will be created
inside Plover's configuration directory (same directory as `plover.cfg` file).
Example content:
```json
{
"private_key": "eb700b05b84a14b81ea69d5f826fc4ca30310db22f8943b1975fe56043c00771",
"public_key": "3a283210963d849642011731ba048e8d8f2272802902a9ef7de56d0116236801",
"host": "localhost",
"port": 8086,
"remotes": [
{
"pattern": "^https?\\:\\/\\/localhost?(:[0-9]*)?"
}
],
"ssl": {
"cert_path": "/path/to/cert.pem",
"key_path": "/path/to/key.pem"
}
}
```
All fields are optional. But if you specify either a private or public key you need the opposed matching key also specified. The same pattern applies to the pair of ssl paths.
The default is included in the example above except for the private and public keys and the ssl paths which are just an example.
In the remotes config, either an object with a Regex pattern, or a string are supported. This is important to allow [Cross Origin Resource Sharing (CORS)](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) for the specific case where your client runs on a browser.
> [!NOTE]
> This plugin utilises assymetric key encryption to protect the plugin from unauthorised access and is powered by [Pynacl](https://github.com/pyca/pynacl/).
## How to Use
* Enable it in Configure -> Plugins
* Connect to ws://localhost:8086/websocket with your client and get the data pushed to you as
event: data formatted JSON.
Received data format: Search for occurrences of `queue_message` in `plover_websocket_server/manager.py`,
or write an example program
and observe its output.
> [!TIP]
> Use the existing example script `test/client_example.py` to interact with the plugin.
Controlling Plover from other programs:
* Sending 'close' disconnects you.
* Sending a valid JSON string will execute the specified action.
For example `{"stroke": ["S-"]}` (note that invalid keys are silently dropped),
or `{"translation": "abc"}`.
If there's some error during the execution, it will be silently ignored and printed on stderr.
If the `"force"` key is `true` then the command will be executed even when the engine is turned off.
Note that `{PLOVER:RESUME}` will have no effect in that case.
Because the Plover inner working is closely tied to the assumption
that strokes can only come from the keyboard, when `{PLOVER:RESUME}` (or a command with similar effect,
such as `{PLOVER:TOGGLE}`) is sent and the machine is
"Keyboard" then some characters before the cursor will be deleted.
To prevent this, set the `"zero_last_stroke_length"` key to `true`.
> [!WARNING]
> This should be used very sparingly because it may have unintended effects.
## Acknowlegements
Forked from https://github.com/user202729/plover_websocket_server.
Raw data
{
"_id": null,
"home_page": null,
"name": "plover-websocket-server",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "plover plover_plugin",
"author": null,
"author_email": "Daniel de Souza <daniel@cosmicdna.co.uk>",
"download_url": "https://files.pythonhosted.org/packages/02/11/1865f0e993055b99ef6e83fef860c6ed7ca46691c747102ebf04bcdb2e12/plover_websocket_server-0.1.5.tar.gz",
"platform": null,
"description": "# Plover WebSocket Server\n\n[](https://github.com/CosmicDNA/plover-websocket-server/actions/workflows/pytest.yml)\n[](https://pypi.python.org/pypi/plover-websocket-server/)\n\nA WebSocket server for exposing [Plover](https://github.com/openstenoproject/plover) events\nand controlling Plover from an external program.\n\nThis plugin is available on [GitHub](https://github.com/CosmicDNA/plover-websocket-server)\nand [PyPI](https://pypi.org/project/plover-websocket-server/) (under the name `plover-websocket-server`).\nReport all bugs on GitHub.\n\n## Installation\n\nDownload the latest version of Plover for your operating system from the [releases page](https://github.com/openstenoproject/plover/releases). Only versions 4.0.0.dev8 and higher are supported.\n\n1. Open Plover\n2. Navigate to the Plugin Manager tool\n3. Select the \"plover-websocket-server\" plugin entry in the list\n4. Click install\n5. Restart Plover\n\nThe same method can be used for updating and uninstalling the plugin.\n\n## Configuration\n\nA file named `plover_websocket_server_config.json` will be created\ninside Plover's configuration directory (same directory as `plover.cfg` file).\n\nExample content:\n\n```json\n{\n \"private_key\": \"eb700b05b84a14b81ea69d5f826fc4ca30310db22f8943b1975fe56043c00771\",\n \"public_key\": \"3a283210963d849642011731ba048e8d8f2272802902a9ef7de56d0116236801\",\n \"host\": \"localhost\",\n \"port\": 8086,\n \"remotes\": [\n {\n \"pattern\": \"^https?\\\\:\\\\/\\\\/localhost?(:[0-9]*)?\"\n }\n ],\n \"ssl\": {\n \"cert_path\": \"/path/to/cert.pem\",\n \"key_path\": \"/path/to/key.pem\"\n }\n}\n```\n\nAll fields are optional. But if you specify either a private or public key you need the opposed matching key also specified. The same pattern applies to the pair of ssl paths.\n\nThe default is included in the example above except for the private and public keys and the ssl paths which are just an example.\n\nIn the remotes config, either an object with a Regex pattern, or a string are supported. This is important to allow [Cross Origin Resource Sharing (CORS)](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) for the specific case where your client runs on a browser.\n\n> [!NOTE]\n> This plugin utilises assymetric key encryption to protect the plugin from unauthorised access and is powered by [Pynacl](https://github.com/pyca/pynacl/).\n\n## How to Use\n\n* Enable it in Configure -> Plugins\n* Connect to ws://localhost:8086/websocket with your client and get the data pushed to you as\nevent: data formatted JSON.\n\nReceived data format: Search for occurrences of `queue_message` in `plover_websocket_server/manager.py`,\nor write an example program\nand observe its output.\n\n> [!TIP]\n> Use the existing example script `test/client_example.py` to interact with the plugin.\n\nControlling Plover from other programs:\n\n* Sending 'close' disconnects you.\n* Sending a valid JSON string will execute the specified action.\nFor example `{\"stroke\": [\"S-\"]}` (note that invalid keys are silently dropped),\nor `{\"translation\": \"abc\"}`.\n\nIf there's some error during the execution, it will be silently ignored and printed on stderr.\n\nIf the `\"force\"` key is `true` then the command will be executed even when the engine is turned off.\nNote that `{PLOVER:RESUME}` will have no effect in that case.\n\nBecause the Plover inner working is closely tied to the assumption\nthat strokes can only come from the keyboard, when `{PLOVER:RESUME}` (or a command with similar effect,\nsuch as `{PLOVER:TOGGLE}`) is sent and the machine is\n\"Keyboard\" then some characters before the cursor will be deleted.\nTo prevent this, set the `\"zero_last_stroke_length\"` key to `true`.\n\n> [!WARNING]\n> This should be used very sparingly because it may have unintended effects.\n\n## Acknowlegements\n\nForked from https://github.com/user202729/plover_websocket_server.\n",
"bugtrack_url": null,
"license": "GNU General Public License v3 or later (GPLv3+)",
"summary": "A server for exposing Plover engine events and functionality",
"version": "0.1.5",
"project_urls": {
"Homepage": "https://github.com/CosmicDNA/plover-websocket-server.git"
},
"split_keywords": [
"plover",
"plover_plugin"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a513379d4638947d6e102547213ef6c27d233b4f87498aa4f162d4674b0c9089",
"md5": "bf0346ca898c74fb62e3b6eff1b72473",
"sha256": "47842f3b1fa7a4080204dff45dc7d5229c3970331db65dff33362a7fdb07dbff"
},
"downloads": -1,
"filename": "plover_websocket_server-0.1.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "bf0346ca898c74fb62e3b6eff1b72473",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 26722,
"upload_time": "2024-06-05T22:01:57",
"upload_time_iso_8601": "2024-06-05T22:01:57.572715Z",
"url": "https://files.pythonhosted.org/packages/a5/13/379d4638947d6e102547213ef6c27d233b4f87498aa4f162d4674b0c9089/plover_websocket_server-0.1.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "02111865f0e993055b99ef6e83fef860c6ed7ca46691c747102ebf04bcdb2e12",
"md5": "8a606f5bb3e4734190070f0cea04749c",
"sha256": "6979831c64259729f7cd04cf05c22454de7028ce70d2d38977046a50a4939495"
},
"downloads": -1,
"filename": "plover_websocket_server-0.1.5.tar.gz",
"has_sig": false,
"md5_digest": "8a606f5bb3e4734190070f0cea04749c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 26539,
"upload_time": "2024-06-05T22:01:59",
"upload_time_iso_8601": "2024-06-05T22:01:59.527691Z",
"url": "https://files.pythonhosted.org/packages/02/11/1865f0e993055b99ef6e83fef860c6ed7ca46691c747102ebf04bcdb2e12/plover_websocket_server-0.1.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-06-05 22:01:59",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "CosmicDNA",
"github_project": "plover-websocket-server",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "plover-websocket-server"
}
JSON
