⚙️ 🤖 Mitschrift über zentonic-transcribe: Client für asynchrone API (zpub transcribe) #172

Open
opened 2026-11-16 15:13:34 +01:00 by holm · 4 comments
Owner
Dimension Bewertung Einschätzung
Aufwand ████░░░░░░ Mittel — Client für eine asynchrone API, Ablage als transcript.vtt
Nutzen ███████░░░ Hoch — Mitschrift ohne Handarbeit, Player/Suche nutzen sie schon (#145)
Bruchhäufigkeit ████░░░░░░ Mittel — hängt an Erreichbarkeit der KI-Maschine
Dringlichkeit ██░░░░░░░░ Niedrig — wartet auf das Projekt zentonic-transcribe

Auftrag

Holm 2026-11-16: „zentonic-transcribe muss separates projekt werden. das laeuft auf ner ki maschine. da werfen wir was auf dessen api und bekommen auf anfrage irgendwann was zurück. anders gehts nicht.“

Abgrenzung

  • zentonic-transcribe (eigenes Projekt, KI-Maschine): nimmt Audio entgegen, transkribiert (Whisper), liefert auf Anfrage das Ergebnis. Asynchron: Auftrag rein → Job-ID → später abholen.
  • Publisher (dieses Issue): nur Client. Kein Whisper, keine Laufzeit-Annahmen über die KI-Maschine.

Vorschlag Publisher-Seite (Schnittstelle wartet auf zentonic-transcribe)

zpub transcribe submit <tenant> <slug>    # Audio hochladen, Job-ID in episode.cache.json
zpub transcribe fetch  <tenant> [<slug>]  # fertige Jobs abholen → episodes/<slug>/transcript.vtt
zpub transcribe status <tenant>           # offene Jobs
  • Nie überschreiben: vorhandene transcript.vtt bleibt, neue nur mit --force bzw. als transcript.new.vtt.
  • Endpunkt und Token aus der Tenant- bzw. Benutzer-Config, Token nie im Repo.
  • KI-Maschine aus (Normalfall) → submit meldet „nicht erreichbar“, Exit ≠ 0, nichts halb geschrieben.
  • Werkzeuge: bash, curl, jq. Kein Python.

Abnahme

  • API-Vertrag mit zentonic-transcribe abgestimmt (Endpunkte, Job-Status, Format VTT)
  • submit/fetch/status gegen die echte API, eine Folge mit realer Dateigröße
  • fetch legt transcript.vtt ab, Build zeigt die Mitschrift
  • Doku docs/episode-format.md (Mitschrift), docs/transcribe.md

🤖 angelegt von Claude claude2604 (API/Token holm)

| Dimension | Bewertung | Einschätzung | |---|---|---| | Aufwand | `████░░░░░░` | Mittel — Client für eine asynchrone API, Ablage als transcript.vtt | | Nutzen | `███████░░░` | Hoch — Mitschrift ohne Handarbeit, Player/Suche nutzen sie schon (#145) | | Bruchhäufigkeit | `████░░░░░░` | Mittel — hängt an Erreichbarkeit der KI-Maschine | | Dringlichkeit | `██░░░░░░░░` | Niedrig — wartet auf das Projekt zentonic-transcribe | ## Auftrag Holm 2026-11-16: „zentonic-transcribe muss separates projekt werden. das laeuft auf ner ki maschine. da werfen wir was auf dessen api und bekommen auf anfrage irgendwann was zurück. anders gehts nicht.“ ## Abgrenzung - **zentonic-transcribe** (eigenes Projekt, KI-Maschine): nimmt Audio entgegen, transkribiert (Whisper), liefert auf Anfrage das Ergebnis. Asynchron: Auftrag rein → Job-ID → später abholen. - **Publisher (dieses Issue):** nur Client. Kein Whisper, keine Laufzeit-Annahmen über die KI-Maschine. ## Vorschlag Publisher-Seite (Schnittstelle wartet auf zentonic-transcribe) ``` zpub transcribe submit <tenant> <slug> # Audio hochladen, Job-ID in episode.cache.json zpub transcribe fetch <tenant> [<slug>] # fertige Jobs abholen → episodes/<slug>/transcript.vtt zpub transcribe status <tenant> # offene Jobs ``` - Nie überschreiben: vorhandene `transcript.vtt` bleibt, neue nur mit `--force` bzw. als `transcript.new.vtt`. - Endpunkt und Token aus der Tenant- bzw. Benutzer-Config, Token nie im Repo. - KI-Maschine aus (Normalfall) → `submit` meldet „nicht erreichbar“, Exit ≠ 0, nichts halb geschrieben. - Werkzeuge: bash, curl, jq. Kein Python. ## Abnahme - [ ] API-Vertrag mit zentonic-transcribe abgestimmt (Endpunkte, Job-Status, Format VTT) - [ ] submit/fetch/status gegen die echte API, eine Folge mit realer Dateigröße - [ ] fetch legt transcript.vtt ab, Build zeigt die Mitschrift - [ ] Doku docs/episode-format.md (Mitschrift), docs/transcribe.md > 🤖 angelegt von Claude claude2604 (API/Token holm)
Author
Owner

Vorschlag API-Vertrag aus Client-Sicht (Eingabe für zentonic-transcribe)

Holm 2026-11-16: Repo Zentonic/zentonic-transcribe freigegeben (15a, Frage 68 bei thinker00). Was der Publisher als Client braucht — Entscheidung liegt beim neuen Projekt:

Aufruf Zweck Antwort
POST /jobs (multipart: Audio + lang, optional speakers) Auftrag 202 {id, status: "queued"}
GET /jobs/{id} Stand {id, status: queued|running|done|failed, progress?, error?}
GET /jobs/{id}/result.vtt Ergebnis 200 text/vtt (WebVTT, <v Sprecher> optional), 404 solange nicht fertig
GET /health KI-Maschine an? 200
  • Idempotenz: gleicher Upload (sha256) → gleiche Job-ID statt Doppelarbeit; Client schickt X-Content-SHA256.
  • Großdateien: Master-WAV/MP3 bis einige hundert MB; Upload abbrechbar/wiederholbar.
  • Aufbewahrung: Ergebnis mindestens 30 Tage abholbar; Audio nach Fertigstellung löschen.
  • Auth: ein Token je Client (Header), kein Klartext im Repo.
  • Normalfall „Maschine aus“: Client prüft /health, meldet „nicht erreichbar“ und schreibt nichts.
  • Format-Anforderungen des Publishers an die VTT: siehe docs/episode-format.md „Mitschrift“ (Player #145, Linse #159).

🤖 angelegt von Claude claude2604 (API/Token holm)

## Vorschlag API-Vertrag aus Client-Sicht (Eingabe für zentonic-transcribe) Holm 2026-11-16: Repo `Zentonic/zentonic-transcribe` freigegeben (15a, Frage 68 bei thinker00). Was der Publisher als Client braucht — Entscheidung liegt beim neuen Projekt: | Aufruf | Zweck | Antwort | |---|---|---| | `POST /jobs` (multipart: Audio + `lang`, optional `speakers`) | Auftrag | `202 {id, status: "queued"}` | | `GET /jobs/{id}` | Stand | `{id, status: queued\|running\|done\|failed, progress?, error?}` | | `GET /jobs/{id}/result.vtt` | Ergebnis | `200 text/vtt` (WebVTT, `<v Sprecher>` optional), `404` solange nicht fertig | | `GET /health` | KI-Maschine an? | `200` | - **Idempotenz:** gleicher Upload (sha256) → gleiche Job-ID statt Doppelarbeit; Client schickt `X-Content-SHA256`. - **Großdateien:** Master-WAV/MP3 bis einige hundert MB; Upload abbrechbar/wiederholbar. - **Aufbewahrung:** Ergebnis mindestens 30 Tage abholbar; Audio nach Fertigstellung löschen. - **Auth:** ein Token je Client (Header), kein Klartext im Repo. - **Normalfall „Maschine aus“:** Client prüft `/health`, meldet „nicht erreichbar“ und schreibt nichts. - Format-Anforderungen des Publishers an die VTT: siehe `docs/episode-format.md` „Mitschrift“ (Player #145, Linse #159). > 🤖 angelegt von Claude claude2604 (API/Token holm)
Author
Owner

Stand Feierabend 2026-11-16

  • Session c2604-zentonic-transcribe läuft (thinker00 17:15) und meldet den beschlossenen API-Vertrag per Datei an c2604-zentonic-publisher.
  • Nächster Schritt: Client gegen den Vertrag bauen (Frage 17 an Holm: gleich gegen eine nachgebaute Schnittstelle oder erst gegen die echte).
  • Offen: Holms Antwort auf 17, Vertrag von zentonic-transcribe.

🤖 angelegt von Claude claude2604 (API/Token holm)

## Stand Feierabend 2026-11-16 - Session `c2604-zentonic-transcribe` läuft (thinker00 17:15) und meldet den beschlossenen API-Vertrag per Datei an c2604-zentonic-publisher. - Nächster Schritt: Client gegen den Vertrag bauen (Frage 17 an Holm: gleich gegen eine nachgebaute Schnittstelle oder erst gegen die echte). - Offen: Holms Antwort auf 17, Vertrag von zentonic-transcribe. > 🤖 angelegt von Claude claude2604 (API/Token holm)
Author
Owner

Beschluss API-Vertrag v1 (zentonic-transcribe)

Vertrag: docs/api.md auf dev (Zentonic/zentonic-transcribe#2, API-Vertrag v1). Dienst läuft lokal (Zentonic/zentonic-transcribe#3, Dienst-Gerüst): echter Lauf über die API, Podcast-MP3 9:21 min / 10 MB → VTT in 49 s (whisper.cpp Vulkan, large-v3-turbo, c1b1).

Übernommen aus dem Vorschlag

  • POST /v1/jobs → 202 {id, status: "queued", …}, GET /v1/jobs/<id>, GET /v1/jobs/<id>/result.vtt, GET /v1/health (ohne Auth)
  • Idempotenz per X-Content-SHA256: gleiche Datei + Sprache + Sprecher → gleiche Job-ID (200, "duplicate": true)
  • Token je Client (Authorization: Bearer), Client-Name steht im Job
  • Ergebnis 30 Tage abholbar, Audio nach dem Lauf gelöscht
  • Normalfall „Maschine aus“: Client meldet „nicht erreichbar“, Exit ≠ 0

Abweichungen (mit Grund)

Vorschlag Beschluss Grund
multipart roher Body, curl --data-binary @datei streamt große Dateien, kein Multipart-Parser nötig
404 solange nicht fertig 409 not_ready, Retry-After: 60 404 heißt „Job unbekannt“
lang ?language= (Vorgabe de, auto) —
speakers (Diarisierung) ?speaker=<Name> je Spur, Cues mit <v Name> Whisper erkennt keine Sprecher; Mehrspur = Diarisierung gratis, Client führt VTTs zusammen
progress? entfällt in v1; position in der Warteschlange whisper-cli liefert keinen verlässlichen Fortschritt
Upload fortsetzen Neustart des Uploads, Dedup verhindert Doppelarbeit Resume braucht Protokoll, kein Nutzen bei LAN

Zusätzlich: result.json (Segmente), result.txt, GET /v1/jobs?status=…&ref=…, DELETE /v1/jobs/<id>, ?ref= als freier Bezug (z. B. zentonic/<slug>), Fehlerformat {"error": {"code", "message"}}.

VTT: WEBVTT, Zeitmarken HH:MM:SS.mmm, ein Cue je Segment; passt zu docs/episode-format.md „Mitschrift“.

Für die Client-Entwicklung

Dienst ohne Modell (ZT_BACKEND=dummy, ein Dummy-Segment je 5 s) und tools/smoke.sh als curl-Referenz: README im Repo, Abschnitt „Aufruf“. Offen auf Dienstseite: Phantomtext bei Musik-Intro/Outro (Zentonic/zentonic-transcribe#4, Whisper-Halluzinationen), KI-Maschine als Host (Zentonic/zentonic-transcribe#1, EPIC).

🤖 angelegt von Claude claude2604 (API/Token holm)

## Beschluss API-Vertrag v1 (zentonic-transcribe) Vertrag: [`docs/api.md`](https://forgejo.mueller.network/Zentonic/zentonic-transcribe/src/branch/dev/docs/api.md) auf `dev` ([Zentonic/zentonic-transcribe#2](https://forgejo.mueller.network/Zentonic/zentonic-transcribe/issues/2), API-Vertrag v1). Dienst läuft lokal ([Zentonic/zentonic-transcribe#3](https://forgejo.mueller.network/Zentonic/zentonic-transcribe/issues/3), Dienst-Gerüst): echter Lauf über die API, Podcast-MP3 9:21 min / 10 MB → VTT in 49 s (whisper.cpp Vulkan, large-v3-turbo, c1b1). ### Übernommen aus dem Vorschlag - `POST /v1/jobs` → `202 {id, status: "queued", …}`, `GET /v1/jobs/<id>`, `GET /v1/jobs/<id>/result.vtt`, `GET /v1/health` (ohne Auth) - Idempotenz per `X-Content-SHA256`: gleiche Datei + Sprache + Sprecher → gleiche Job-ID (`200`, `"duplicate": true`) - Token je Client (`Authorization: Bearer`), Client-Name steht im Job - Ergebnis 30 Tage abholbar, Audio nach dem Lauf gelöscht - Normalfall „Maschine aus“: Client meldet „nicht erreichbar“, Exit ≠ 0 ### Abweichungen (mit Grund) | Vorschlag | Beschluss | Grund | |---|---|---| | multipart | roher Body, `curl --data-binary @datei` | streamt große Dateien, kein Multipart-Parser nötig | | `404` solange nicht fertig | `409 not_ready`, `Retry-After: 60` | `404` heißt „Job unbekannt“ | | `lang` | `?language=` (Vorgabe `de`, `auto`) | — | | `speakers` (Diarisierung) | `?speaker=<Name>` je Spur, Cues mit `<v Name>` | Whisper erkennt keine Sprecher; Mehrspur = Diarisierung gratis, Client führt VTTs zusammen | | `progress?` | entfällt in v1; `position` in der Warteschlange | whisper-cli liefert keinen verlässlichen Fortschritt | | Upload fortsetzen | Neustart des Uploads, Dedup verhindert Doppelarbeit | Resume braucht Protokoll, kein Nutzen bei LAN | Zusätzlich: `result.json` (Segmente), `result.txt`, `GET /v1/jobs?status=…&ref=…`, `DELETE /v1/jobs/<id>`, `?ref=` als freier Bezug (z. B. `zentonic/<slug>`), Fehlerformat `{"error": {"code", "message"}}`. VTT: `WEBVTT`, Zeitmarken `HH:MM:SS.mmm`, ein Cue je Segment; passt zu `docs/episode-format.md` „Mitschrift“. ### Für die Client-Entwicklung Dienst ohne Modell (`ZT_BACKEND=dummy`, ein Dummy-Segment je 5 s) und `tools/smoke.sh` als curl-Referenz: README im Repo, Abschnitt „Aufruf“. Offen auf Dienstseite: Phantomtext bei Musik-Intro/Outro ([Zentonic/zentonic-transcribe#4](https://forgejo.mueller.network/Zentonic/zentonic-transcribe/issues/4), Whisper-Halluzinationen), KI-Maschine als Host ([Zentonic/zentonic-transcribe#1](https://forgejo.mueller.network/Zentonic/zentonic-transcribe/issues/1), EPIC). > 🤖 angelegt von Claude claude2604 (API/Token holm)
Author
Owner

Dienst läuft: zentonic-transcribe v0.1.0 auf c1b1

Holm 1c: c1b1 ist Übergangs-Host, bis die KI-Maschine steht (Zentonic/zentonic-transcribe#5, c1b1 als Übergangs-Host).

  • URL: http://127.0.0.1:8765 (nur lokal auf c1b1), /v1/health zeigt "build": "v0.1.0"
  • Token zur Laufzeit lesen: PASSWORD_STORE_DIR=/home/holm/.zenagent-store pass show zentonic/transcribe-token-publisher (Maschinen-Store, ohne Passphrase); Client-Name im Job: publisher
  • Gemessen: MP3 9:21 min → VTT in 42 s, mit VAD (kein Phantomtext bei Musik)
  • Schläft c1b1, ist der Dienst weg — das ist der Fall „nicht erreichbar“ aus dem Vertrag.

🤖 angelegt von Claude claude2604 (API/Token holm)

## Dienst läuft: zentonic-transcribe v0.1.0 auf c1b1 Holm 1c: c1b1 ist Übergangs-Host, bis die KI-Maschine steht ([Zentonic/zentonic-transcribe#5](https://forgejo.mueller.network/Zentonic/zentonic-transcribe/issues/5), c1b1 als Übergangs-Host). - URL: `http://127.0.0.1:8765` (nur lokal auf c1b1), `/v1/health` zeigt `"build": "v0.1.0"` - Token zur Laufzeit lesen: `PASSWORD_STORE_DIR=/home/holm/.zenagent-store pass show zentonic/transcribe-token-publisher` (Maschinen-Store, ohne Passphrase); Client-Name im Job: `publisher` - Gemessen: MP3 9:21 min → VTT in 42 s, mit VAD (kein Phantomtext bei Musik) - Schläft c1b1, ist der Dienst weg — das ist der Fall „nicht erreichbar“ aus dem Vertrag. > 🤖 angelegt von Claude claude2604 (API/Token holm)
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
Zentonic/zentonic-publisher#172
No description provided.