Integrations and External Services

Integrations are stored in the project document and executed by the engine. The Studio, the AI Assistant and the MCP server all manage them through ProjectRestController:

GET .../integrations returns the four lists, and every row carries its type. Deleting is one endpoint for all kinds, DELETE .../integrations?type={pre|during|post|connector}&ref={ref}, so the kind must be known to delete a row. Code that opens, edits or deletes an integration by ref has to branch on its kind first — the pre/post and the MCP-server edit views each look the ref up only in their own list, and a ref routed to the wrong one never resolves.

Projects that admit end users through their own identity providers name Keycloak identity-provider aliases (Identity Providers and External Roles). KeycloakIdentityProviderProbe checks a new alias against the realm the backend trusts without admin credentials: it reads the realm’s discovery document and then calls the broker endpoint {realm}/broker/{alias}/endpoint, which answers 404 only for an unknown alias. An unreachable Keycloak yields "unknown" rather than a verdict, and the save goes through. Probing a known OIDC alias leaves a failed identity-provider login event in Keycloak.

A video uploaded to an interactive-content element — in the Studio (POST /api/v1/project/multimodality-video) or through the MCP tool upload_interactive_content_file — is stored as uploaded at platform/project/{id}/multimodalInteraction/{ref}.mp4 and served from there right away, whatever its container. ProjectService then queues its re-encoding with VideoTranscoder: the original is downloaded into a temporary directory, re-encoded with ffmpeg, and the copy stored next to it as {ref}_encoded_v{n}.mp4, n being ENCODE_VERSION. The element’s url is then switched to the copy by a compare-and-set that matches only while the element still serves that very upload, so an edit, a newer upload or a removal made in the meantime wins. The copy is then deleted again, unless an element serves it after all — a form saved with the address of the copy an earlier upload made. An element missing at that point is looked up once more a moment later, as an edit replaces an element by removing it and adding its new version. The copy’s address keeps the original’s q query: when a form opened before the switch sends the original’s address back, the update recognizes the same upload and keeps the copy.

The original’s video bitrate is that of its video stream. A container that stores none per stream (WebM, Matroska) gives the file’s bitrate less the audio’s, and a file without a duration — a browser’s recording — gives its size over the time of its last frame, which a second ffprobe pass reads; when none of that is known, the copy gets 3 Mbit/s. A browser’s recording also declares 1000 frames a second; the cap of 60 keeps it from being encoded at that rate. The decoder buffer (-maxrate, -bufsize) is sized for at least 200 kbit/s, so that a keyframe of a low-bitrate video still fits it. A copy can come out larger than its original, for one because the audio is always stereo, and it replaces the original all the same.

These settings are constants of VideoTranscoder, and changing any of them means bumping ENCODE_VERSION, so that copies made with other settings stay recognizable by name. The originals are kept for the same reason: a copy can always be made again from its original. Only new uploads are re-encoded — an element keeps serving whatever its url names, and a video given by URL is never re-encoded.

ffmpeg and ffprobe read only what an uploaded video needs: the containers MP4, MOV and 3GP, WebM and Matroska, and Ogg; the decoders of the common video, audio, subtitle and cover-art codecs (DECODERS); and pictures of at most 4096 × 2304 pixels, any 4K video. A file with anything else — an AVI, a QuickTime Animation track, an 8K or a 5.7K video — fails and keeps its original; a picture too large is refused before it is decoded.

ffmpeg runs as a child process in the backend’s container and shares the pod’s memory with the JVM, which shapes how it runs:

A failure — no ffmpeg, a file ffmpeg cannot read or does not take, an ffmpeg error or timeout, a storage error — is logged as a warning and leaves the original served, as does a restart in the middle of a job. Without ffmpeg and ffprobe on the PATH, or with promethist.video-transcoding.enabled=false — as in issue environments — nothing is re-encoded (Video Re-encoding settings).