Compare commits

...

2 Commits

Author SHA1 Message Date
2e915b9037 Merge branch 'main' of gordon.zumepro.cz:zumepro/pythagoras 2025-05-05 15:06:32 +02:00
cdaae14e84 Make README pretty 2025-05-05 15:05:58 +02:00

208
README.md
View File

@@ -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. Heres an example:
`
```bash
curl -X GET http://localhost:8000/media/stallman.webm
`
```