CasparCG OSC Protocol
From CasparCG Wiki
From v2.0.4 onwards, CasparCG Server adds support for the Open Sound Control (OSC) protocol which sends real-time data and events from CasparCG Server over UDP to a client.
In CasparCG Server, the OSC implementation provides one way support only, CasparCG Server provides a client interface, sending status information to an OSC server but does not listen for OSC datagrams from remote clients.
When a client establishes a connection to the AMCP port configured for the server, an OSC client is started by CasparCG Server against the AMCP client's IP, using a default UDP port configurable in casparcg.config (see below), this OSC client will expire when the AMCP connection that initiated it ends. Persistent OSC clients can be set-up by adding them to the list of persistent clients in CasparCG config (as below).
Clients receive events by connecting to the OSC client interface provided by CasparCG Server, and then issuing a RegisterMethod command to subscribe to different properties and actions made available by the CasparCG Server. Looking at the source code for the Caspar Monitor example client, in particular Form1.cs would be a good place to start in understanding CasparCG Server and OSC.
The following is an example of the configuration entries which relate to the OSC implementation, as described above, persistent OSC clients can be added to the list of predefined clients by adding a <predefined-client> element, in the example below, an OSC client is defined for an OSC server on localhost port 5253.
<osc> <default-port>6250</default-port> <predefined-clients> <predefined-client> <address>127.0.0.1</address> <port>5253</port> </predefined-client> </predefined-clients> </osc>
The OSC protocol uses a fairly simple message structure containing an address pattern and various arguments corresponding to each pattern, the protocol also includes other detail as described on the Wikipedia entry. The below is a list of address patterns and details of what response subscribing to this will trigger, this list is currently a work in progress and does not represent all of the addresses available, the example client by Andy Mace at the bottom of this page will show you what your CasparCG Server is doing live. It is important to note that OSC sends messages for things that are active only, if CasparCG Server is not doing anything you will only see a small number of lines.
Number ranges such as [0-9] should be substituted for the appropriate channel, layer or output port you are trying to monitor. More than one digit is acceptable in all of these cases but not specified for brevity.
Output and Channel setting Messages
Output messages contain information about CasparCG Server Consumers, this largely contains information about which Consumers are active, alongside this are other messages such has format and profiler messages which contain more information about what the channel is doing.
|/channel/[0-9]/||format||PAL||The video format of the channel|
|profiler/time||0.041 | 0.04||The amount of time that CasparCG Server is spending rendering the frame, two arguments are sent in this message, what it is and what it should be as shown in the example.|
|output/port/[0-9]/type||screen||A message like this will exists for each of the outputs in use, with the default CasparCG config file in use this will result in two rows; one of type screen, and one of type system-audio. Current types are screen, system-audio, decklink, bluefish and file|
|output/port/[0-9]/frame||200 | 922222222888836854||The number of frames that have been created by the consumer on this port, the example indicates that 200 frames have been written to disk and that a maximum of 922222222888836854 can be written.|
Stage messages contain properties related to CasparCG Server layers and the producers that are contained within them.
General Stage messages
The following messages do not directly relate to a producer.
|/channel/[0-9]/stage/layer/[0-9]/||time||101.24||Seconds the layer has been active|
|frame||2531||Time in frames that the layer has been active|
|profiler/time||0.39 | 0.4||Actual | Expected time on frame|
|paused||True/False||Whether the layer is paused or not|
The messages below may be produced when an object utilising the FFMPEG Producer is in use on the stage.
|/channel/[0-9]/stage/layer/[0-9]/file/||time||12 | 400||Seconds elapsed on file playback | Total Seconds|
|frame||300 | 10000||Frames elapsed on file playback | Total frames|
|fps||25||Framerate of the file being played|
|path||AMB.mp4||Filename and path (if file is in a sub-folder) of the media file, paths relative to the media folder defined in the config file|
|video/width||1920||Frame width of the video file|
|video/height||1080||Frame height of the video file|
|video/field||progressive||Scan type of the video file, progressive or interlaced|
|video/codec||H.264 /AVC||Codec of the video file|
|audio/sample-rate||48000||Audio sample rate of this files audio track|
|audio/channels||2||Number of channels in this files audio track|
|audio/format||s16||Audio compression format, in this case uncompressed 16 bit PCM audio|
|audio/codec||Audio codec for the audio track in this file|
|/channel/[0-9]/stage/layer/[0-9]/||loop||1||Whether the file is set to loop playback or not, only applies to ffmpeg inputs of type file not stream or device.|
The messages below may be produced when an object utilising the Flash Producer is in use on the stage.
The majority of information from CasparCG's compositing module is not yet made available via OSC (an issue is open for this), the only information available currently is audio related as listed below.
|/channel/[0-9]/mixer/audio/||nb_channels||2||Number of audio channels in use on this CasparCG channel|
|[0-9]/dBFS||-20||Audio level in dBFS|
A couple of members of the CasparCG community have constructed simple OSC example clients to demonstrate its use, these are available from the links below. Pleaes note that in both cases these are basic examples of how to use the OSC protocol and intended to help understand how it works.
|Client||Description||Forum post||Download Links|
|Caspar CG OSC Monitor||Same name, different author to the below one, this application shows an implementation of the OSC Server in C# allowing UDP messages generated from Caspar CG Server to be shown, a few filter options are provided to limit which messages are shown. This is tested against Caspar CG Server v2.0.7||N/A||https://github.com/duncanbarnes/Caspar-CG-OSC-Monitor|
|CasparCG OSC Monitor||Andy Mace's OSC Monitor shows all OSC messages provided by CasparCG Server 2.1. Please note that this client was built when Caspar used TCP communication for OSC, as Caspar now uses UDP communication, this client currently does not work.||CasparCG Forum||https://github.com/CasparCG/Tools/tree/master/csharp/OSCMonitor|
|Caspar Monitor||This example by forum user Interpreter shows what's currently playing on channel 1 layer 1 on a Caspar server running on localhost.||CasparCG Forum||http://www.monoscopio.se/downloads/CasparMonitor.zip|