API Dokumentation – server.php

Stand: 13.08.2025

Letzte Änderungen

Kommentare (neu): Endpunkte add_comment, get_comments, delete_comment. Optional login-pflichtig via Server-Konfiguration.
5-Sterne-Bewertungen (neu): Endpunkte rate_video (Upsert 1–5) und get_rating (Durchschnitt, Anzahl, Verteilung, eigener Score).
POST + JSON-Body: POST-Endpunkte akzeptieren neben x-www-form-urlencoded auch application/json.
CORS erweitert: Erlaubte Methoden jetzt GET, POST, OPTIONS.
Kategorien aus *.info.json: Kategorien werden jetzt aus den JSON-Metadaten gelesen. Jedes Video hat category (erste Kategorie) und categories (volle Liste).
Kategorie-Filter: ?category= unterstützt eine kommagetrennte Liste (ANY-of), z. B. ?category=People%20%26%20Blogs,News.
Meta: availableCategories listet alle gefundenen Kategorien.
Per-Bibliothek-Caching: Cache-Version v6; Neuaufbau via ?refreshCache=1.
Zweite Bibliothek: media/yeeeh zusätzlich zu media/youtube. Auswahl über ?library=youtube|yeeeh|all (Standard: all).
Neues Feld: Jedes Video enthält "library" (Herkunftsbibliothek). IDs sind eindeutig pro Bibliothek.
Einzel-Video-Route: ?id=... liefert bei Browser-Aufruf OG-Metadaten + Redirect, bei AJAX JSON.
Filter & Suche: q (Volltext), tag (kommagetrennt), optional libraryFilter bei library=all.
Sortierung: sort=title|date und order=asc|desc.
Paginierung: itemsPerPage (1–200) und page (ab 1).
HTTP-Optimierung: Antworten setzen ETag und Last-Modified (304-Support).
Thumbnail-Auswahl: Es wird das größte Bild im Ordner verwendet.

Übersicht

server.php scannt Video-Ordner, verarbeitet Metadaten (*.info.json / description.txt) und stellt Inhalte als JSON bereit. Unterstützt werden zwei Bibliotheken – media/youtube und media/yeeeh – einzeln oder kombiniert. Es gibt Filterung (inkl. Kategorien aus JSON), Sortierung, Paginierung, CORS, ETag/Last-Modified sowie Caching und Logging. Zusätzlich bietet die Datei Aktions-Endpunkte (Login, Fortschritt) und neu Kommentare & Bewertungen.

API-Endpunkte

Basis-URL

GET https://taddl-hub.natsuk4sh1i.de/server/server.php

Query-Parameter

Parameter	Typ	Beschreibung
`library`	string	Wählt die Datenquelle: `youtube`, `yeeeh` oder `all` (Standard). Bei `all` werden beide Bibliotheken zusammengeführt.
`id`	string	Gibt ein einzelnes Video anhand seiner ID zurück. Optional kann `library` mitgegeben werden. Bei Browser-Aufruf liefert die API OG-Metadaten + Redirect; bei AJAX (`X-Requested-With: XMLHttpRequest`) JSON.
`q`	string	Volltextsuche in Titel, Beschreibung und Tags (case-insensitive).
`category`	string	Filtert nach Kategorien aus `.info.json` (case-insensitive). Unterstützt kommagetrennte* Werte (ANY-of). Beispiel: `?category=People%20%26%20Blogs,News`
`tag`	string	Filtert nach Tags. Kommagetrennte Liste, z. B. `tag=howto,beginner`.
`sort`	string	Sortiert nach `title` oder `date` (nutzt `upload_date` im ISO-Format).
`order`	string	Sortierrichtung: `asc` (Standard) oder `desc`.
`itemsPerPage`	integer	Anzahl der Videos pro Seite (1–200). Wenn nicht gesetzt, werden alle Treffer zurückgegeben.
`page`	integer	Seitenzahl (ab 1). Nur relevant, wenn `itemsPerPage` gesetzt ist.
`libraryFilter`	string	Optionaler zusätzlicher Filter auf `youtube` oder `yeeeh`, nützlich wenn `library=all` abgefragt wird.
`refreshCache`	boolean / string	Erzwingt Neuaufbau des Index-Caches für die gewählte(n) Bibliothek(en), z. B. `refreshCache=1`.

Hinweis Ältere Aliase aus früheren Versionen:

search → jetzt q
tags → jetzt tag
sortBy/sortDir → jetzt sort/order

Antwortformat

Listen-Antwort (JSON)

{
  "success": true,
  "data": {
    "videos": [
      {
        "id": "a1b2c3d4",
        "library": "youtube",
        "title": "Video Titel",
        "sources": [
          { "src": "media/youtube/Ordner/Datei.mp4", "type": "video/mp4" }
        ],
        "thumbnail": "media/youtube/Ordner/Datei.jpg",
        "description": "Video Beschreibung",
        "category": "People & Blogs",
        "categories": ["People & Blogs"],
        "upload_date": "2023-01-01",
        "tags": ["tag1", "tag2"]
      }
    ]
  },
  "meta": {
    "totalVideos": 50,
    "currentPage": 1,
    "totalPages": 5,
    "library": "all",
    "libraries": ["youtube", "yeeeh"],
    "filters": {
      "q": "einsteiger",
      "category": "People & Blogs,News",
      "tags": ["howto", "beginner"],
      "sort": "date",
      "order": "desc",
      "libraryFilter": null
    },
    "availableCategories": ["People & Blogs","News","Gaming"],
    "generatedAt": "2025-08-12T12:34:56Z"
  },
  "error": null
}

Einzel-Video (AJAX-JSON)

Wenn X-Requested-With: XMLHttpRequest gesetzt ist:

{
  "success": true,
  "data": {
    "id": "a1b2c3d4",
    "library": "yeeeh",
    "title": "Video Titel",
    "sources": [
      { "src": "media/yeeeh/Ordner/Datei.webm", "type": "video/webm" }
    ],
    "thumbnail": "media/yeeeh/Ordner/Datei.jpg",
    "description": "Beschreibung…",
    "category": "People & Blogs",
    "categories": ["People & Blogs","Comedy"],
    "upload_date": "2024-05-20",
    "tags": []
  },
  "meta": { "library": "yeeeh" },
  "error": null
}

Einzel-Video (Browser/OG + Redirect)

Bei normalem Browser-Aufruf (GET server.php?id=...) wird eine schmale HTML-Seite mit Open-Graph-Metadaten ausgeliefert und sofort nach video.php?id=...&library=... weitergeleitet.

Fehlerantwort

{
  "success": false,
  "error": "Fehlermeldung",
  "meta": { "library": "youtube" }
}

Funktionsweise

1. Bibliotheken

media/youtube und media/yeeeh werden unterstützt.
Mit ?library=youtube bzw. ?library=yeeeh können Inhalte separat abgefragt werden.
?library=all (Standard) führt beide zusammen; optional kann libraryFilter zusätzlich auf eine Bibliothek einschränken.
Jedes Video besitzt das Feld library; IDs sind pro Bibliothek stabil (md5(library:folder) gekürzt).

2. Caching & Conditional GET

Pro Bibliothek wird ein Index als JSON gecacht (Dateien wie .video_index_v6_youtube.json).
Der Cache wird beim ersten Aufruf erstellt und danach wiederverwendet.
Neuaufbau mit ?refreshCache=1 oder durch Erhöhen von $cacheVersion.
Antworten setzen ETag und Last-Modified (304 bei unverändertem Inhalt).

3. Video-Scanning

Scans die Unterordner auf erster Ebene in der jeweiligen Bibliothek.
Unterstützte Videoformate: mp4, mkv, ogv, webm, ogg.
Unterstützte Thumbnail-Formate: jpg, jpeg, png, gif.
Thumbnail-Auswahl: größtes Bild im Ordner (Auflösung, dann Dateigröße). Dateinamen müssen nicht mit dem Ordnernamen übereinstimmen.
Thumbnail-URLs escapen Leerzeichen und # (z. B. %20, %23), ohne Slashes zu verändern.

4. Metadaten

Liest *.info.json (yt-dl/yt-dlp) falls vorhanden.
Felder: title, upload_date (als ISO YYYY-MM-DD), description, tags, categories.
category ist die erste Kategorie aus categories (bequeme Anzeige/Legacy).
Fallback-Beschreibung aus description.txt im Ordner.
Standard-Thumbnail: media/default.jpg.

5. CORS & Logging

CORS: Access-Control-Allow-Origin: *, Methoden: GET, POST, OPTIONS.
Bei Cookie-basierten Sessions über Fremd-Domain: Origin statt * setzen und Access-Control-Allow-Credentials: true aktivieren; im Client credentials: 'include'.
Einfache Request-Logs in server.log.

Beispielaufrufe

Alle Videos (beide Bibliotheken):
```
GET server.php
```
Nur YouTube:
```
GET server.php?library=youtube
```
Nur Yeeeeh:
```
GET server.php?library=yeeeh
```
Nur eine Bibliothek aus kombinierten Ergebnissen filtern:
```
GET server.php?library=all&libraryFilter=yeeeh
```

Videos einer oder mehrerer Kategorien:

GET server.php?category=People%20%26%20Blogs,News

Suche:
```
GET server.php?q=einsteiger
```
Nach Tags filtern:
```
GET server.php?tag=howto,beginner
```

Sortiert & paginiert:

GET server.php?sort=date&order=desc&itemsPerPage=10&page=2

Einzelnes Video (AJAX JSON):

GET server.php?id=a1b2c3d4&library=yeeeh

Cache neu aufbauen:
```
GET server.php?refreshCache=1
```

API-Endpunkte – Aktionen

Basis-URL für Aktionen

GET/POST https://taddl-hub.natsuk4sh1i.de/server/server.php?action=...

Diese Endpunkte nutzen den action-Parameter, um serverseitige Funktionen wie Login, Fortschritt, Kommentare und Bewertungen bereitzustellen. Antworten sind JSON. POST akzeptiert application/x-www-form-urlencoded oder application/json (Body wird automatisch gemerged).

action	Methode	Beschreibung	Parameter	Auth
`login`	POST	Loggt einen Benutzer ein.	`username`, `password`	–
`logout`	POST	Beendet die aktuelle Session.	–	erforderlich (eingeloggt)
`upsert_progress`	POST	Speichert/aktualisiert den Wiedergabefortschritt eines Videos.	`video_id`, `library`, `position` (ms)	erforderlich
`get_progress_list`	GET	Listet alle gespeicherten Wiedergabefortschritte.	–	erforderlich
`delete_progress`	POST	Löscht den Wiedergabefortschritt für ein Video.	`video_id`, `library`	erforderlich
`clear_progress`	POST	Löscht alle gespeicherten Wiedergabefortschritte.	–	erforderlich
`get_online_users`	GET	Gibt eine Liste der aktuell online befindlichen Benutzer zurück.	–	–
`get_users`	GET	Listet alle Benutzer im System.	–	–
`add_comment`	POST	Fügt einem Video einen Kommentar hinzu.	`video_id` (8-stellige Hex-ID), `content` (1–2000 Zeichen)	abhängig Wenn Server-Konfig `commentsRequireLogin = true`: Login erforderlich.
`get_comments`	GET	Listet Kommentare zu einem Video (paginierbar).	`video_id` (erforderlich), `page` (≥1, Standard 1), `per_page` (1–100, Standard 20), `order` (`asc`\|`desc`, Standard `desc`)	–
`delete_comment`	POST	Soft-Delete eines Kommentars (setzt `deleted_at`).	`id` (Kommentar-ID)	Autor des Kommentars oder Admin
`rate_video`	POST	Setzt/aktualisiert die Bewertung (1–5) des aktuellen Nutzers/Gasts für ein Video.	`video_id` (erforderlich), `rating` (1–5)	abhängig Wenn Server-Konfig `ratingsRequireLogin = true`: Login erforderlich.
`get_rating`	GET	Gibt Rating-Aggregation für ein Video zurück.	`video_id` (erforderlich)	–

Antwortbeispiele – Kommentare

# Kommentar hinzufügen (JSON-Body)
POST /server/server.php?action=add_comment
Content-Type: application/json

{"video_id":"a1b2c3d4","content":"Tolles Video!"}

# Beispiel-Antwort
{
  "success": true,
  "data": {
    "id": 123,
    "video_id": "a1b2c3d4",
    "user_id": 42,
    "username": "alice",
    "content": "Tolles Video!"
  },
  "meta": null,
  "error": null
}

# Kommentare abrufen (Seite 1, 20 pro Seite, neueste zuerst)
GET /server/server.php?action=get_comments&video_id=a1b2c3d4&page=1&per_page=20&order=desc

# Beispiel-Antwort
{
  "success": true,
  "data": {
    "comments": [
      {
        "id": 123,
        "video_id": "a1b2c3d4",
        "user_id": 42,
        "username": "alice",
        "content": "Tolles Video!",
        "created_at": "2025-08-13 10:00:00",
        "updated_at": "2025-08-13 10:00:00"
      }
    ]
  },
  "meta": { "total": 37, "page": 1, "per_page": 20 },
  "error": null
}

Antwortbeispiele – Bewertungen

# 5 Sterne vergeben (Form-Encoded oder JSON)
POST /server/server.php?action=rate_video
Content-Type: application/json

{"video_id":"a1b2c3d4","rating":5}

# Beispiel-Antwort
{
  "success": true,
  "data": {
    "video_id": "a1b2c3d4",
    "average": 4.667,
    "count": 15,
    "userRating": 5,
    "distribution": { "1": 1, "2": 0, "3": 2, "4": 4, "5": 8 }
  },
  "error": null
}

# Rating abrufen
GET /server/server.php?action=get_rating&video_id=a1b2c3d4

# Beispiel-Antwort
{
  "success": true,
  "data": {
    "video_id": "a1b2c3d4",
    "average": 4.667,
    "count": 15,
    "userRating": 5,
    "distribution": { "1": 1, "2": 0, "3": 2, "4": 4, "5": 8 }
  },
  "error": null
}

Beispielaufrufe (cURL)

# Benutzer einloggen
curl -X POST \
  -d "username=testuser&password=geheim" \
  https://taddl-hub.natsuk4sh1i.de/server/server.php?action=login

# Fortschritt speichern
curl -X POST \
  -d "video_id=a1b2c3d4&library=youtube&position=123000" \
  https://taddl-hub.natsuk4sh1i.de/server/server.php?action=upsert_progress

# Kommentar hinzufügen (JSON)
curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"video_id":"a1b2c3d4","content":"Mega!"}' \
  https://taddl-hub.natsuk4sh1i.de/server/server.php?action=add_comment

# Kommentare abrufen
curl "https://taddl-hub.natsuk4sh1i.de/server/server.php?action=get_comments&video_id=a1b2c3d4&page=1&per_page=20&order=desc"

# Kommentar löschen
curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"id":123}' \
  "https://taddl-hub.natsuk4sh1i.de/server/server.php?action=delete_comment"

# 4 Sterne vergeben
curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"video_id":"a1b2c3d4","rating":4}' \
  "https://taddl-hub.natsuk4sh1i.de/server/server.php?action=rate_video"

# Rating abrufen
curl "https://taddl-hub.natsuk4sh1i.de/server/server.php?action=get_rating&video_id=a1b2c3d4"

# Alle Benutzer abrufen
curl "https://taddl-hub.natsuk4sh1i.de/server/server.php?action=get_users"

Hinweise zu Authentifizierung & Rechte

Standardmäßig arbeiten die Endpunkte mit PHP-Session (Cookie). Bei Cross-Origin-Aufrufen ggf. Access-Control-Allow-Credentials: true aktivieren und im Client Cookies mitsenden.
commentsRequireLogin und ratingsRequireLogin können serverseitig aktiviert werden (in server.php), um Kommentare/Bewertungen nur für eingeloggte Nutzer zuzulassen.
delete_comment erfordert Adminrechte oder Eigentümerschaft des Kommentars.
Bewertungen werden pro Nutzer (eingeloggt) oder pro Gast-IP (nicht eingeloggt) eindeutig gespeichert (Upsert).

Systemanforderungen

PHP 7.4 oder höher (empfohlen: PHP 8+)
Schreibrechte für das Verzeichnis der server.php (für Cache & Logs)
Leserechte für media/youtube und media/yeeeh
MySQL-Tabellen für Kommentare/Bewertungen: video_comments, video_ratings (siehe Migrationen)