@huynle/hub 0.11.0 → 0.11.1

package/packages/protocol/schema/api/v1/speech.json

@@ -0,0 +1,492 @@
+{
+  "paths": {
+    "/api/v1/transcribe": {
+      "post": {
+        "operationId": "transcribe",
+        "tags": [
+          "speech"
+        ],
+        "x-hub-access": "user",
+        "summary": "Speech to text",
+        "description": "Transcribes a recording with the user's speech-to-text settings. The body is the audio itself, at most 10 MB by default (the hub's HUB_MAX_AUDIO_BYTES); its Content-Type names the format (parameters such as `;codecs=opus` are ignored). Fails with 415 (code invalid) for a Content-Type the hub does not know, 400 invalid for an empty recording, 413 too_large over the limit, and 502 upstream_failed when the speech provider fails.",
+        "parameters": [
+          {
+            "name": "x-hub-recording",
+            "in": "header",
+            "required": false,
+            "description": "Voice recording (docs/voice-recording.md): the ID of a recording of this user that this request belongs to. Optional; without it nothing is recorded.",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "x-hub-segment",
+            "in": "header",
+            "required": false,
+            "description": "Voice recording: the segment number of this audio in the recording named by x-hub-recording; the segment is then kept for the recording (no second upload).",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "audio/webm": {
+              "schema": {
+                "type": "string",
+                "format": "binary"
+              }
+            },
+            "audio/mp4": {
+              "schema": {
+                "type": "string",
+                "format": "binary"
+              }
+            },
+            "audio/x-m4a": {
+              "schema": {
+                "type": "string",
+                "format": "binary"
+              }
+            },
+            "audio/m4a": {
+              "schema": {
+                "type": "string",
+                "format": "binary"
+              }
+            },
+            "audio/aac": {
+              "schema": {
+                "type": "string",
+                "format": "binary"
+              }
+            },
+            "audio/ogg": {
+              "schema": {
+                "type": "string",
+                "format": "binary"
+              }
+            },
+            "audio/wav": {
+              "schema": {
+                "type": "string",
+                "format": "binary"
+              }
+            },
+            "audio/x-wav": {
+              "schema": {
+                "type": "string",
+                "format": "binary"
+              }
+            },
+            "audio/wave": {
+              "schema": {
+                "type": "string",
+                "format": "binary"
+              }
+            },
+            "audio/mpeg": {
+              "schema": {
+                "type": "string",
+                "format": "binary"
+              }
+            },
+            "audio/mp3": {
+              "schema": {
+                "type": "string",
+                "format": "binary"
+              }
+            },
+            "audio/flac": {
+              "schema": {
+                "type": "string",
+                "format": "binary"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "The text heard (empty when nothing was said).",
+            "headers": {
+              "x-hub-recording-audio": {
+                "description": "With x-hub-recording and x-hub-segment: what became of the segment's audio.",
+                "schema": {
+                  "type": "string",
+                  "x-hub-known": [
+                    "stored",
+                    "skipped-cap",
+                    "failed",
+                    "off"
+                  ]
+                }
+              }
+            },
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Transcript"
+                }
+              }
+            }
+          },
+          "default": {
+            "$ref": "#/components/responses/Error"
+          }
+        }
+      }
+    },
+    "/api/v1/speak": {
+      "post": {
+        "operationId": "speak",
+        "tags": [
+          "speech"
+        ],
+        "x-hub-access": "user",
+        "summary": "Text to speech",
+        "description": "Speaks text with the user's text-to-speech settings. The text is made speakable first (Markdown and code blocks dropped, links named) and cut to the hub's limit (800 characters by default, HUB_MAX_SPEECH_CHARS). The audio is streamed as the provider makes it. Fails with 400 invalid when nothing speakable is left, and 502 upstream_failed when the speech provider fails before the audio starts.",
+        "parameters": [
+          {
+            "name": "x-hub-recording",
+            "in": "header",
+            "required": false,
+            "description": "Voice recording (docs/voice-recording.md): the ID of a recording of this user that this request belongs to. Optional; without it nothing is recorded.",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "x-hub-tts-ref",
+            "in": "header",
+            "required": false,
+            "description": "Voice recording: which reply sentence this is, `<messageID>:<ordinal>:<seq>:<i>`.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/SpeakRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "The speech, MP3.",
+            "content": {
+              "audio/mpeg": {
+                "schema": {
+                  "type": "string",
+                  "format": "binary"
+                }
+              }
+            }
+          },
+          "default": {
+            "$ref": "#/components/responses/Error"
+          }
+        }
+      }
+    },
+    "/api/v1/settings/speech": {
+      "get": {
+        "operationId": "getSpeechSettings",
+        "tags": [
+          "speech"
+        ],
+        "x-hub-access": "user",
+        "summary": "The user's speech settings",
+        "description": "The speech-to-text and text-to-speech settings that apply to the user, and whether each direction can work. Keys are never shown: only whether one is set, where it comes from and, for the caller's own key (or any key on a pairing-mode hub), its last four characters. On a hub with several users (OIDC), a user who is not the pairing-mode owner also gets `scope: \"user\"`, the server default and their own saved fields.",
+        "responses": {
+          "200": {
+            "description": "The effective settings.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/SpeechSettings"
+                }
+              }
+            }
+          },
+          "default": {
+            "$ref": "#/components/responses/Error"
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "schemas": {
+      "Transcript": {
+        "type": "object",
+        "required": [
+          "text"
+        ],
+        "properties": {
+          "text": {
+            "type": "string"
+          }
+        }
+      },
+      "SpeakRequest": {
+        "type": "object",
+        "required": [
+          "text"
+        ],
+        "properties": {
+          "text": {
+            "type": "string",
+            "description": "What to say. Markdown is fine: it is made speakable."
+          }
+        }
+      },
+      "SpeechSettings": {
+        "type": "object",
+        "required": [
+          "stt",
+          "tts",
+          "voiceHints",
+          "ready"
+        ],
+        "properties": {
+          "stt": {
+            "$ref": "#/components/schemas/SpeechToTextSettings"
+          },
+          "tts": {
+            "$ref": "#/components/schemas/TextToSpeechSettings"
+          },
+          "voiceHints": {
+            "type": "object",
+            "description": "Voices known to work, keyed by a model ID prefix (a voice belongs to its model).",
+            "additionalProperties": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
+          },
+          "ready": {
+            "$ref": "#/components/schemas/SpeechReadiness"
+          },
+          "scope": {
+            "type": "string",
+            "description": "\"user\": a user's own view on a hub with several users, with `default` and `user`. Absent for the server default's view (the owner of a pairing-mode hub).",
+            "x-hub-known": [
+              "user"
+            ]
+          },
+          "default": {
+            "$ref": "#/components/schemas/SpeechDefaultSettings"
+          },
+          "user": {
+            "$ref": "#/components/schemas/OwnSpeechSettings"
+          }
+        }
+      },
+      "SpeechToTextSettings": {
+        "type": "object",
+        "required": [
+          "provider",
+          "model",
+          "apiKey"
+        ],
+        "properties": {
+          "provider": {
+            "type": "string",
+            "x-hub-known": [
+              "openrouter",
+              "openai-compatible"
+            ]
+          },
+          "model": {
+            "type": "string"
+          },
+          "baseURL": {
+            "type": "string",
+            "description": "Present when one is configured."
+          },
+          "language": {
+            "type": "string",
+            "description": "The spoken language's code (e.g. en), when one is set."
+          },
+          "apiKey": {
+            "$ref": "#/components/schemas/SpeechKey"
+          }
+        }
+      },
+      "TextToSpeechSettings": {
+        "type": "object",
+        "required": [
+          "provider",
+          "model",
+          "voice",
+          "apiKey"
+        ],
+        "properties": {
+          "provider": {
+            "type": "string",
+            "x-hub-known": [
+              "openrouter",
+              "openai-compatible"
+            ]
+          },
+          "model": {
+            "type": "string"
+          },
+          "voice": {
+            "type": "string"
+          },
+          "baseURL": {
+            "type": "string",
+            "description": "Present when one is configured."
+          },
+          "speed": {
+            "type": "number",
+            "description": "0.5 to 2, when set."
+          },
+          "apiKey": {
+            "$ref": "#/components/schemas/SpeechKey"
+          }
+        }
+      },
+      "SpeechKey": {
+        "type": "object",
+        "required": [
+          "set",
+          "source"
+        ],
+        "description": "A speech provider key, masked.",
+        "properties": {
+          "set": {
+            "type": "boolean"
+          },
+          "last4": {
+            "type": "string",
+            "description": "Its last four characters: only for a key of 12 characters or more that the caller may see."
+          },
+          "source": {
+            "type": "string",
+            "description": "user: the user's own; settings: the saved server default; config: the hub's configuration file; env: the hub's environment; none: no key.",
+            "x-hub-known": [
+              "user",
+              "settings",
+              "config",
+              "env",
+              "none"
+            ]
+          }
+        }
+      },
+      "SpeechReadiness": {
+        "type": "object",
+        "required": [
+          "stt",
+          "tts"
+        ],
+        "properties": {
+          "stt": {
+            "type": "boolean",
+            "description": "Speech-to-text can work (OpenRouter has a key, another provider a base URL)."
+          },
+          "tts": {
+            "type": "boolean",
+            "description": "Text-to-speech can work."
+          },
+          "reason": {
+            "type": "string",
+            "description": "What is missing, for people; absent when both are ready."
+          }
+        }
+      },
+      "SpeechDefaultSettings": {
+        "type": "object",
+        "required": [
+          "stt",
+          "tts"
+        ],
+        "description": "The server default under the user's own settings.",
+        "properties": {
+          "stt": {
+            "$ref": "#/components/schemas/SpeechToTextSettings"
+          },
+          "tts": {
+            "$ref": "#/components/schemas/TextToSpeechSettings"
+          }
+        }
+      },
+      "OwnSpeechSettings": {
+        "type": "object",
+        "required": [
+          "stt",
+          "tts"
+        ],
+        "description": "The fields the user saved; absent ones come from the server default.",
+        "properties": {
+          "stt": {
+            "$ref": "#/components/schemas/OwnSpeechToTextSettings"
+          },
+          "tts": {
+            "$ref": "#/components/schemas/OwnTextToSpeechSettings"
+          }
+        }
+      },
+      "OwnSpeechToTextSettings": {
+        "type": "object",
+        "properties": {
+          "provider": {
+            "type": "string",
+            "x-hub-known": [
+              "openrouter",
+              "openai-compatible"
+            ]
+          },
+          "model": {
+            "type": "string"
+          },
+          "baseURL": {
+            "type": "string"
+          },
+          "language": {
+            "type": "string"
+          },
+          "apiKey": {
+            "$ref": "#/components/schemas/SpeechKey"
+          }
+        }
+      },
+      "OwnTextToSpeechSettings": {
+        "type": "object",
+        "properties": {
+          "provider": {
+            "type": "string",
+            "x-hub-known": [
+              "openrouter",
+              "openai-compatible"
+            ]
+          },
+          "model": {
+            "type": "string"
+          },
+          "voice": {
+            "type": "string"
+          },
+          "baseURL": {
+            "type": "string"
+          },
+          "speed": {
+            "type": "number"
+          },
+          "apiKey": {
+            "$ref": "#/components/schemas/SpeechKey"
+          }
+        }
+      }
+    }
+  }
+}