Ez a projekt egy Python alapú REST API, amely lehetővé teszi hangfájlok lejátszását, vezérlését és állapotának lekérdezését egy socket-alapú lejátszómagon keresztül. A rendszer FastAPI-ra épül, és a háttérben egy socket szerveren keresztül kommunikál a lejátszó modulokkal.

🧠 Működés röviden

• A REST API parancsokat fogad HTTP-n keresztül (pl. /play, /stop, /volume).
• Ezeket a parancsokat JSON formátumban továbbítja egy helyi socket szervernek (alapértelmezetten 127.0.0.1:9999).
• A socket válaszként visszaküld egy JSON választ, amelyet az API továbbít a kliensnek.

---

🚀 Telepítés

1. Követelmények:

pip install fastapi uvicorn

2. API indítása:

uvicorn api_server:app --host 127.0.0.1 --port 8010 --reload

Feltételezi, hogy a fájl neve api_server.py.

---

📡 API végpontok és használatuk

🔊 POST /play

Hangfájl lejátszása.

Bemeneti JSON:

{
  "file_path": "/path/to/audio.wav",
  "start_ms": 0,
  "volume": 100,
  "start_at": 1721981243.0
}

Kulcs	Típus	Alapértelmezett	Leírás
file_path	string	–	A lejátszandó WAV fájl elérési útja
start_ms	int	0	Hanyadik milliszekundumtól induljon a lejátsás
volume	int	100	Kezdő hangerő 0–100 között
start_at	float	None	Opcionális abszolút Unix timestamp, mikor induljon

Példa válasz:

{
  "id": "thread_001",
  "status": "started"
}

---

⏹️ POST /stop

Lejátszás leállítása adott azonosító alapján.

Bemeneti JSON:

{
  "id": "thread_001"
}

Kulcs	Típus	Leírás
id	string	A lejátszási szál azonosítója

Példa válasz:

{
  "status": "stopped",
  "id": "thread_001"
}

---

🔉 POST /volume

Hangerő módosítása egy aktív lejátszási szálhoz.

Bemeneti JSON:

{
  "id": "thread_001",
  "volume": 80
}

Kulcs	Típus	Leírás
id	string	A lejátszási szál azonosítója
volume	int	Új hangerő érték 0–100 között

Példa válasz:

{
  "status": "volume_changed",
  "id": "thread_001",
  "volume": 80
}

---

📊 GET /status

Jelenlegi rendszerállapot lekérdezése.

Nincs bemenet.

Példa válasz:

{
  "active_threads": [
    {
      "id": "thread_001",
      "file_path": "/path/to/audio.wav",
      "position_ms": 23456,
      "volume": 80
    }
  ]
}

---

🧩 Modulok leírása

• PlayRequest: lejátszási paramétereket tartalmaz (útvonal, időzítés, hangerő).
• ControlRequest: szálazonosító alapján vezérlő parancsokat küld.
• VolumeRequest: hangerő szabályozásához használt modell.
• send_socket_command(): TCP socket kapcsolaton küldi a parancsokat a háttér lejátszó processznek.

---

⚠️ Hibakezelés

Ha a socket kapcsolat sikertelen, az API 500 Internal Server Error válasszal tér vissza, a kivétel szöveges részletével a detail mezőben.

---

📌 Megjegyzés

A rendszer feltételezi, hogy egy külön háttérben futó socket szerver (lejátszó) elérhető a 127.0.0.1:9999 címen, amely értelmezi a "action" mezővel ellátott JSON parancsokat.

---

🛠️ Fejlesztési lehetőségek

• További vezérlők: PAUSE, RESUME, SEEK
• Felhasználói autentikáció
• Webes felület a REST API-hoz