Composition SDK (#94)

* Add the generated Composition API client

Generated from the Composition API spec, the same way as the Fishjam client.
The whip and whep endpoints speak application/sdp, which the generator does not
support, so they are absent.

* Add CompositionClient

Wraps the generated bindings the way FishjamClient wraps its own, with a
register method per input and output variant because the response differs per
type. Models are exported from fishjam.composition.

* Forward a room's tracks into a composition

Points Fishjam at a composition and reports the link back on the room. The
livestream WHIP and WHEP addresses come with it, since they are derived from
the Fishjam URL rather than configured.

* Add the composition example

A backend that composes a looping movie and a camera published over WHIP into
a Fishjam livestream, serving the credentials for both ends over HTTP.

* Name both generated clients after the API they wrap

Neither _openapi_client nor _composition_client said what the other did.

* Report Composition API failures as the server states them

A status outside the standard set raised ValueError from the generated client
instead of an HTTPError, and messages were wrapped in a list, so they read as
['gone'] where the Fishjam ones read as text.

* Start the demo's services with the server

Building them at import allocated a room and a composition before startup, and
leaked the room when the composition failed.

Author: Gawor270

examples/composition/.env.example

@@ -0,0 +1,6 @@
+# Your Fishjam envs, which you can get at https://fishjam.io/app
+FISHJAM_ID="your-fishjam-id"
+FISHJAM_MANAGEMENT_TOKEN="your-management-token"
+
+# Only needed when running against a deployment other than production
+# COMPOSITION_URL="http://localhost:8000"

examples/composition/README.md

@@ -0,0 +1,82 @@
+# Composition Demo
+
+Demo application showing compositions, the real-time video compositing sessions, with
+[Fishjam](https://fishjam.io) and the Python Server SDK.
+
+Two sources are composed into one picture, laid out like a gaming livestream: a looping
+movie fills the stage with your camera tucked into its top corner, framed by the Fishjam
+logo and a caption bar. The result is sent to a Fishjam livestream that viewers watch.
+
+```
+[camera] ── WHIP ─┐
+                  ├─▶ composition ── WHIP ─▶ fishjam livestream ── WHEP ─▶ [viewers]
+[movie mp4] ──────┘
+```
+
+## What it shows
+
+- **Inputs**: a WHIP input the demo prints publishing credentials for, and an MP4 input
+  looping a movie from a URL
+- **Renderers**: an SVG logo registered as an image, and the Inter font used by the caption
+- **Scene**: the movie fills the stage with the camera in its top corner, on a cream frame
+  with a coral bar along the bottom. Each tile sits on a black backing, so a stream that is
+  not publishing yet reads as an empty tile rather than a hole
+  - _picture in picture_ — the movie fills the stage, the camera sits in its top corner
+  - _spotlight_ — the camera takes the stage with the movie tucked away
+  - _side by side_ — the movie and the camera share the stage
+- **Audio**: both inputs mixed, with the movie ducked under the camera
+
+## Prerequisites
+
+- Python 3.10+
+- [uv](https://docs.astral.sh/uv/) package manager
+- Fishjam credentials ([get them here](https://fishjam.io/app))
+
+> [!IMPORTANT]
+> All commands should be run from the `examples/composition` directory
+
+## Quick Start
+
+1. Install dependencies:
+
+   ```bash
+   uv sync
+   ```
+
+2. Copy [`.env.example`](./.env.example) to `.env` and populate your environment variables.
+
+3. Run the server:
+
+   ```bash
+   uv run ./main.py
+   ```
+
+Starting the server creates the composition and the livestream, then serves two endpoints:
+
+| Endpoint | Returns |
+| --- | --- |
+| `GET /streamer` | `url` and `token` to publish a camera into the composition over WHIP |
+| `GET /viewer` | `url` and `token` to watch the composed result over WHEP |
+
+Publish with any WHIP client, such as `useLivestreamStreamer` from the React client SDK,
+and watch with a livestream viewer such as `useLivestreamViewer`.
+
+Press Ctrl+C to delete the composition and the livestream room.
+
+To change the scene while the output is running, call `CompositionClient.update_output`.
+An update has to mirror the registration: this output registers both video and audio, so
+an update has to carry both.
+
+> [!NOTE]
+> A composition holds resources until it is deleted, so let the demo clean up on exit
+> rather than killing it.
+
+## Composing a whole room
+
+This demo composes inputs whose IDs it chooses itself. To compose everyone in a room
+instead, forward the room's tracks with `FishjamClient.forward_room_tracks` and render
+them with a template, since a template decides the layout as peers come and go. Build one
+with `npx @fishjam-cloud/composition-cli build App.tsx --out template.js`, register it
+with `CompositionClient.register_template_output`, and see the
+[JS example](https://github.com/fishjam-cloud/js-server-sdk/tree/main/examples/composition)
+for a template to start from.

examples/composition/composition/__init__.py

@@ -0,0 +1,83 @@
+from contextlib import asynccontextmanager
+
+from starlette.applications import Starlette
+from starlette.middleware import Middleware
+from starlette.middleware.cors import CORSMiddleware
+from starlette.requests import Request
+from starlette.responses import JSONResponse, Response
+from starlette.routing import Route
+
+from .composition_service import CompositionService
+from .config import COMPOSITION_URL, FISHJAM_ID, FISHJAM_TOKEN
+from .fishjam_service import FishjamService
+
+
+def clean_up(*services) -> None:
+    for service in services:
+        if service is None:
+            continue
+
+        try:
+            service.cleanup()
+        except Exception as error:
+            print(f"cleanup failed: {error}")
+
+
+@asynccontextmanager
+async def lifespan(app: Starlette):
+    fishjam = composition = None
+
+    try:
+        fishjam = FishjamService(FISHJAM_ID, FISHJAM_TOKEN)
+        composition = CompositionService(FISHJAM_TOKEN, COMPOSITION_URL)
+        composition.register_assets()
+        composition.play_movie()
+        composition.camera()
+        composition.stream_to(
+            fishjam.livestream_whip_url(), fishjam.create_streamer_token()
+        )
+    except Exception:
+        clean_up(composition, fishjam)
+        raise
+
+    app.state.fishjam = fishjam
+    app.state.composition = composition
+
+    try:
+        yield
+    finally:
+        clean_up(composition, fishjam)
+        print("deleted the composition and the livestream room")
+
+
+async def streamer(request: Request) -> Response:
+    camera = request.app.state.composition.camera()
+
+    return JSONResponse({"url": camera.url, "token": camera.bearer_token})
+
+
+async def viewer(request: Request) -> Response:
+    fishjam = request.app.state.fishjam
+
+    return JSONResponse({
+        "url": fishjam.livestream_whep_url(),
+        "token": fishjam.create_viewer_token(),
+    })
+
+
+app = Starlette(
+    lifespan=lifespan,
+    routes=[
+        Route("/streamer", streamer, methods=["GET"]),
+        Route("/viewer", viewer, methods=["GET"]),
+    ],
+    middleware=[
+        Middleware(
+            CORSMiddleware,
+            allow_origins=["*"],
+            allow_credentials=True,
+            allow_methods=["*"],
+            allow_headers=["*"],
+        )
+    ],
+)

examples/composition/composition/app.py

@@ -0,0 +1,83 @@
+import httpx
+
+from fishjam import CompositionClient, WhipInputTarget
+from fishjam.composition import (
+    AudioScene,
+    AudioSceneInput,
+    ImageSpecSvg,
+    ImageSpecSvgAssetType,
+    OutputWhipAudioOptions,
+    OutputWhipVideoOptions,
+    Resolution,
+)
+
+from .config import (
+    CAMERA_INPUT_ID,
+    FONT_URL,
+    HEIGHT,
+    LOGO_IMAGE_ID,
+    LOGO_URL,
+    MOVIE_INPUT_ID,
+    MOVIE_URL,
+    OUTPUT_ID,
+    WIDTH,
+)
+from .scene import scene
+
+
+class CompositionService:
+    def __init__(self, management_token: str, composition_url: str | None = None):
+        self.compositions = CompositionClient(
+            management_token=management_token, composition_url=composition_url
+        )
+        self.composition_id = self.compositions.create_composition().composition_id
+        self._camera: WhipInputTarget | None = None
+
+    def register_assets(self) -> None:
+        self.compositions.register_font(
+            self.composition_id, httpx.get(FONT_URL, follow_redirects=True).content
+        )
+        self.compositions.register_image(
+            self.composition_id,
+            LOGO_IMAGE_ID,
+            ImageSpecSvg(
+                asset_type=ImageSpecSvgAssetType.SVG,
+                url=LOGO_URL,
+                resolution=Resolution(width=200, height=200),
+            ),
+        )
+
+    def play_movie(self) -> None:
+        self.compositions.register_mp4_input(
+            self.composition_id, MOVIE_INPUT_ID, url=MOVIE_URL, loop=True
+        )
+
+    def camera(self) -> WhipInputTarget:
+        if self._camera is None:
+            self._camera = self.compositions.register_whip_input(
+                self.composition_id, CAMERA_INPUT_ID, video=True
+            )
+
+        return self._camera
+
+    def stream_to(self, endpoint_url: str, bearer_token: str) -> None:
+        self.compositions.register_whip_output(
+            self.composition_id,
+            OUTPUT_ID,
+            endpoint_url=endpoint_url,
+            bearer_token=bearer_token,
+            video=OutputWhipVideoOptions(
+                resolution=Resolution(width=WIDTH, height=HEIGHT), initial=scene()
+            ),
+            audio=OutputWhipAudioOptions(
+                initial=AudioScene(
+                    inputs=[
+                        AudioSceneInput(input_id=CAMERA_INPUT_ID),
+                        AudioSceneInput(input_id=MOVIE_INPUT_ID, volume=0.2),
+                    ]
+                )
+            ),
+        )
+
+    def cleanup(self) -> None:
+        self.compositions.delete_composition(self.composition_id)

examples/composition/composition/composition_service.py

@@ -0,0 +1,24 @@
+import os
+
+import dotenv
+
+dotenv.load_dotenv()
+
+FISHJAM_ID = os.environ["FISHJAM_ID"]
+FISHJAM_TOKEN = os.environ["FISHJAM_MANAGEMENT_TOKEN"]
+COMPOSITION_URL = os.getenv("COMPOSITION_URL")
+HOST = os.getenv("HOST", "localhost")
+PORT = int(os.getenv("PORT", "8000"))
+
+CAMERA_INPUT_ID = "camera"
+MOVIE_INPUT_ID = "movie"
+LOGO_IMAGE_ID = "fish"
+OUTPUT_ID = "livestream"
+
+MOVIE_URL = "https://github.com/smelter-labs/smelter-snapshot-tests/raw/refs/heads/main/assets/BigBuckBunny720p24fpsStereo30s.mp4"
+LOGO_URL = "https://fishjam.swmansion.com/favicon.svg"
+FONT_URL = "https://raw.githubusercontent.com/google/fonts/main/ofl/inter/Inter%5Bopsz%2Cwght%5D.ttf"
+FONT_FAMILY = "Inter"
+
+WIDTH = 1280
+HEIGHT = 720

examples/composition/composition/config.py

@@ -0,0 +1,24 @@
+from fishjam import FishjamClient, RoomOptions
+
+
+class FishjamService:
+    def __init__(self, fishjam_id: str, management_token: str):
+        self.fishjam = FishjamClient(fishjam_id, management_token)
+        self.livestream_id = self.fishjam.create_room(
+            RoomOptions(room_type="livestream")
+        ).id
+
+    def livestream_whip_url(self) -> str:
+        return self.fishjam.livestream_whip_url()
+
+    def livestream_whep_url(self) -> str:
+        return self.fishjam.livestream_whep_url()
+
+    def create_streamer_token(self) -> str:
+        return self.fishjam.create_livestream_streamer_token(self.livestream_id)
+
+    def create_viewer_token(self) -> str:
+        return self.fishjam.create_livestream_viewer_token(self.livestream_id)
+
+    def cleanup(self) -> None:
+        self.fishjam.delete_room(self.livestream_id)