From cdaae14e84366c4b892b5ad46b34d7963c20b0e0 Mon Sep 17 00:00:00 2001 From: zucham Date: Mon, 5 May 2025 15:05:58 +0200 Subject: [PATCH] Make README pretty --- README.md | 208 ++++++++++++++++++++++++++++++++---------------------- 1 file changed, 122 insertions(+), 86 deletions(-) diff --git a/README.md b/README.md index d6c20d2..325cba3 100644 --- a/README.md +++ b/README.md @@ -1,179 +1,215 @@ # Pythagoras -Local-run server which acts as a proxy between the moderation server, presentation client and subtitle scripts. This is a single-purpose ugly implementation with its sole purpose being the Richard Stallman lecture at TUL. +**Pythagoras** is a local-run server that acts as a proxy between the moderation server, presentation client, and subtitle scripts. This implementation is specifically designed for the Richard Stallman lecture at TUL. + +## Table of Contents + +- [Dependencies](#dependencies) +- [Installation](#installation) +- [Running the App](#running-the-app) + - [Running Translation Server](#running-translation-server) + - [Cleaning Up](#cleaning-up) + - [Packing for Production](#packing-for-production) +- [Usage](#usage) + - [Subtitles](#subtitles) + - [Commands](#commands) + - [Media](#media) ## Dependencies -- pyenv -- python virtualenv -- bun +- `pyenv` +- `python-virtualenv` +- `bun` ## Installation -Clone the repository: +1. Clone the repository: -`git clone git@gordon.zumepro.cz:zumepro/pythagoras.git` + ```bash + git clone git@gordon.zumepro.cz:zumepro/pythagoras.git + ``` -Install the dependencies: +2. Install the dependencies: -`sudo pacman -S python-virtualenv` + ```bash + sudo pacman -S python-virtualenv + ``` -## Running the app +## Running the App -Simply execute the **run** recipe in the Makefile to start the server: +To start the server, simply execute the **run** recipe in the Makefile: -`make run` +```bash +make run +``` -Note that run is also the default recipe. So `make` works too. +Note: `run` is the default recipe, so you can also just use: -The run recipe should take care of everything for you... enjoy! +```bash +make +``` -### Running translation server +The run recipe will take care of everything for you. Enjoy! -To start translation server for subtitle translation, run: +### Running Translation Server -`make libretranslate` +To start the translation server for subtitle translation, run: -You can keep it running through multiple `make run`'s. -The makefile will pre-install everything if needed. +```bash +make libretranslate +``` -### Cleaning up the mess +You can keep it running through multiple `make run` commands. The Makefile will pre-install everything if needed. -If you wish to go back to a clean slate just run: +### Cleaning Up -`make clean` +If you wish to return to a clean slate, just run: -### Packing for production +```bash +make clean +``` -To make an archive `pythagoras.tar.xz` in project root simply run: +### Packing for Production -`make pack` +To create an archive named `pythagoras.tar.xz` in the project root, simply run: + +```bash +make pack +``` ## Usage -To connect to the WebSocket for receiving subtitles, messages and commands, simply use the `/ws` endpoint, for example like this: +To connect to the WebSocket for receiving subtitles, messages, and commands, use the `/ws` endpoint. For example: -` +```bash websocat ws://localhost:8000/ws -` +``` ### Subtitles Here is a list of all subtitle types: -- `subtitle_en_submit_sentence`, `subtitle_cs_submit_sentence`, `subtitle_en_update_current` +- `subtitle_en_submit_sentence` +- `subtitle_cs_submit_sentence` +- `subtitle_en_update_current` -To push new subtitles onto the server, use the `/subtitles/` endpoints. There are currently two different ones, and each produces different response type. When translation is enabled, each sentence submission yields two websocket messages, one in English and one in Czech. Here are some examples: +To push new subtitles onto the server, use the `/subtitles/` endpoints. There are currently two different endpoints, each producing a different response type. When translation is enabled, each sentence submission yields two WebSocket messages, one in English and one in Czech. Here are some examples: -___ +#### Update Current Subtitle -- The first is `/subtitles/update_current`, which serves the purpose of updating the current sentence as it comes. Here is an example: +To update the current sentence as it comes, use: -` +```bash curl -X POST http://localhost:8000/subtitles/update_current -H "Content-Type: text/plain" -d 'I love pushing ' -` +``` -___ +#### Submit Finished Sentence -- The second is `/subtitles/submit_sentence`, which is used to submit the next finished sentence. Here is an example: +To submit the next finished sentence, use: -` +```bash curl -X POST http://localhost:8000/subtitles/submit_sentence -H "Content-Type: text/plain" -d 'I love pushing sentences to servers!' -` - -___ - +``` ### Commands -Here is a list of all commands: +Here is a list of all available commands: -- `getselectedmessage`, `setlibretranslate`, `setautopolling`, `autopollingrate`, `playvideo`, `seekvideo`, `setscreen_main`, `setscreen_video`, `setscreen_idle` +- `getselectedmessage` +- `setlibretranslate` +- `setautopolling` +- `autopollingrate` +- `playvideo` +- `seekvideo` +- `setscreen_main` +- `setscreen_video` +- `setscreen_idle` -To control the server using commands, use the `/control` endpoint, for example like this: +To control the server using commands, use the `/control` endpoint. Here are some examples: -___ +#### Get Selected Message -- Poll the peehaitchpea server for the latest message to display: +Poll the server for the latest message to display: -` +```bash curl -X POST http://localhost:8000/control -H "Content-Type: application/json" -d '{"command": "getselectedmessage"}' -` +``` -___ +#### Set LibreTranslate State -- Change the state of the LibreTranslate translation module (active or deactivated): +Change the state of the LibreTranslate translation module (active or deactivated): -` +```bash curl -X POST http://localhost:8000/control -H "Content-Type: application/json" -d '{"command": "setlibretranslate", "state": false}' -` +``` -___ +#### Set Auto-Polling State -- Change the state of auto-polling: +Change the state of auto-polling: -` +```bash curl -X POST http://localhost:8000/control -H "Content-Type: application/json" -d '{"command": "setautopolling", "state": false}' -` +``` -___ +#### Set Polling Rate -- Set the polling rate to a value (in seconds): +Set the polling rate to a value (in seconds): -` +```bash curl -X POST http://localhost:8000/control -H "Content-Type: application/json" -d '{"command": "autopollingrate", "rate": 10}' -` +``` -___ +#### Play Video -- Tell the client to play a video, defined by the `filename` parameter. It has optional parameters `subtitles`, which should point to a subtitle file and defaults to `null`, and `secondsfromstart` which indicated the timestap at what the video should start, which defaults to `0`: +Tell the client to play a video, defined by the `filename` parameter. It has optional parameters `subtitles` (which should point to a subtitle file and defaults to `null`) and `secondsfromstart` (which indicates the timestamp at which the video should start, defaulting to `0`): -` +```bash curl -X POST http://localhost:8000/control -H "Content-Type: application/json" -d '{"command": "playvideo", "filename": "stallman.webm"}' -` +``` -` +To include subtitles and specify a start time: + +```bash curl -X POST http://localhost:8000/control -H "Content-Type: application/json" -d '{"command": "playvideo", "filename": "stallman.webm", "subtitles": "stallman.vtt", "secondsfromstart": 69}' -` +``` -___ +#### Seek Video -- Seek the currently played video to a timestamp (in seconds): +Seek the currently played video to a specific timestamp (in seconds): -` +```bash curl -X POST http://localhost:8000/control -H "Content-Type: application/json" -d '{"command": "seekvideo", "timestamp": 420}' -` +``` -___ +#### Set Screen to Main View -- Set the screen of the client to the main view (subtitles and messages): +Set the screen of the client to the main view (subtitles and messages): -` +```bash curl -X POST http://localhost:8000/control -H "Content-Type: application/json" -d '{"command": "setscreen_main"}' -` +``` -___ +#### Set Screen to Video Playback -- Set the screen of the client to the video playback: +Set the screen of the client to the video playback view: -` +```bash curl -X POST http://localhost:8000/control -H "Content-Type: application/json" -d '{"command": "setscreen_video"}' -` +``` -___ +#### Set Screen to Idle -- Set the screen of the client to the idle screen (this is the default screen after startup of the app): +Set the screen of the client to the idle screen (this is the default screen after startup of the app): -` +```bash curl -X POST http://localhost:8000/control -H "Content-Type: application/json" -d '{"command": "setscreen_idle"}' -` - -___ +``` ### Media -You can also request media from Pythagoras using the `/media/` endpoint, which will yield you the standard HTTP FileResponse, here is an example: +You can also request media from Pythagoras using the `/media/` endpoint, which will yield a standard HTTP FileResponse. Here’s an example: -` +```bash curl -X GET http://localhost:8000/media/stallman.webm -` +``` +