Service API
Moth provides service APIs for data streaming and media services. Publishing and subscribing through these APIs is one of the main ways Moth is used.
Service API overview
Moth service APIs are used to implement live streaming, video conferencing, chat, and similar media features.
Protocol
ws | wss: protocol used to connect to the Moth server. Use secure WebSocket (wss) when needed.
API types
Moth service APIs are divided into the following two groups.
| API | Message format | Supported version |
|---|---|---|
/shot/ws/{pub,sub} | JSON messages | v0.0.1 |
/pang/ws/{pub,sub,ctl,meb} | Text/Binary message | v0.0.6 |
Pathnames
The Moth service API uses different pathnames for specific operations.
| API type | Function | Supported version |
|---|---|---|
/pang/ws/pub | Publishes data to the given channel (source, track). | v0.0.3 |
/pang/ws/sub | Subscribes to data from the given channel (source, track). | v0.0.3 |
/pang/ws/ctl | Controls how resources in the channel are used, including settings such as the stream key, for source/track. | v0.0.5 |
/pang/ws/meb | Sends and receives data on the given channel (source, track) and broadcasts it to all participating sessions. | v0.0.6 |
Options for /pang API
You can configure the following options.
| Option | Description | Usage |
|---|---|---|
channel=<xid> | Uses the channel identified by <xid>. | Required |
channel=instant & name=<string> | Creates and uses a temporary instant channel without registration, using the given name. | Required when not using an xid channel |
| source | Uses the source. If omitted, the default source base is used. source=["base" | <string>] | Optional |
| track | Uses the track. If omitted, the default track video is used. track=["video" | <string>] | Optional |
| mode | Specifies how the buffer is organized. Choose single or bundle. mode=["single" | "bundle"] | Optional |
| style | Specifies how data is received. Choose mono or multi. style=["mono" | "multi"] | Optional |
| wait | Specifies the receive wait mode. With force, the subscriber waits even if there is no publisher. wait=["force"] | Optional |
| timeout | Lets the subscriber wait for <second> even after connecting when no data is sent. timeout=[30 | <1~3600>] | Optional |
| len | Receives published data using the specified number of buffer slots. len=[5 | <2~10>] | Optional |
| total | Specifies the total number of generated buffers. total=[<2~10>] | Optional |
| order | Uses the indexed buffer among the generated buffers. order=[<0~9>] | Required when total is used |
| codec | Specifies the desired codec. Currently conversion among JPEG, VP8, and H264 is supported. codec=[jpeg|vp8|h264] | Optional (sub) |
Channel authorization
Moth requires a Stream key to authorize channel usage.
/pang/ws/pub?channel=<xid>&track=colink&mode=bundle&mime=video/h264&key=<string>
When using the service API or configuring a channel, provide the authentication key through the key parameter.
Example
ws(s)://<server_addr:port>/pang/ws/pub?channel=btlb3pjpc98lsdbc0lj0