pythagoras/README.md

# Pythagoras

**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`

## Installation

1. Clone the repository:

   ```bash
   git clone git@gordon.zumepro.cz:zumepro/pythagoras.git
   ```

2. Install the dependencies:

   ```bash
   sudo pacman -S python-virtualenv
   ```

## Running the App

To start the server, simply execute the **run** recipe in the Makefile:

```bash
make run
```

Note: `run` is the default recipe, so you can also just use:

```bash
make
```

The run recipe will take care of everything for you. Enjoy!

### Running Translation Server

To start the translation server for subtitle translation, run:

```bash
make libretranslate
```

You can keep it running through multiple `make run` commands. The Makefile will pre-install everything if needed.

### Cleaning Up

If you wish to return to a clean slate, just run:

```bash
make clean
```

### Packing for Production

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, 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`

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

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

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 available commands:

- `getselectedmessage`
- `setlibretranslate`
- `setautopolling`
- `autopollingrate`
- `playvideo`
- `seekvideo`
- `setscreen_main`
- `setscreen_video`
- `setscreen_idle`

To control the server using commands, use the `/control` endpoint. Here are some examples:

#### Get Selected Message

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):

```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:

```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):

```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 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 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):

```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 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):

```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 a standard HTTP FileResponse. Here’s an example:

```bash
curl -X GET http://localhost:8000/media/stallman.webm
```

## License

This project is licensed under the GNU General Public License v3.0 - see the [LICENSE](LICENSE) file for details.