Streaming API¶
Endpoints¶
Method |
Path |
Description |
---|---|---|
GET |
Retrieve the current streaming status and settings |
|
PUT |
Start streaming to the LaMetric device |
|
PUT |
Stop streaming to the LaMetric device |
Overview¶
The LaMetric Streaming API allows you to stream content to a LaMetric SKY device. This section describes the available endpoints for the Streaming API and provides detailed information about the LMSP (LaMetric Streaming Protocol ) used for UDP streaming.
In general, the streaming process looks as follows:
API Client retrieves information about streaming status and the size of the canvas from the Device
API Client starts a stream and receives UDP port and Session Id
API Client sends LMSP packets as fast as 30 FPS
API Client stops stream when done.
Get Stream Status¶
URL |
/api/v2/device/stream |
Method |
GET |
Authorization |
basic |
API Version |
2.3.0 |
Description¶
Retrieves the current stream status and settings.
Body¶
{
"protocol": "lmsp",
"version": "1.0",
"port": 9999,
"status": "[stopped|receiving]",
"canvas": {
"pixel": {
"size": { "width": 8, "height": 16 }
},
"triangle": {
"size": { "width": 16, "height": 32 }
}
}
}
Stream Object |
||
Field |
Type |
Description |
|
Integer |
|
|
String |
Version in format “<major>.<minor>”, version of the protocol |
|
Boolean |
UDP port opened on the device. Usually 9999 |
|
String |
|
|
Object |
Canvas with “square” pixels, contains size property |
|
Object |
Canvas with “triangular” pixels, contains size property |
Example¶
Request
GET https://<device ip address>:4343/api/v2/device/stream
Authorization: Basic <Base64("dev:<device API key>")>
Content-Type: application/json
Accept: applciation/json
Response
{
"protocol": "lmsp",
"version": "1.0",
"port": 9999,
"status": "stopped",
"canvas": {
"pixel": {
"size": { "width": 24, "height": 8 }
},
"triangle": {
"size": { "width": 48, "height": 16 }
}
}
}
Start Stream¶
URL |
/api/v2/device/stream/start |
Method |
PUT |
Authorization |
basic |
API Version |
2.3.0 |
Description¶
Before you will be able to stream UDP packets to the device, you need to start the streaming by calling this endpoint. This method also allows to configure some aspects of the streaming, like:
Render mode
Fill Type
Post processing
Render Mode
There are two render modes - Pixel and Triangle.
In pixel mode you control individual square pixels. Best suits for cases when digital image or text should be displayed.
In triangle mode you control individual triangles. Best suits for abstract effects.
Fill Type
LaMetric SKY devices have limitation on the canvas size. In some cases actual screen real estate can be larger than the canvas size available for drawing. In this case streamed content will be upscaled or tiled to fill the area.
Post Processing
Content can be displayed on LaMetric device without modifications or additional effect can be applied. Currently fading_pixels effect is supported
Body¶
{
"canvas": {
"fill_type": "[scale|tile]",
"render_mode": "[pixel|triangle]",
"post_process": {
"type": "[none|effect]",
"params": {
"effect_type": "fading_pixels",
"effect_params": {
"smooth": true,
"pixel_fill": 1,
"fade_speed": 0.005,
"pixel_base": 0.05
}
}
}
}
}
Canvas Object |
||
Field |
Type |
Description |
|
String |
Valid values are
|
|
String |
Valid values are
|
|
Object |
Controls post processing effects |
PostProcess Object |
||
Field |
Type |
Description |
|
String |
Optional.
|
|
Object |
Optional. Effect parameters |
Params Object |
||
Field |
Type |
Description |
|
Stirng |
Only |
|
String |
Paremeters of a specific effect |
Fading Pixels Parameters Object |
||
Field |
Type |
Description |
|
Boolean |
|
|
Integer |
fill area percentage, [0..1]. |
|
Float |
pixel brightness that is added to the pixel per rendering cycle, [0..1]. Bigger the number, faster the pixel fades in/out |
|
Float |
base pixel brightness, [0..1], where |
Response¶
{
"success": {
"data": {
"canvas": {
"fill_type": "[scale|tile]",
"render_mode": "[pixel|triangle]"
},
"port": 9999,
"session_id": "<session_id>",
"status": "[receiving|stopped]"
},
"path": "/api/v2/device/stream/start"
}
}
Response Object |
||
Field |
Type |
Description |
|
Number |
UDP port where LMSP packets should be sent |
|
String |
Session ID is used in LaMetric Streamin Protocol to send UDP packets. If current session ID on the device differs from the one in UDP packet – content will not be displayed. |
Example¶
Request
PUT /api/v2/device/stream/start
Host: 192.168.170.83:4343
Authorization: Basic <Base64("dev:<device API key>")>
Content-Type: application/json
Accept: applciation/json
{
"canvas": {
"fill_type": "scale",
"render_mode": "pixel",
"post_process": {
"type": "none"
}
}
}
Response
Status 200
{ "success": { "data": { "canvas": { "fill_type": "scale", "render_mode": "pixel" }, "session_id": "a2891aa891ab4f8e8a1a16eb319b00f3", "status": "receiving", "port": 9999 }, "path": "/api/v2/device/stream/start" } }
Stop Stream¶
URL |
/api/v2/device/stream/stop |
Method |
PUT |
Authorization |
basic |
API Version |
2.3.0 |
Description¶
Stop streaming content to the LaMetric device.
Example¶
Request
GET /api/v2/device/stream/stop
Host: 192.168.170.83:4343
Authorization: Basic <Base64("dev:<device API key>")>
Content-Type: application/json
Accept: applciation/json
Response
{
"success": {
"data": {
"status": "stopped"
},
"path": "api/v2/device/stream/stop"
}
}
LaMetric Streaming Protocol (LMSP)¶
The LMSP protocol is used for streaming content to the LaMetric SKY device via UDP. Below is a detailed description of the UDP packet format used by LMSP.
UDP Packet Format¶
Field |
Size |
Description |
---|---|---|
Protocol name |
4 bytes |
|
Version |
2 bytes |
|
Session ID
|
16 bytes
|
UUID, if session ID is different from current session ID -
packets will be ignored
|
Content Encoding |
1 byte |
|
Reserved |
1 byte |
|
Canvas Area Count |
1 byte |
The number of canvas areas in this payload (parts of the image) |
Reserved |
1 byte |
|
Canvas Area X |
2 bytes |
|
Canvas Area Y |
2 bytes |
|
Canvas Area Width |
2 bytes |
|
Canvas Area Height |
2 bytes |
|
Canvas Area Data
Length
|
2 bytes
|
Length of the binary data
|
Canvas Area Data |
<var> |
Binary data |
The total size of the UDP packet header is 36 bytes, plus the size of the binary data part.
Tip
When handling multi byte values, use little endian byte order
Example¶
In this example we will be streaming image content to a LaMetric SKY device in pixel mode
1. Get the canvas size from the device¶
First of all we need to know the size of canvas on a device.
Request
GET /api/v2/device/stream HTTP/1.1
Host: 192.168.170.83:4343
Authorization: Basic <Base64("dev:<device API key>")>
Accept: application/json
Content-Type: application/json
Response
{
"protocol": "lmsp",
"version": "1.0",
"port": 9999,
"status": "stopped",
"canvas": {
"pixel": {
"size": { "width": 24, "height": 8 }
},
"triangle": {
"size": { "width": 48, "height": 16 }
}
}
}
Looks like the pixel canvas is 24x8.
2. Start a stream¶
Will be using fill type scale
and render mode pixel
without post processing effect.
PUT /api/v2/device/stream/start HTTP/1.1
Host: 192.168.170.83:4343
Authorization: Basic <Base64("dev:<device API key>")>
Accept: application/json
Content-Type: application/json
Content-Length: 481
{
"canvas": {
"fill_type": "scale",
"render_mode": "pixel",
"post_process": {
"type": "none"
}
}
}
Response
{
"success": {
"data": {
"canvas": {
"fill_type": "scale",
"render_mode": "pixel"
},
"port": 9999,
"session_id": "a2891aa891ab4f8e8a1a16eb319b00f3",
"status": "receiving"
},
"path": "/api/v2/device/stream/start"
}
}
Status receiving
indicates that the device is listening for the incoming UDP packets.
We also will need the port
and the session_id
on the next step.
3. Send UDP packets to the port 9999 of the following structure as fast as 30 FPS¶
Now we use Session Id, canvas size and the actual content to make the LMSP Packet and then send it to the port 9999 of the device.
[
0x6c, 0x6d, 0x73, 0x70, // "lmsp"
0x01, 0x00, // 1
0xa2, 0x89, 0x1a, 0xa8, 0x91, 0xab, 0x4f, 0x8e, 0x8a, 0x1a, 0x16, 0xeb, 0x31, 0x9b, 0x00, 0xf3, // session id
0x00, // Raw data (no encoding)
0x00, // reserved (not used)
0x01, // 1 area
0x00, // reserved (not used)
0x00, 0x00, // x = 0
0x00, 0x00, // y = 0
0x18, 0x00, // width = 24 = 0x18 = 0x18,0x00
0x08, 0x00, // height = 8 = 0x8 = 0x08,0x00
0x40, 0x02, // data length = 24 * 8 * 3 = 576 = 0x240 = 0x40,0x02
0x00, 0x00, 0x00, ... // data in RGB888 format (R, G, B, R, G, B, ...)
]
4. Stop the stream when done¶
When stream gets stopped, device will return to its normal operation mode.
PUT /api/v2/device/stream/stop HTTP/1.1
Host: 192.168.170.83:4343
Authorization: Basic <Base64("dev:<device API key>")>
Accept: application/json
Content-Type: application/json