From 73e622d69764ec734de4c3232bcd02b1d17873f1 Mon Sep 17 00:00:00 2001 From: itsrubberduck Date: Sun, 21 Sep 2025 00:24:47 +0200 Subject: [PATCH] update readme --- README.md | 166 ++++++++++++++++++++++++++++++++---------------------- 1 file changed, 100 insertions(+), 66 deletions(-) diff --git a/README.md b/README.md index cec524a..e85732b 100644 --- a/README.md +++ b/README.md @@ -1,82 +1,116 @@ -# Nuxt Minimal Starter +# OpenSquawk -Look at the [Nuxt documentation](https://nuxt.com/docs/getting-started/introduction) to learn more. +OpenSquawk is an open, cost-efficient AI-ATC platform for flight simulators. +Built with Nuxt 4, it provides a web interface that combines training, radio communication, and learning content for simulator pilots. +On the server side, via Node.js Open AI deliver speech synthesis, decision trees, and account management. +Goal: a community-driven alternative to other costly AI-ATC solutions while being open and extensible. + +## Current Features + +* Modern web UI (Nuxt 4, Tailwind, Vuetify) with landing and learning pages +* Server APIs for ATC logic, decision trees, learning content, and authentication +* MongoDB storage +* OpenAI integration for speech and text models with configurable voices +* Optional local Speaches server for self-hosted speech in/output + +## Roadmap & Integrations + +* **Simulator Bridges:** Planned connection to Microsoft Flight Simulator and X-Plane to receive live flight data. Implementation is scheduled but will take a few more months. +* **SimBrief:** Upcoming direct integration of SimBrief data (flight plans, briefings) for seamless cockpit dispatch info. +* **VATSIM:** No integration for now due to unclear licensing. We are monitoring the situation but will avoid coupling until approval is granted. + +## Requirements + +| Component | Note | +|---------------------|----------------------------------------------------------------------------| +| Node.js 22 | Specified in `package.json`. | +| Yarn | | +| MongoDB 7+ | Local instance or hosted database. Configure via `MONGODB_URI`. | +| ffmpeg | Needed for audio processing (`fluent-ffmpeg`), must be on the system PATH. | +| OpenAI API Key | For TTS and LLM calls (`OPENAI_API_KEY`). | +| Optional: Piper TTS | For local speech (`pip install "piper-tts[http]"`). | ## Setup -Make sure to install dependencies: +1. Clone the repository: + + ```bash + git clone https://github.com/FaktorxMensch/OpenSquawk.git + cd OpenSquawk + ``` +2. Enable corepack and install dependencies: + + ```bash + corepack enable + yarn install + ``` +3. Configure environment variables: + + ```bash + cp .env.example .env + ``` + + Key variables: + + * `MONGODB_URI`: MongoDB connection string (default `mongodb://127.0.0.1:27017/opensquawk`). + * `JWT_SECRET` & `JWT_REFRESH_SECRET`: Random strings for tokens. + * `OPENAI_API_KEY`, optional `OPENAI_PROJECT`, `LLM_MODEL`, `TTS_MODEL`, `VOICE_ID`. + * `ATC_OUT_DIR`: Directory for generated audio files. + * `USE_PIPER`, `PIPER_PORT`: Enable local Piper TTS instance. + * SMTP settings (`NOTIFY_*`) if emails should be sent. +4. Start MongoDB and ensure `ffmpeg` is on the PATH. +5. Launch the dev server: + + ```bash + yarn dev + ``` + + Interface runs at [http://localhost:3000](http://localhost:3000) with hot-reload. + +## Production & Preview + +* Build: + + ```bash + yarn build + ``` +* Local preview: + + ```bash + yarn preview + ``` +* For custom hosting, serve the Nuxt directory (`yarn start`). + +## Optional Local Speech Services + +### Piper TTS + +For speech output without OpenAI: ```bash -# npm -npm install - -# pnpm -pnpm install - -# yarn -yarn install - -# bun -bun install +pip install "piper-tts[http]" +piper-http-server --port 5001 ``` -## Development Server +Set `USE_PIPER=true` and adjust `PIPER_PORT`. +Model ID (`SPEECH_MODEL_ID`) can also be set in `.env`. -Start the development server on `http://localhost:3000`: +### Local STT/TTS -```bash -# npm -npm run dev +Local models via WSL+Docker is planned but not yet implemented. Placeholders and TODOs exist in the code. -# pnpm -pnpm dev +## Project Structure -# yarn -yarn dev - -# bun -bun run dev +``` +app/ # Nuxt frontend (pages, components, stores) +server/ # API routes, services, utilities (ATC, Auth, LLM) +shared/ # Shared types and helpers +content/ # Markdown news & CMS content ``` -## Production +## Contributing & Community -Build the application for production: +We welcome issues, pull requests, and ideas—especially Nuxt/Node expertise, ATC knowledge, MSFS/X-Plane test flights, and infrastructure/cost optimization. +Contact: [info@opensquawk.de](mailto:info@opensquawk.de). -```bash -# npm -npm run build - -# pnpm -pnpm build - -# yarn -yarn build - -# bun -bun run build -``` - -Locally preview production build: - -```bash -# npm -npm run preview - -# pnpm -pnpm preview - -# yarn -yarn preview - -# bun -bun run preview -``` - -Check out the [deployment documentation](https://nuxt.com/docs/getting-started/deployment) for more information. - - -# Piper TTS local -if you want to use local tts, install and run pip install "piper-tts[http]" on port 5001, then set USE_PIPER=true in .env - -# Whisper Tiny local -if you want to use local whisper tiny implement it #TODO +OpenSquawk thrives on community collaboration—priorities are set together. Join in!