World Model Accelerator (WMA)

WMA connects your application to a fal runner through WebRTC. A session can exchange control messages, audio, and video. Use fal.wma.App to manage the session and fal.wma.AiortcPeer to connect a Python media pipeline.

WMA is experimental, including when it ships in a stable fal package. Pin your SDK versions because the WMA API can change. The Python examples require fal 1.81.4 or later and Pydantic 2. The browser walkthrough uses a separately versioned JavaScript prerelease.

Deploy your first app

Start with the generated-video example. It runs on a CPU and requires no camera, model weights, or GPU. You can change its colors and speed while the video streams.

1. Install and authenticate

Use Python 3.12 for this walkthrough. Create a virtual environment, then install the SDK:

python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install 'fal[wma]==1.81.4' 'pydantic>=2,<3'
fal auth login

On Windows PowerShell, activate the environment with .venv\Scripts\Activate.ps1. If your package index cannot find 1.81.4, wait for the PyPI publishing workflow to finish. A GitHub release can exist before its package is available on PyPI. The wma extra installs local WebRTC dependencies. WMA apps also receive aiortc in their runner requirements. Your account needs deployment access and WMA bridge access. Installing the package does not grant either permission.

2. Download and deploy the video example

Download the example from the matching SDK release:

curl --fail --location \
  https://raw.githubusercontent.com/fal-ai/fal/fal_v1.81.4/projects/fal/examples/wma_video.py \
  --output wma_video.py
fal deploy wma_video.py::VideoApp --auth private

Keep the application ID from the deployment output. You will use this ID in the playground and browser client. The example uses an XS CPU runner, permits two simultaneous sessions per runner, and limits each session to two minutes. Runner compute can incur charges. Disconnect when you finish testing.

3. Connect in the playground

Open your deployed app in the fal dashboard.
Select its /start-session playground.
Select Connect and wait for the video.
Select Fast sunset, then select Send message.
Confirm that the colors and speed change.
Select Disconnect to end the session.

The playground displays an AsyncAPI link and controls for the declared messages. If you see an SDP text field instead, check the realtime contract.

Choose an example

Each example includes a realtime contract and deployment requirements. Download the file, then deploy the named class with --auth private.

Example	Class	What you can test
Control echo	`EchoApp`	Send a text message and receive it back.
Generated video	`VideoApp`	Change a video stream’s palette and speed without a camera.
Camera effects	`FilterApp`	Send camera video and receive mirrored, monochrome, or edge-filtered video.
Motion measurements	`MotionApp`	Send camera video and receive brightness and motion measurements as messages.

The camera examples need browser camera permission. Motion measurements use pixel differences, not an object detector. For your own frontend, follow Connect a browser to WMA.

Build your own app

Subclass fal.wma.App and implement create_backend(session). Return an AiortcPeer, or implement PeerBackend for your own transport. The following complete app echoes typed control messages. Save it as wma_echo.py.

from typing import Literal

from pydantic import BaseModel, Field

import fal.wma


class EchoMessage(BaseModel):
    type: Literal["echo"] = "echo"
    text: str = Field(default="Hello, WMA!", description="Text to echo back.")


class EchoApp(fal.wma.App):
    machine_type = "XS"
    requirements = ["pydantic>=2,<3"]
    max_multiplexing = 4
    secrets = ["FAL_KEY"]
    realtime_contract = fal.wma.RealtimeContract(
        media=fal.wma.MediaContract(),
        client_messages=EchoMessage,
        server_messages=EchoMessage,
        client_message_examples=(
            fal.wma.MessageExample(
                name="Say hello",
                payload={"type": "echo", "text": "Hello, WMA!"},
            ),
        ),
    )

    async def create_backend(self, session):
        from aiortc import RTCConfiguration

        servers, _ = await fal.wma.RunnerIceConfig.from_bridge().build_ice_servers_async(
            session.offer.ice_servers,
            forwarded_status=session.offer.ice_status,
        )
        session.on_message("echo", lambda message: session.send(message))
        return fal.wma.AiortcPeer(
            session,
            lambda _pc: None,
            rtc_configuration=RTCConfiguration(iceServers=servers),
        )

Deploy it with:

fal deploy wma_echo.py::EchoApp --auth private

The echo handler sends back the received message. Contract schemas describe your API but do not validate incoming messages automatically. For application commands, validate the payload inside your handler with your Pydantic model before you use it. The callback passed to AiortcPeer receives the peer connection. Attach outgoing tracks with pc.addTrack(track). Register a pc.on("track") handler to process incoming media. The video and camera examples demonstrate both patterns.

Describe your app for the playground

Declare realtime_contract on every app that needs the WMA playground. The SDK generates AsyncAPI and links it from the /start-session OpenAPI operation through x-fal-realtime. This metadata enables Connect/Disconnect controls, message forms, examples, and media previews. Use Pydantic models for client_messages and server_messages. Add MessageExample entries for commands that customers can try. Use MediaContract to describe the actual media tracks. Track directions are always from the client’s perspective:

App	`MediaContract.send`	`MediaContract.receive`
Control echo	Empty	Empty
Generated video	Empty	`Track(kind="video")`
Camera effects	`Track(kind="video", source="camera", required=True)`	`Track(kind="video")`
Motion measurements	`Track(kind="video", source="camera", required=True)`	Empty

For example, a camera-to-video app declares:

media = fal.wma.MediaContract(
    send=(fal.wma.Track(kind="video", source="camera", required=True),),
    receive=(fal.wma.Track(kind="video"),),
)

Redeploy after changing the contract, then refresh the playground. Transport can work without a contract, but the SDK cannot infer your messages or tracks. Core sessions support Pydantic 1. Typed contracts and schema rendering require Pydantic 2.

Session lifecycle and cleanup

The client sends its offer through the WMA bridge. The bridge forwards it to your app’s POST /start-session endpoint. The response streams the answer and keeps the HTTP connection open for the session’s lifetime. Media and control messages travel through WebRTC, either directly or through TURN. Closing the session closes its backend and finalizes deferred usage. Do not add application heartbeat or close routes for this lifecycle. Keep mutable state inside create_backend so different sessions do not share controls accidentally. Use session.create_task() for background work that must stop with the session. Bind resources with session.bind_backend(backend) before setup work that can fail. AiortcPeer stops its attached outgoing tracks during cleanup. Use a separate relay subscription when sessions share a media source. It limits the initial connection wait to 35 seconds. Set disconnected_grace_seconds if you want a bounded wait after a transient disconnect. session.send(message) returns False when the channel cannot accept a message or its buffer is full. Drop stale updates or retry later. A worker thread’s True result confirms queue acceptance, not delivery to the client.

ICE, billing, and deployment

Use RunnerIceConfig.from_bridge() with the forwarded offer, as shown above. It validates the supplied ICE servers before use. TURN permits connections on networks where a direct path fails. A successful local connection does not prove that TURN works. For metered application usage, call session.add_billable_units(n) for delivered work. Use session.cap_billable_units(n) before finalization if cleanup identifies undelivered work. Deferred usage is zero on setup failures by default. Runner compute can still incur charges. Billing report failures require operational follow-up. The base app includes the FAL_KEY secret for its billing reporter. Preserve it if your subclass overrides secrets. Configure the required runner secrets and endpoint pricing before using deferred billing. Your browser application’s API key belongs on its server, never in browser code. Before customer handoff, verify these behaviors against the deployed app:

Connect with the intended client and network.
Exchange the declared controls and media.
Test TURN on a network that requires relay connectivity.
Disconnect and reconnect with a new session.
Confirm that cleanup stops background work and releases resources.
Confirm the settled billing amount for delivered work.

Troubleshooting

Symptom	Check
`No module named fal.wma`	Install the required SDK version in the same environment that runs `fal deploy`.
`aiortc` is missing locally	Install the `fal[wma]` extra.
The playground asks for SDP	Declare `realtime_contract`, redeploy, and refresh.
Schema generation fails	Use Pydantic 2 locally and in the app’s runner requirements.
A private app returns 401 or 403	Check account access, credentials, and the browser’s authenticated server proxy.
Controls work but no video arrives	Declare the correct client receive tracks and attach an outgoing server track.
Connections fail on restrictive networks	Check TURN provisioning and the selected ICE path.
A session closes after two minutes	The three media examples intentionally impose this limit.

See the SDK guide for module details and custom backend responsibilities.

Setting Up

Model APIs

Serverless

Compute

Organizations

fal Agent

fal Assets

World Model Accelerator (WMA)

Deploy your first app

1. Install and authenticate

2. Download and deploy the video example

3. Connect in the playground

Choose an example

Build your own app

Describe your app for the playground

Session lifecycle and cleanup

ICE, billing, and deployment

Troubleshooting

​Deploy your first app

​1. Install and authenticate

​2. Download and deploy the video example

​3. Connect in the playground

​Choose an example

​Build your own app

​Describe your app for the playground

​Session lifecycle and cleanup

​ICE, billing, and deployment

​Troubleshooting

Deploy your first app

1. Install and authenticate

2. Download and deploy the video example

3. Connect in the playground

Choose an example

Build your own app

Describe your app for the playground

Session lifecycle and cleanup

ICE, billing, and deployment

Troubleshooting