| 1 Definition | 2 Functional Requirements | 3 Syntax | 4 Semantics |
1 Definition
User Command (CAE-UCM) is End User’s data enabling editing and control of an Audio or Visual Scene: a request (UserCommandRQ), input to the AIM that executes it, or the response to it (UserCommandRS), output by that AIM under the same UserCommandID. It is one Data Type: exactly one of the two is present. A request specifies navigation, remixing, spatial positioning, change of the features of Objects, substitution, motion, listing, and acoustic environment modifications of Objects and Scenes. Objects and Scenes are identified by the name the User gave them.
2 Functional Requirements
User Command shall support the following Functional Requirements:
| Scene Navigation | Changing the position and/or orientation of the end user by specifying a new User Point of View. |
| Acquire Object | Acquire an Object from the environment or a storage device. |
| Deliver Object | Deliver an Object to the environment or a storage device. |
| Remixing | Level (LUFS measured as specified by ITU‑R BS.1770), a number, specifying amplification or attenuation of Audio Objects. |
| Addition/Removal | Adding Audio Objects and Speech Objects to a Scene, each placed at a position and orientation given as numbers; removing them. |
| Object Repositioning | Moving an Object to a new position and orientation: a command is absolute, and every amount in it is a required number. |
| Feature Change | Changing a feature of an Object from a defined list (ChangedObjects), each by a value; a new Name is the same Object with a unique name. |
| Object Substitution | Having a Speech Object translated into another language, the translation replacing the original at its place. |
| Object Motion | Assigning motion attributes to Audio Objects using Spatial Attitude and Acoustic Profile. |
| Acoustic Environment Modification | Changing the acoustic characteristics applied to Audio Objects and Scenes through Acoustic Profiles, and the Closed Space of a Scene. |
| Listing | Listing the Objects and Scenes of a Kind, by name, with their Duration, number of children and Version; listing the members of a named Scene with their PoV; listing everything (All) that an editing AIM keeps. |
| Deletion | Deleting Objects and Scenes, by the name the User gave them, with all their versions, from where the Module keeps them: not the same as removing an Object from a Scene. |
| Revocation | Revoking an earlier User Command, by its UserCommandID. |
| Response | Reporting, in the same Data Type and under the same UserCommandID, how each action of a request was executed. |
3 Syntax
https://schemas.mpai.community/CAE3/V1.0/data/UserCommand.json
4 Semantics
| Label | Description |
| Header | User Command Header, format “CAE-UCM-Vx.y”. |
| MInstanceID | Identifier of the M-Instance. |
| UEnvironmentID | Identifier of the User Environment. |
| UserCommandID | Identifier of the User Command. The response carries the UserCommandID of the request it answers. |
| UserCommandTime | Timestamp indicating when the command is issued (Simple Time). |
| Confidence | A number from 0 to 1: how likely it is that the User Command is what the User asked for – for instance, when it is interpreted from what the User says. |
| UserCommandRQ | A request. Exactly one of UserCommandRQ and UserCommandRS is present. Every amount in a request is a number the request carries; an AIM that finds none reports it, it does not guess one. Objects and Scenes are identified by the name the User gave them. |
| – UserPoV | Where the Scene, or an Object heard alone, is heard from (Point of View). |
| – LUFS | The loudness, in LUFS, as a number. Alone it sets the loudness of the open Object; with ModifiedObjects it is the amount the modification carries when no entry has an Acoustic Profile or a Spatial Attitude. |
| – RevokedUserCommandID | The User Command to revoke, by its UserCommandID. It goes to the AIM that executed that command, which undoes it if it can; the report says whether it did: Done, Failed, or NotSupported where the AIM cannot undo it. |
| – AcquiredObject | The Object to acquire or to open: an Audio, Speech, 3D Model or Visual Object, in full or by its identifier (ObjectOrID). |
| – DeliveredObject | The Object to deliver: an Audio, Speech, 3D Model or Visual Object, in full or by its identifier (ObjectOrID). |
| – AddedObjects | Objects added to a Scene, or composed into an Audio Object. |
| – ObjectID | The name of the Audio Object, or of the Scene, that the command makes of the Objects it adds (the name the User gives it, such as “concert”). Required when the command makes one: an Audio Object composed of the Objects, or the Scene created when none is open. A name that is taken becomes the name followed by the next free number (“concert 2”). |
| – Objects[] | The Objects added. |
| – ObjectID | The Object, or its name. |
| – SpatialAttitude | Where the Object is put: the position and the orientation, as numbers. Required (Spatial Attitude). |
| – RemovedObjects | Objects removed from a Scene. |
| – Objects[] | Each entry gives the ObjectID, or the SpatialAttitude, or both; at least one. |
| – DeletedObjects | Deletes, from where the Module keeps them, the Objects and Scenes named – the Audio Objects, Speech Objects, Audio Scenes, Speech Scenes and Multimodal Scenes, by the name the User gave them, with all their versions. Not the same as RemovedObjects, which takes an Object out of the open Scene and leaves it kept. An Object that is a member of a Scene is not deleted, and the response says so, naming the Scene: the Scene is deleted first. A name that is not known fails. Nothing is deleted that is not named. |
| – Objects[] | The Objects and Scenes to delete: at least one entry. |
| – ObjectID | The Object or Scene to delete, by the name the User gave it. Required. |
| – MovedObjects | Objects moved to a new position and orientation. |
| – Objects[] | Each entry has a NewSpatialAttitude and either an ObjectID or an OldSpatialAttitude. |
| – ObjectID | The Object, by name. |
| – AcousticProfile | The Object part of the Acoustic Profile. |
| – OldSpatialAttitude | Where the Object is now, as numbers; names the Object when ObjectID is absent. |
| – NewSpatialAttitude | Where the Object is to be: the position and the orientation, as numbers. Required. |
| – ChangedObjects | Edits the features of the Objects named, each feature changed by a value. The features that can be changed are listed here by name, and nothing else is allowed; every edit is a new version, which has the name of the Object. The sound itself is not a feature: it is not edited. |
| – Objects[] | Each entry has an ObjectID and at least one of the features below. |
| – ObjectID | The Object whose features are changed, by its name. |
| – Name | The new name of the Object (its AudioObjectID or BasicAudioObjectID): it is the same Object, and the name stays unique – a name that is taken becomes the name followed by the next free number (“violin 2”). |
| – Time | The time of the Object (AudioObjectTime, BasicAudioObjectTime). |
| – SpaceTime | The Space/Time of an Audio Object (AudioObjectSpaceTime): the frame its children are placed in. |
| – UserPoV | Where the Object is heard from when it is heard alone. |
| – ParentAudioObjectIDs | The names of the Audio Objects the Audio Object is a child of. |
| – DescrMetadata | The description of the Object (at most 2048 characters). |
| – Children[] | Where and when each child of an Audio Object, named, is inside the parent: ObjectID (the name of the child, a Basic Audio Object or an Audio Object) and SpaceTime. |
| – DeviceID | The device of a Basic Audio Object. |
| – Level | The loudness of a Basic Audio Object, in LUFS, a number. |
| – PerceptStatus | The percept status of a Basic Audio Object. |
| – AcousticProfile | The Object part of the Acoustic Profile of a Basic Audio Object. |
| – AudioQualifier | The Audio Qualifier of a Basic Audio Object. |
| – SpatialAttitude | Where the Object is in the open Scene: a Scene Editing feature. |
| – Qualifier | The Qualifier of a Speech Object: a Speech Object Editing feature. |
| – ModifiedObjects | Objects whose acoustics are modified. When present, either LUFS is present or each entry has an AcousticProfile or a SpatialAttitude. |
| – Objects[] | The entries: ObjectID, AcousticProfile (Object part), SpatialAttitude. |
| – ListedObjects | Asks the Editing AIM that keeps the Objects or Scenes of a Kind to list them. The response (UserCommandRS.ListedObjects) gives their names, never storage keys. |
| – Kind | One of Audio Object, Basic Audio Object, Speech Object, Basic Speech Object, Audio Scene, Speech Scene, Multimodal Scene, or All (everything the editing AIM keeps). Required. |
| – ObjectID | The name of the one Scene or Object to list, of the Kind given (not All). For a Scene the response gives the number of its members and, for each member, its name and its PoV – its position and orientation as provided in the Scene; no Object is touched. Absent, everything of the Kind is listed. |
| – ClosedSpace[] | The space the open Scene is in – a room built round its Objects: one Closed Space, by ID or in full. It replaces the one the Scene had. |
| – ModifiedScene | The acoustics of the open Scene: what happens to the sound of its Objects on the way to the listener. |
| – AcousticProfile | The Scene part of the Acoustic Profile; it is the one the Scene has from now on. |
| – TranslatedObjects | Speech Objects to translate into another language, with Text and Speech Translation (MMC-TST). The source language is the one the Speech Object’s own Qualifier states. The translated Speech Object replaces the original in the Scene, at its place. |
| – Objects[] | Each entry has an ObjectID and a SpeechQualifier, both required. |
| – ObjectID | The Speech Object, by name. |
| – SpeechQualifier | The Qualifier of the translated Speech Object: its Attributes.Metadata.Language states the target language. |
| UserCommandRS | The response: how the User Command was executed, output by the AIM that executed it, under the UserCommandID of the request. Outcome is required. |
| – ReportTime | When the report was made. |
| – Outcome | Done: every action done; Partly: some; Failed: none; Ignored: the command names nothing this AIM executes. |
| – Actions[] | One entry per action of the request. |
| – Action | The field of UserCommandRQ the action comes from: UserPoV, LUFS, RevokedUserCommandID, AcquiredObject, DeliveredObject, AddedObjects, RemovedObjects, DeletedObjects, MovedObjects, ChangedObjects, ModifiedObjects, ClosedSpace, ModifiedScene, TranslatedObjects, ListedObjects. |
| – ObjectID | The name of the Object or Scene acted on. |
| – Outcome | Done, Failed or NotSupported. |
| – ResultID | The name of what the action produced: every edit is a new version, which has the name of the Object or Scene edited. |
| – Reason | Why the action was not done (at most 1024 characters). |
| – ListedObjects[] | The answer to a ListedObjects request: what the AIM keeps of the Kind asked for, by name – never a storage key. |
| – ObjectID | The name of the Object or Scene. |
| – Kind | Audio Object, Basic Audio Object, Speech Object, Basic Speech Object, Audio Scene, Speech Scene or Multimodal Scene. |
| – MemberObjectIDs[] | For an Audio Object, a Speech Object or a Scene: the names of the Objects it is made of. |
| – Duration | Of an Object: how long it lasts, in seconds (that of its sound; for an Object made of others, the end of the child that lasts longest inside it). Absent where the AIM cannot tell. |
| – ChildCount | Of an Object: the number of children it is made of (0 for a Basic Object). |
| – Version | Of an Object: its version – 1 for the first, one more for every edit. |
| – ObjectCount | Of a Scene named in the request: the number of its members. |
| – Members[] | Of a Scene named in the request: each member by its name, with its PoV. |
| – ObjectID | The name of the member. |
| – PoV | Its position and orientation as provided in the Scene (Spatial Attitude). |
| DataXMData | Data Exchange Metadata describing the User Command instance. |
| DescrMetadata | Descriptive metadata (at most 2048 characters). |
5 Conformance Testing
A Data instance conforms with User Command (CAE‑UCM) if:
- Its JSON Object validates against the User Command JSON Schema, and contains exactly one of UserCommandRQ and UserCommandRS.
- Any included JSON Objects validate against their respective JSON Schemas.
- All data elements:
- Have the specified Data Types.
- Conform with the qualifiers defined in their JSON Schemas.
