Fonetic Documentation

Real-time translation for person-to-person chat (Fonetic Hyper-Local) and public transport announcements (Fonetic OV).

Quick Start

Chat functionality: CHAT_API.md
Announcement functionality: ANNOUNCEMENT_API.md
Codebase overview: CODE_MAP.md
Known issues: ISSUES.md

Features

1. Person-to-Person Room Based Chat (Fonetic Hyper-Local)

People near the same beacon can chat in different languages with real-time translation.

  • Status: Working end-to-end
  • Server: WebSocket on port 5002
  • Documentation: CHAT_API.md

2. Public Transport Announcements (Fonetic OV)

Train/bus announcements captured and translated for passengers.

  • Status: Backend complete, web demo working, mobile app TODO
  • OV client: Captures and sends audio (HTTP POST)
  • Server: Transcription + translation working
  • Web demo: Browser viewer at /server/templates/index.html
  • Mobile app: Not yet integrated with announcements (TODO)
  • Documentation: ANNOUNCEMENT_API.md

Architecture

Chat Flow

[Mobile App]
     ↓ WebSocket connection
[Main Server] (api.fonetic.studio:5002)
     ↓ Send for translation
[LibreTranslate] (192.168.200.32:5000)
     ↓ Translated messages
[Main Server]
     ↓ Push via WebSocket
[All users in room]

Announcement Flow

[Train Announcement]
     ↓
[OV Client] (Raspberry Pi in vehicle)
     ↓ HTTP POST /stt + vehicle ID
[Main Server] (api.fonetic.studio:11624)
     ↓ Forward audio
[GPU Server] (192.168.200.32:11624)
     ↓ Transcription
[Main Server]
     ↓ Translation
[LibreTranslate] (192.168.200.32:5000)
     ↓ Translated text
[Main Server]
     ↓ WebSocket push
[Clients] (web demo/mobile app)
     ↓
[User sees announcement in their language]

See CODE_MAP.md for detailed architecture and file descriptions.

Repository Structure

/server          - Main Python server (WebSocket chat + announcement relay)
/app             - Flutter mobile app (iOS/Android/Web)
/ov              - Announcement capture system
  /ov/client     - Raspberry Pi OV client
  /ov/server     - GPU STT server
/beacon          - Physical beacon devices (TOTP generation)
/docs            - This documentation

Known Issues

There's a couple issues within the codbase See ISSUES.md for complete list.

Biggest problems:

  • TOTP validation not implemented

  • WebSocket reconection broken

  • Room cleanup never called