chore: add miscellaneous comments

Fedir Zadniprovskyi · fedirz · commit 2db1d58ba77f · 2025-06-30T07:58:58.000-07:00
diff --git a/src/speaches/api_types.py b/src/speaches/api_types.py
@@ -33,17 +33,20 @@ def offset(self, seconds: float) -> None:
 
 # https://github.com/openai/openai-openapi/blob/master/openapi.yaml#L10938
 class TranscriptionSegment(BaseModel):
+    avg_logprob: float
+    compression_ratio: float
+    end: float
     id: int
+    no_speech_prob: float
     seek: int
     start: float
-    end: float
+    temperature: float
     text: str
     tokens: list[int]
-    temperature: float
-    avg_logprob: float
-    compression_ratio: float
-    no_speech_prob: float
-    words: list[TranscriptionWord] | None
+    words: (
+        list[TranscriptionWord] | None
+    )  # TODO: why is here? It's not a field defined in the [OpenAI API spec](https://platform.openai.com/docs/api-reference/audio/verbose-json-object)
+    # TODO: add `usage` field: https://platform.openai.com/docs/api-reference/audio/verbose-json-object#audio/verbose-json-object-usage
 
     @classmethod
     def from_faster_whisper_segments(
@@ -79,6 +82,8 @@ def from_faster_whisper_segments(
 # https://github.com/openai/openai-openapi/blob/master/openapi.yaml#L10924
 class CreateTranscriptionResponseJson(BaseModel):
     text: str
+    # NOTE: there's also a `logprobs` field it's only supported by non-whisper models, so we don't include it here (we can't `faster-whisper` doesn't provide it)
+    # TODO: add `usage` field: https://platform.openai.com/docs/api-reference/audio/json-object#audio/json-object-usage
 
     @classmethod
     def from_segments(cls, segments: list[TranscriptionSegment]) -> "CreateTranscriptionResponseJson":
@@ -88,6 +93,7 @@ def from_segments(cls, segments: list[TranscriptionSegment]) -> "CreateTranscrip
 # https://platform.openai.com/docs/api-reference/audio/verbose-json-object
 # https://github.com/openai/openai-openapi/blob/master/openapi.yaml#L11007
 class CreateTranscriptionResponseVerboseJson(BaseModel):
+    # NOTE: there's also a `logprobs` field it's only supported by non-whisper models, so we don't include it here (we can't `faster-whisper` doesn't provide it)
     task: str = "transcribe"
     language: str
     duration: float
