Session Service
1. Start Project
2. Start Publish Context
HTTP Remoting Service

Remoting over HTTP

Version 6 comes with a VMS module that makes the Remoting4 OSC protocol transparent to HTTP / HTTPS

Session Service

Ventuz Runtime and Ventuz Designer hook this service into the VMS as a dynamic module. So in combination with the Session Service you can easily achieve a launch and a shutdown of the Runtime and/or access the Designer. See projects and publish contexts here: http://localhost:20404/vms_session_service/1.0

Start Project

To launch Ventuz Runtime with a project (here 0c31bb73-f9e1-430f-909f-e3a985adf41a) request this URL:

http://localhost:20404/vms_session_service/1.0/projects/0c31bb73-f9e1-430f-909f-e3a985adf41a/action/start

Additional command line arguments can be passes as query fields.

http://localhost:20404/vms_session_service/1.0/projects/ lists all available projects

Start Publish Context

To launch Ventuz Runtime with a Ventuz Publish Context (here 62a7b420-99ca-4704-8848-1e804ca4cff0) use this URL:

http://localhost:20404/vms_session_service/1.0/publishcontexts/62a7b420-99ca-4704-8848-1e804ca4cff0/action/launch?-warmup

Additional command line arguments can be passes as query fields. The argument -warmup will load all scenes specified in this context and cues all templates for two frames.

http://localhost:20404/vms_session_service/1.0/publishcontexts lists all available publish contexts

HTTP Remoting Service

Please have this notes in mind:

Every HTTP/S request is a blocking call
Every HTTP/S request will establish a new TCP connection (as of today), so using HTTPS might be slow!
Responses are usually formatted as JSON parse-able text
Async responses like log message or status changes can not be received

Requests

A request URL always start with the service address:

http://localhost:20404/remoting/1.0/Remoting4

This URL is directly extended by the OSC command address described in the Remoting4 documentation. The command /Ventuz/Info is issued by requesting this URL:

Request: GET http://localhost:20404/remoting/1.0/Remoting4/Ventuz/Info

Response: (example)

{
  Ventuz: {
    Version: "6.0.0.128",
    Edition: "Ventuz 6.0 V6.0.0 128 R21772",
    Mode: "Designer"
  },
  Machine: {
    Name: "DESKTOP-NSJ5IPI",
    ID: 0,
    GroupID: 0,
    ProcessID: 18508,
    ProcessGUID: "2838e71e-6c22-4c5b-b7d6-cee37a4db194",
    SystemID: "VZ_M80-55022900324_BFEBFBFF000306F2_00330-80109-59023-AA022",
    Rate: [ 59954, 1000 ],
    Pipes: [ "Graphics" ]
  },
  Project: {
    Title: "Hockey",
    ID: "15e6698c-7726-4be1-9ede-3ee1c58d9006"
  },
  PublishContext: null
}

Arguments

The HTTP protocol accepts two different methods:

GET arguments / parameters have to be encoded into the query fields of the request URL
POST arguments / parameters are passed as multi-part-form-data

In both methods the arguments have to be formatted in the order as described in the Remoting4 documentation as JSON parse-able text. The argument RequestID have to be omitted.

Example:

Request: http://localhost:20404/remoting/1.0/Remoting4/0000/Load?3dmask&1

SceneIdentity = 3dmask
LoadFlags = 1

Response:

{
  IID: "FTKT",
  IsNew: true
}

Responses

Simple responses are transferred as JSON values or arrays. Complex responses are returned as JSON objects (dictionaries)

The /0000/Snapshot command is an exception: it delivers a binary response containing the image on success.

http://localhost:20404/remoting/1.0/Remoting4/0000/Snapshot?1&0&0&0&0&0&0&0&true

Errors

Request: http://localhost:20404/remoting/1.0/Remoting4/0000/ThisIsNoCommand

Response:

{
  ErrorCode: 501,
  Error: 501,
  Message: "Unknown or invalid address /0000/ThisIsNoCommand",
  Details: "Method 'Ventuz.Kernel.CModel.Remoting4Server+Session.Request_IID_ThisIsNoCommand' not found."
}

Request: http://localhost:20404/remoting/1.0/Remoting4/0000/Load?unknownscene

Response:

{
 ErrorCode: 404,
 Error: 404,
 Message: "Load failed",
 Details: "Remoting2: unknownscene: Could not find file 'D:\PROJECTS_TIMELINE\NAB_Eishockey\Scenes\unknownscene.vzs'.: 
Invalid Scene"
}

Returned error codes are also described in the Remoting4 documentation.

Extra Commands

The Remoting via HTTP protocol has extra command:

Switch Project

/Ventuz/SwitchProject with one argument:

filename_or_guid where guid is a project or a publish context id

Switches the current project or publish context. Unloads all scenes, resets renderer and load another project

Play Template

Version 6.00.xx

/0000/00/Play with two arguments:

options (int), same options as the Cue command
data (string), template data or URL or empty string

Cues and Takes a template. This is actually a combination of the Cue and Take command with sync execution. This makes it very easy to bring template based graphics on-air without maintaining complex communication. Using an empty string for data issues a cue-out on the specified port (here port 00 of pipe 0000). Options are the same values for the Cue command. See TransitionOptions in the Remoting4 documentation.

Examples

Get Ventuz Info: http://localhost:20404/remoting/1.0/Remoting4/Ventuz/Info

Set Project Data Background to Red: http://localhost:20404/remoting/1.0/Remoting4/Ventuz//Background?Red

Get Ports of Layout Scene in Pipe 0000: http://localhost:20404/remoting/1.0/Remoting4/0000/Ports

Get Status of Port 00 of Layout Scene in Pipe 0000: http://localhost:20404/remoting/1.0/Remoting4/0000/00/Status

Let 0000 load a scene cube.vzs: http://localhost:20404/remoting/1.0/Remoting4/0000/Load?cube

Validate scene IID SFBD: http://localhost:20404/remoting/1.0/Remoting4/SFBD/Validate

Activate scene SFBD in Port 00 of Layout Scene in Pipe 0000: http://localhost:20404/remoting/1.0/Remoting4/0000/00/Status?SFBD

Deactivate scene in Port 00 of Layout Scene in Pipe 0000: http://localhost:20404/remoting/1.0/Remoting4/0000/00/Status?null

Release scene SFBD from memory (this requires an deactivation from Port before!): http://localhost:20404/remoting/1.0/Remoting4/SFBD/Release

Get SceneModel of scene IID PGOB: http://localhost:20404/remoting/1.0/Remoting4/PGOB/SceneModel

Get Scene Data .PositionX from current scene: http://localhost:20404/remoting/1.0/Remoting4/0000/00//.PositionX

Set Scene Data .PositionX from current scene to 1.25: http://localhost:20404/remoting/1.0/Remoting4/0000/00//.PositionX?1.25

Cue Template Data UI: http://localhost:20404/remoting/1.0/Remoting4/0000/00/Cue (via HTML form)

Cue Template Data URL encoded: http://localhost:20404/remoting/1.0/Remoting4/0000/00/Cue?0&ventuz://templates/templates%7Cremoting4%20demo%203%20simple/Animation1/F_and_V_Info&43F275B7-C366-40EF-8E08-A3E73395FFCC

Clear Template URL encoded: http://localhost:20404/remoting/1.0/Remoting4/0000/00/Cue?0&null&43F275B7-C366-40EF-8E08-A3E73395FFCC

Take cued data: http://localhost:19404/remoting/1.0/Remoting4/0000/00/Take?43F275B7-C366-40EF-8E08-A3E73395FFCC

The URL format of the Cue commands is: http://localhost:20404/remoting/1.0/Remoting4/0000/00/Cue?´TransitionOptions´&´TemplateAddress(URL-Encoded)´&´TakeId-Guid´

Ventuz Introduction

Quick Guides

General

Ventuz Designer

Ventuz Director

Ventuz Runtime & Configuration

How To

Ventuz Node Reference

Advanced and Development

Misc

Table of Contents

Remoting over HTTP

Session Service

Start Project

Start Publish Context

HTTP Remoting Service

Requests

Arguments

Responses

Errors

Extra Commands

Switch Project

Play Template

Examples