Compositions documentation - #278
Open
Gawor270 wants to merge 11 commits into
Open
Conversation
New top-level docs section for the hosted composition service: concept overview (disambiguated from the client-side Smelter library), quick start, template authoring with the composition SDK and CLI, room composition, runtime events, an input/output guide, a scene-model explainer, and an API reference. The REST reference renders a sanitized preview OpenAPI spec via Scalar; the auth model and WebSocket event stream are documented in prose.
Replace the hand-written preview spec with one generated from the
service source, copied by scripts/update_api.sh (the source repo is
private, so it is cloned on demand instead of being a submodule) and
sanitized of internal-only fields. The committed spec comes from the
template-workers branch with the oneOf variant-title improvement
applied, matching what main will contain after the pending merge.
Align the docs with the actual API surface: templated outputs are
registered in a single multipart request to POST
.../output/{output_id}/template (config + template), not registered
first and uploaded after; rescaler takes a single child. Template code
samples are now type-checked by the build, with
@fishjam-cloud/composition linked from the js-server-sdk submodule.
CI's SUBMODULES_TOKEN covers the private source repo (same as the fishjam and room-manager submodules), so clone-on-demand is not needed. The repo has no semver release tags yet, so the submodule is checked out at a branch instead of the latest tag.
Contributor
There was a problem hiding this comment.
Pull request overview
Adds a new beta Smelter Cloud documentation section to the Docusaurus site, including concept docs, how-to guides, and a published OpenAPI/Scalar REST API reference.
Changes:
- Introduces new
docs/smelter/docs tree (overview, quick start, scenes, how-tos, API reference) and sidebar categories. - Publishes Smelter Cloud REST API docs via Scalar at
/api/smelter-cloud, backed by a committed OpenAPI JSON spec. - Updates tooling to fetch/copy the Smelter Cloud spec from a new submodule and links the local
@fishjam-cloud/compositionpackage for type-checkable examples.
Reviewed changes
Copilot reviewed 16 out of 18 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| yarn.lock | Adds workspace link entry for @fishjam-cloud/composition. |
| static/api/smelter-cloud-openapi.json | Adds committed Smelter Cloud OpenAPI 3.1 JSON spec for publishing. |
| spelling.txt | Adds rtmp to spellcheck allowlist. |
| scripts/update_api.sh | Adds branch-based submodule checkout and JSON spec sanitization/copy step. |
| package.json | Adds linked dependency on @fishjam-cloud/composition for examples/typechecking. |
| docusaurus.config.ts | Adds a Scalar instance to render the Smelter Cloud REST API reference page. |
| docs/smelter/what-is-smelter-cloud.mdx | Adds Smelter Cloud concept overview and navigation pointers. |
| docs/smelter/scenes.mdx | Documents video/audio scene model and live updates. |
| docs/smelter/quick-start.mdx | Adds end-to-end tutorial for creating/registering inputs/outputs and publishing. |
| docs/smelter/how-to/write-and-deploy-a-template.mdx | Adds template authoring/build/deploy guide including multipart upload endpoint. |
| docs/smelter/how-to/inputs-and-outputs.mdx | Summarizes supported input/output protocols and key fields. |
| docs/smelter/how-to/drive-a-template-with-events.mdx | Documents event delivery to templates via /event endpoint and eventBus. |
| docs/smelter/how-to/compose-a-fishjam-room.mdx | Documents linking a Fishjam room and templating room-driven layouts. |
| docs/smelter/how-to/category.json | Adds How-to Guides generated index under Smelter Cloud section. |
| docs/smelter/api-reference.mdx | Adds entry-point page for REST API, WebSocket auth, and error format. |
| docs/smelter/category.json | Adds top-level “Smelter Cloud” sidebar category at position 1. |
| .gitmodules | Adds api/smelter-cloud submodule entry. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Guard the jq dependency in update_api.sh, use optional chaining on peer metadata in the template example, and fix quick-start wording: a whip_client output publishes to a WHIP endpoint; playback is WHEP on the receiving service.
Gawor270
marked this pull request as ready for review
July 24, 2026 14:37
The reference page now lives at /api/smelter-cloud next to the other API docs, the Scalar page moves to /api/smelter-cloud/rest (mirroring the /api + /api/rest pair of the server API), and the API hub page links both. Smelter section links updated.
Replace the navbar dropdown with a single API Reference link landing on the /api index, where the Composition API (Smelter Cloud) sits as a subsection next to the SDK references and the hub page. The prose page is renamed Composition API to match the spec title shown by Scalar.
Split the single autogenerated sidebar in two: the Docs sidebar drops the api category, and a new apiSidebar (docs and versioned) holds the API index, the SDK references, and the Composition API page. Landing on API Reference now shows only API navigation instead of the full docs tree.
Dissolve the standalone Smelter Cloud section: the concept page (with the scene model) lives in explanation/, the quick start in tutorials/, and the guides in how-to/compositions/. All content now presents compositions as a Fishjam feature named Compositions, without beta notes. The API Reference returns to its earlier shape. The Composition API is published like the other APIs: a Scalar page at /api/compositions, a second document on /api/rest, a navbar dropdown listing both APIs, and a Compositions section (REST, WebSocket, auth, errors) on the API hub page. A presentation overlay (scripts/composition_openapi_overlay.jq) adds operation summaries, tag groups, request examples, and titles for anonymous oneOf variants. The submodule and spec are renamed to api/composition and composition-openapi.json. The room guide now documents the real flow: a single Fishjam track_forwardings call forwards the room, links the composition, and registers inputs automatically. The template guide starts from a simple static example, and the room-aware hooks live in the room guide.
Gawor270
changed the title
Comment on lines
+19
to
+21
| [submodule "api/smelter-cloud"] | ||
| path = api/composition | ||
| url = git@github.com:fishjam-cloud/foundry.git |
Comment on lines
+52
to
+54
| cd $CWD/$submodule_path | ||
| git fetch origin $2 | ||
| git checkout FETCH_HEAD --detach &>/dev/null |
Comment on lines
+385
to
+389
| { | ||
| title: "Composition API", | ||
| slug: "composition", | ||
| url: "/docs/api/composition-openapi.json", | ||
| }, |
Comment on lines
+60
to
+71
| del(.components.schemas.WhipInput.properties.endpoint_override) | ||
| | .components.schemas.Mp4Input.description = "Input stream from an MP4 file." | ||
| | .components.schemas.Framerate.oneOf[0].title = "Ratio string" | ||
| | .components.schemas.Framerate.oneOf[1].title = "Frames per second" | ||
| | .components.schemas.PortOrPortRange.oneOf[0].title = "Port range string" | ||
| | .components.schemas.PortOrPortRange.oneOf[1].title = "Single port" | ||
| | .components.schemas.VideoEncoderBitrate.oneOf[0].title = "Average bitrate" | ||
| | .components.schemas.VideoEncoderBitrate.oneOf[1].title = "Average and max bitrate" | ||
| | .components.schemas.Response.oneOf[0].title = "Bearer token" | ||
| | .components.schemas.Response.oneOf[1].title = "Media durations" | ||
| | .components.schemas.Response.oneOf[2].title = "Port" | ||
| | .components.schemas.Response.oneOf[3].title = "Empty" |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes FCE-2924 and FCE-2925, and covers FCE-3137 by publishing the API specification here.
Documents compositions as a core Fishjam feature, integrated into the existing docs structure instead of a standalone section:
explanation/compositions(what compositions are, core concepts, the scene model).tutorials/compositions(create a composition end to end with curl).how-to/compositions/(write and deploy a template, compose a Fishjam room, drive a template with events, choose inputs and outputs).api/reference): a Compositions section covering REST, the WebSocket event stream, authentication, and errors.