docs: address week-1 onboarding feedback#91
Conversation
- API reference: Create Model (POST /model) response now shows train_mode
as const "fast" (TTS-only); GET /model/{id} and the shared model schema
default to "fast" while still allowing "full" for non-TTS models. Fixes
the stale "full" example in the clone/create model reference.
- Emotion Control: document the [emphasis] tone marker (previously only in
the changelog and models overview), with usage example.
- Emotion Control: move Tone Markers, Audio Effects and Special Effects out
from under "Complete Emotion Reference" into a new "Sound & Delivery
Markers" section, since these are not emotions.
- Real-time streaming + TTS: clarify latency defaults. The raw HTTP/WebSocket
API defaults to "normal" (quality-tuned, high time-to-first-audio) while
the Python SDK defaults to "balanced"; add a warning and a per-surface
support matrix so real-time users (e.g. via LiveKit) set balanced/low.
Note: openapi.json is regenerated from platform-api; the durable train_mode
fix also needs platform-api apps/models/schemas.py updated (follow-up).
|
Important Review skippedDraft detected. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
openapi.json is regenerated from https://api.fish.audio/openapi.json and CI (check-openapi) enforces the committed file matches that output. The train_mode fast/full fix must land in platform-api and be deployed so the live spec emits it; hand-editing the generated file here cannot pass CI. Tracking train_mode as a platform-api follow-up.
1 participant
Summary
Documentation fixes from Cale's week-1 "fresh eyes" onboarding feedback. Three independent, low-risk docs fixes.
Opened as a draft for review before merge.
Changes
[emphasis]documented — previously only mentioned in the changelog and models overview. Added as a Tone Marker with a usage example on the Emotion Control page.latencytonormal(the Python SDK defaults tobalanced). Added a warning and a per-surface support matrix so real-time users (e.g. via the LiveKit plugin) know to setbalanced/low.Dropped from this PR —
train_modefix moved to backendThe Create Model reference advertises
train_mode: "full"in the response, but TTS creation only supports"fast". I originally fixed this inopenapi.json, butopenapi.jsonis a generated artifact —scripts/update-openapi.mjspulls it fromhttps://api.fish.audio/openapi.json, and thecheck-openapiCI job regenerates it and fails if the committed file differs. A hand-edit here can never pass CI.The fix must land in the backend and be deployed:
platform-api/apps/models/schemas.py:103—train_mode: Literal["fast", "full"] = "full"(the response model that emitsfull).Once deployed, the docs spec will pick up
fastautomatically on the next regen. Tracking separately.Other follow-ups (not in this PR)
emotions.mdxadvises "Add appropriate text after sound effects (e.g., 'Ha ha' after laughing)" — likely leftover S1 guidance. Left unchanged pending confirmation of actual S2 behavior.Validation
check-openapi, Mintlify deployment, and CodeRabbit all pass. Mintlify preview built successfully.