mirror of
https://github.com/OpenSquawk/OpenSquawk
synced 2026-08-01 06:06:05 +08:00
update readme
This commit is contained in:
itsrubberduck
166
README.md
166
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!
|
||||
|
||||
Reference in New Issue
Block a user