The vMix TCP API provides the same functionality as the HTTP WEB API but with lower processing overhead making it suitable for use in embedded devices that have limited XML parsing capabilities.

It also provides the ability to subscribe to a TALLY event that will automatically send TALLY updates to the client.


Preface

The vMix TCP API is designed to be a simple protocol that can be expanded in the future without breaking compatibility with existing clients.

Therefore it employs a simple text command/response architecture, similar to other standard protocols such as SMTP.

As a result, fixed length binary structures have been avoided.

The <> symbols in this specification refer to mandatory commands/responses while [] are always optional.


Connection


TCP connection on fixed port 8099


Formatting


All messages are UTF8 encoded and \r\n terminated unless specified otherwise.

This is compatible with ASCII only devices for the vast majority of commands with the exception of those that might retrieve incompatible characters such as in Titles.


Responses


 Responses are space delimited \r\n terminated strings with optional binary data in the following format:


       <command> <status/length> [response]\r\n

       [data]


 Examples:

 MYCOMMAND OK This is the response to MYCOMMAND\r\n

 MYCOMMAND ER This is an error message in response to MYCOMMAND\r\n

 MYCOMMAND 28\r\n

 This is optional binary data

 MYCOMMAND 28 This is a message in addition to the binary data\r\n

 This  is optional binary data


 Notes: 

 a. Optional binary data is the exact length specified in <status/length> including additional terminating characters such as \r\n
which are always appended to the end of multiline text such as from XMLTEXT.

 b. Single line responses such as ER should always be expected and handled, even for commands that usually return binary data.

 c. OK (Success), ER (Error) and length are the only three statuses to expect.


Events


 Events are responses that can be sent at any time to the client in response to state changes.

 All clients should be written to handle any response at any time, as these may be received in the middle of sending a command but before

 receiving that particular commands response. Therefore it is recommended clients operate "asynchronously" without waiting for a particular command response.

  

Commands


 TALLY

 Event Supported: Yes

 Example Request: TALLY\r\n

 Example Response: TALLY OK 0121...\r\n

 Description: Returns a list of tally values where 0 = off, 1 = program, 2 = preview.

 The list is padded to the total number of inputs currently added to vMix and may have up to 1000 entries as a result.

 (Maximum possible length = 9 + 1000 + 2 = 1011 bytes)


 FUNCTION

 Format: FUNCTION <Function> [QueryString]\r\n

 Example Request: FUNCTION PreviewInput Input=5\r\n

 Example Request: FUNCTION SetText Input=3&SelectedName=Headline&Value=Hello world\r\n

 Example Response: FUNCTION OK PreviewInput\r\n

 Example Response: FUNCTION ER Error message\r\n

 Description: Calls a Shortcut Function with optional Query String. This Query String exactly matches the syntax

 and layout of HTTP WEB API. Standard URL escape/encoding characters should be used.


 ACTS
 Event Supported: Yes

 Format: ACTS <ActivatorName> [InputNumber]\r\n

 Example Request: ACTS Input 1\r\n

 Example Response: ACTS OK Input 1 1\r\n

 Description: Retrieves the current state of an Activator. This can be used even if a particular activator has not been added in vMix and is handy
 for retrieving state information for use with custom controllers. 
 To subscribe to all activator events use the command SUBSCRIBE ACTS. This will retrieve all events
 as it is not possible to subscribe to only a particular activator.
 The input number can be left blank for Input, InputPreview and Overlay1,2,3,4 to show the currently assigned input, if any, otherwise ER No Input will be returned.
 Return values will always be between 0 and 1. In contrast to the XML output this means boolean True/False becomes 1/0 and integer values such as Volume become 32bit floating point values.


 XML

 Example Request: XML\r\n

 Example Response: XML 37\r\n

 <vmix><version>x.x.x.x</version></vmix>

 Description: Returns the current XML state as binary data encoded in UTF-8 format.

 The data length has no size limit and can be quite large, therefore embedded devices should use the XML parsing commands below to efficiently retrieve values.


 XMLTEXT

 Format: XMLTEXT XPATH

 Example Request: XMLTEXT vmix/inputs/input[1]/@title\r\n

 Example Response: XMLTEXT OK This is the title of the first input\r\n

 Example Request: XMLTEXT vmix/inputs/input[6]/text[@name='Headline']\r\n

 Example Response: XMLTEXT OK This is the value of Headline text field in title input that is the number 6 (index 5) input.\r\n

 Description: Uses the XPATH syntax to retrieve individual text values of the XML state.

 To simplify parsing, multiline text will use the status length, while single line data will always use a single line response.

 

 SUBSCRIBE

 Format: SUBSCRIBE <COMMAND>\r\n

 Example Request: SUBSCRIBE TALLY\r\n

 Example Response: SUBSCRIBE OK TALLY\r\n

 Description: Subscribe to an event/command. Event responses matching the selected command may begin immediately, even before the SUBSCRIBE response is received.

 Event responses will continue to be received until either a. UNSUBSCRIBE is called or b. the connection is closed.


 UNSUBSCRIBE

 Format: UNSUBSCRIBE <COMMAND>\r\n

 Example Request: UNSUBSCRIBE TALLY\r\n

 Example Response: UNSUBSCRIBE OK TALLY\r\n

 Description: Due to the internal event queue in vMix, event responses may continue to be received briefly after the UNSUBSCRIBE command has been called.


 QUIT

 Description: Closes the connection