Composition SDK

[Gawor270]

Description

Adds composition support to the SDK

• adds the autogenerated composition-openapi package
• adds CompositionClient, covering the composition control plane
• adds forwardRoomTracks to FishjamClient, pointing a room's tracks at a composition
• adds an example that exercises templates, track forwarding and events

Motivation and Context

The Composition API had no server-side client, so anyone creating a composition hand-rolled HTTP.

Documentation impact

• Documentation update required
• Documentation updated in another PR
• No documentation update required

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to
  not work as expected)

[linear]

FCE-3730

[Copilot]

Pull request overview

Adds composition management and room track forwarding to the server SDK, backed by a generated Composition OpenAPI client and an end-to-end example.

Changes:

• Adds CompositionClient, composition types, errors, serialization, and tests.
• Adds room track forwarding and livestream WHIP URL helpers.
• Adds Composition OpenAPI codegen and a complete composition demo.

Reviewed changes

Copilot reviewed 34 out of 118 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
AGENTS.md	Documents the SDK test command.
spelling.txt	Adds RTMP to the spelling dictionary.
yarn.lock	Locks new workspaces and demo dependencies.
packages/js-server-sdk/package.json	Bundles the Composition OpenAPI client.
packages/js-server-sdk/src/client.ts	Adds track forwarding and livestream WHIP helpers.
packages/js-server-sdk/src/composition.ts	Implements CompositionClient.
packages/js-server-sdk/src/exceptions/index.ts	Adds composition resource exceptions.
packages/js-server-sdk/src/exceptions/mapper.ts	Maps Composition API failures.
packages/js-server-sdk/src/index.ts	Exports composition APIs and types.
packages/js-server-sdk/src/types.ts	Defines composition configuration and branded IDs.
packages/js-server-sdk/src/utils.ts	Adds composition URL and file helpers.
packages/js-server-sdk/tests/composition.test.ts	Tests composition requests and variants.
packages/js-server-sdk/tests/exceptions.test.ts	Tests composition exception mapping.
packages/js-server-sdk/tests/fixtures/font.ttf	Supplies a font upload fixture.
packages/js-server-sdk/tests/track_forwarding.test.ts	Tests forwarding and URL helpers.
packages/composition-openapi/LICENSE	Adds package licensing.
packages/composition-openapi/README.md	Documents OpenAPI generation.
packages/composition-openapi/package.json	Defines the internal OpenAPI workspace.
packages/composition-openapi/tsconfig.json	Configures TypeScript compilation.
packages/composition-openapi/openapitools.json	Pins the generator version.
packages/composition-openapi/openapi.sh	Generates and patches the client.
packages/composition-openapi/src/index.ts	Exports generated code.
packages/composition-openapi/src/generated/index.ts	Exports generated APIs and models.
packages/composition-openapi/src/generated/runtime.ts	Provides generated fetch runtime support.
packages/composition-openapi/src/generated/.openapi-generator-ignore	Configures generator exclusions.
packages/composition-openapi/src/generated/.openapi-generator/FILES	Records generated files.
packages/composition-openapi/src/generated/.openapi-generator/VERSION	Records generator version.
packages/composition-openapi/src/generated/apis/index.ts	Exports generated API classes.
packages/composition-openapi/src/generated/apis/CompositionsApi.ts	Implements composition lifecycle requests.
packages/composition-openapi/src/generated/apis/EventsApi.ts	Implements template event requests.
packages/composition-openapi/src/generated/apis/InputsApi.ts	Implements input requests.
packages/composition-openapi/src/generated/apis/MediaTransportApi.ts	Implements WHIP/WHEP transport requests.
packages/composition-openapi/src/generated/apis/OutputsApi.ts	Implements output requests.
packages/composition-openapi/src/generated/apis/RenderersApi.ts	Implements font and image requests.
packages/composition-openapi/src/generated/models/index.ts	Exports generated models.
packages/composition-openapi/src/generated/models/ApiError.ts	Defines API errors.
packages/composition-openapi/src/generated/models/AudioChannels.ts	Defines audio channel options.
packages/composition-openapi/src/generated/models/AudioMixingStrategy.ts	Defines audio mixing strategies.
packages/composition-openapi/src/generated/models/AudioScene.ts	Defines audio scenes.
packages/composition-openapi/src/generated/models/AudioSceneInput.ts	Defines audio scene inputs.
packages/composition-openapi/src/generated/models/AverageAndMaxBitrate.ts	Defines bitrate limits.
packages/composition-openapi/src/generated/models/BoxShadow.ts	Defines box shadows.
packages/composition-openapi/src/generated/models/Component.ts	Defines component unions.
packages/composition-openapi/src/generated/models/CompositionCreatedResponse.ts	Defines composition creation responses.
packages/composition-openapi/src/generated/models/CreateCompositionRequest.ts	Defines composition creation options.
packages/composition-openapi/src/generated/models/EasingFunction.ts	Defines easing function unions.
packages/composition-openapi/src/generated/models/EasingFunctionBounce.ts	Defines bounce easing.
packages/composition-openapi/src/generated/models/EasingFunctionCubicBezier.ts	Defines Bézier easing.
packages/composition-openapi/src/generated/models/EasingFunctionLinear.ts	Defines linear easing.
packages/composition-openapi/src/generated/models/FontUpload.ts	Defines font uploads.
packages/composition-openapi/src/generated/models/Framerate.ts	Defines frame rates.
packages/composition-openapi/src/generated/models/H264EncoderPreset.ts	Defines H.264 presets.
packages/composition-openapi/src/generated/models/HorizontalAlign.ts	Defines horizontal alignment.
packages/composition-openapi/src/generated/models/Image.ts	Defines image components.
packages/composition-openapi/src/generated/models/ImageSpec.ts	Defines image specification unions.
packages/composition-openapi/src/generated/models/ImageSpecAuto.ts	Defines automatic image detection.
packages/composition-openapi/src/generated/models/ImageSpecGif.ts	Defines GIF images.
packages/composition-openapi/src/generated/models/ImageSpecJpeg.ts	Defines JPEG images.
packages/composition-openapi/src/generated/models/ImageSpecPng.ts	Defines PNG images.
packages/composition-openapi/src/generated/models/ImageSpecSvg.ts	Defines SVG images.
packages/composition-openapi/src/generated/models/InputStream.ts	Defines input-stream components.
packages/composition-openapi/src/generated/models/Interpolation.ts	Defines interpolation modes.
packages/composition-openapi/src/generated/models/Mp4Input.ts	Defines MP4 inputs.
packages/composition-openapi/src/generated/models/OpusEncoderPreset.ts	Defines Opus presets.
packages/composition-openapi/src/generated/models/OutputEndCondition.ts	Defines output termination conditions.
packages/composition-openapi/src/generated/models/OutputRtmpClientAudioOptions.ts	Defines RTMP audio options.
packages/composition-openapi/src/generated/models/OutputRtmpClientVideoOptions.ts	Defines RTMP video options.
packages/composition-openapi/src/generated/models/OutputWhipAudioOptions.ts	Defines WHIP audio options.
packages/composition-openapi/src/generated/models/OutputWhipVideoOptions.ts	Defines WHIP video options.
packages/composition-openapi/src/generated/models/Overflow.ts	Defines overflow behavior.
packages/composition-openapi/src/generated/models/PixelFormat.ts	Defines pixel formats.
packages/composition-openapi/src/generated/models/PortOrPortRange.ts	Defines port configuration.
packages/composition-openapi/src/generated/models/RegisterInput.ts	Defines input registration unions.
packages/composition-openapi/src/generated/models/RegisterInputResponse.ts	Defines input registration responses.
packages/composition-openapi/src/generated/models/RegisterOutput.ts	Defines output registration unions.
packages/composition-openapi/src/generated/models/RegisterTemplateOutput.ts	Defines template output uploads.
packages/composition-openapi/src/generated/models/RescaleMode.ts	Defines rescaling modes.
packages/composition-openapi/src/generated/models/Rescaler.ts	Defines rescaler components.
packages/composition-openapi/src/generated/models/Resolution.ts	Defines media resolutions.
packages/composition-openapi/src/generated/models/RtmpInput.ts	Defines RTMP inputs.
packages/composition-openapi/src/generated/models/RtmpOutput.ts	Defines RTMP outputs.
packages/composition-openapi/src/generated/models/SendCompositionEventRequest.ts	Defines template events.
packages/composition-openapi/src/generated/models/Text.ts	Defines text components.
packages/composition-openapi/src/generated/models/TextStyle.ts	Defines text styles.
packages/composition-openapi/src/generated/models/TextWeight.ts	Defines text weights.
packages/composition-openapi/src/generated/models/TextWrapMode.ts	Defines text wrapping.
packages/composition-openapi/src/generated/models/Tiles.ts	Defines tile layouts.
packages/composition-openapi/src/generated/models/Transition.ts	Defines scene transitions.
packages/composition-openapi/src/generated/models/TransportProtocol.ts	Defines transport protocols.
packages/composition-openapi/src/generated/models/UnregisterInput.ts	Defines input removal options.
packages/composition-openapi/src/generated/models/UnregisterOutput.ts	Defines output removal options.
packages/composition-openapi/src/generated/models/UnregisterRenderer.ts	Defines renderer removal options.
packages/composition-openapi/src/generated/models/UpdateOutputRequest.ts	Defines output scene updates.
packages/composition-openapi/src/generated/models/VerticalAlign.ts	Defines vertical alignment.
packages/composition-openapi/src/generated/models/VideoEncoderBitrate.ts	Defines video bitrates.
packages/composition-openapi/src/generated/models/VideoScene.ts	Defines video scenes.
packages/composition-openapi/src/generated/models/View.ts	Defines view components.
packages/composition-openapi/src/generated/models/ViewDirection.ts	Defines view directions.
packages/composition-openapi/src/generated/models/WhepInput.ts	Defines WHEP inputs.
packages/composition-openapi/src/generated/models/WhipAudioEncoderOptions.ts	Defines WHIP encoder unions.
packages/composition-openapi/src/generated/models/WhipAudioEncoderOptionsAny.ts	Defines unrestricted WHIP encoding.
packages/composition-openapi/src/generated/models/WhipAudioEncoderOptionsOpus.ts	Defines Opus WHIP encoding.
packages/composition-openapi/src/generated/models/WhipInput.ts	Defines WHIP inputs.
packages/composition-openapi/src/generated/models/WhipOutput.ts	Defines WHIP outputs.
examples/composition/.env.example	Provides demo environment variables.
examples/composition/.gitignore	Excludes generated and local files.
examples/composition/README.md	Documents the composition demo.
examples/composition/package.json	Configures demo dependencies and scripts.
examples/composition/tsconfig.json	Configures demo TypeScript.
examples/composition/template/App.tsx	Implements the composition template.
examples/composition/template/scene.ts	Defines demo scenes and styling.
examples/composition/src/const.ts	Defines server and media constants.
examples/composition/src/environment.d.ts	Types environment variables.
examples/composition/src/index.ts	Starts and tears down the demo.
examples/composition/src/controllers/peers.ts	Serves peer tokens.
examples/composition/src/controllers/viewers.ts	Serves viewer tokens.
examples/composition/src/service/composition.ts	Coordinates composition setup.
examples/composition/src/service/fishjam.ts	Coordinates rooms and forwarding.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[czerwiukk]

more coming soon

[Copilot]

Pull request overview

Copilot reviewed 34 out of 118 changed files in this pull request and generated 2 comments.

Suppressed comments (1)

Previously missed (1) — in code that hasn't changed since the last review.

examples/composition/src/const.ts:17

• .pathname is a URL-encoded URL path, not a filesystem path: directories containing spaces produce %20, and Windows produces a leading /C:/, so toBlob/readFile cannot find the bundle. Convert the file URL with fileURLToPath before passing it to the SDK.

export const TEMPLATE_BUNDLE = new URL('../dist/template.js', import.meta.url).pathname;