API Specification#

Ingress#

gRPC API#

The Animation Graph microservice can accept an input animation data stream from an animation data source (e.g. Audio2Face-3D). This animation data stream is provided through the PushAnimationDataStream remote procedure call (RPC). The animation graph then blends the final animation and generates a new animation data stream that can be streamed to a downstream renderer. These renderers connect to the Animation Graph microservice renderer through the PullAnimationDataStream RPC. Both RPCs are defined in the Animation Data Service.

Animation Data Stream Audio Format#

The Animation Graph microservice currently only supports animation data streams with the following audio format.

Format

PCM

Channel Count

1

Sample Rate

Any (Hz)

Bit Per Sample

16

HTTP API#

In addition to the animation data stream APIs, the Animation Graph microservice also exposes an HTTP API. With this API you can:

  • Control the values of animation graph variable, e.g. to control postures and gestures of the default animation graph.

  • Add and remove active streams to the microservice.

  • Delete an active request from an input animation data source, e.g. interrupting an Audio2Face utterance while the avatar is speaking.

An interactive HTTP API overview can be accessed once the microservice has been started at http://localhost:8020/docs.

Animation Graph Variable Control#

Please note that the HTTP API routes are generated dynamically when the Animation Graph microservice starts. It loads the Custom Layer Data from the USD scene file and generates the endpoint paths accordingly.

Thus, the HTTP API exposed by the microservice depends on the animation graph variable configuration contained in the USD scene file. The HTTP API documentation for the default animation graph is provided here as a reference.

Please see the default animation graph section for example API calls to change animation graph variables.

Stream Management#

The Animation Graph microservice is a stateful service, which only generates an output animation data stream after a stream has been registered with a stream ID.

An animation data stream can be added with:

stream_id=$(uuidgen)
curl -X POST -s http://localhost:8020/streams/$stream_id

Similarly, an animation data stream can be removed with:

curl -X DELETE -s http://localhost:8020/streams/$stream_id

Egress#

Redis Stream (Experimental)#

The Animation Graph microservice has a Redis client which attempts to connect to a Redis server hosted at IAAGMS_REDIS_HOST (“$egress.redis.address”) and IAAGMS_REDIS_PORT (“$egress.redis.port”) at initialization of the service.

Every time an input animation data stream request ends (e.g. an Audio2Face utterance finishes), the Animation Graph microservice publishes in a Redis channel named animation_graph_events to notify the end of the request:

{
    "event_type": event_type,
    "stream_id": stream_id,
    "source_id": source_id,
    "request_id": request_id,
    event_type + "_at": datetime (UTC)
}

Where event_type is “request_playback_ended” if the request ended normally, or “request_playback_interrupted” if the request was interrupted through the HTTP API interruption endpoint. request_id and source_id are the ids of the input animation data stream request (e.g. a UUID as request_id and “Audio2Face with Emotions” as source_id for Audio2Face).

On this page