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
• Installation
• Running the App
  • Running Translation Server
  • Cleaning Up
  • Packing for Production
• Usage
  • Subtitles
  • Commands
  • Media

Dependencies

• pyenv
• python-virtualenv
• bun

Installation

1. Clone the repository:

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

2. Install the dependencies:

   sudo pacman -S python-virtualenv
   

Running the App

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

make run

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

make

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

Running Translation Server

To start the translation server for subtitle translation, run:

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:

make clean

Packing for Production

To create an archive named pythagoras.tar.xz in the project root, simply run:

make pack

Usage

To connect to the WebSocket for receiving subtitles, messages, and commands, use the /ws endpoint. For example:

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:

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:

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:

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

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:

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

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

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:

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

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

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:

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

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:

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 file for details.