Wavestore Simple Protocol (HTTPS)
The Wavestore has a simple REST API, known as "Wavestore Simple Protocol", for some basic operations. It is accessible via simple HTTPS commands.
This is in addition to the full network API and the ONVIF API.
These simple commands provide a simple interface for applications which do not wish to use the full API. The output is broadly textual and line based. These commands are Wavestore specific.
This document is correct for Wavestore V6.40 and later. For historical revisions, see below.
Most commands can be accessed on http: (port 80) or https: (port 443). RTSP can be accessed on the normal RTSP port (port 554).
Cameras
This command gets a list of current cameras which can be viewed live.
https://<ip>/simple/camera
or
https://<ip>/simple/Cameras
Reply
HTTP/1.0 200 OK Content-Type: text/plain; charset=UTF-8 Content-Length: xxx 00001 Car Park 00002 Camera 2 Road 00022 Q24 Office 00025 Axis Front door 00026 AXIS PTZ
- If you request /Cameras, you'll get a reply with "Content-Type: application/x.ws".
- If you request /camera, the reply will have "Content-Type: text/plain; charset=UTF-8" which is probably easier to use. from 6.20
But both will return the same body, with UTF-8 character set.
The body data:
- The first field, terminated by space, is the hexadecimal channel number, and needs an "/rtsp/" prefix to become the rtsp path to access this camera (eg, in full the URL to the "Axis Front door" camera is "rtsp://ip/rtsp/00025").
- The remaining field (terminated by CRLF) is the name of the camera. The character set encoding is UTF8.
Bounds
The simple/bounds api returns the bounds of recording on the specified channel; the channel is as 5 digits as above. The timestamps are in ISO format, the start on one line and the last recording time on the next. Available from 6.20.
https://<ip>/simple/bounds/<channel>
Reply
20190913T080015 20191002T162006
A track with no recording will return:
END END
Recordings
The simple/recordings api returns the details of recordings on the specified channel; the channel is as 5 digits as above. Each line contains a range of times in ISO format. Normally recordings within a second or two of each other are treated as the same recording. Available from 6.20.
https://<ip>/simple/recordings/<channel>
Reply
20190913T080015-20190913T080121 20190913T080121-20190913T080320 20190913T080351-20191002T162006
Export
Exports can be performed using the /simple/export interface. Note this is only available over https (not http). These are done using wsexporttool, so the parameters are the same.
https://<ip>/simple/export?parameters...
Parameters are given in standard URL format as name=keyword and multiple parameters are joined with &
- Typical parameters include user and pwd for the Wavestore user who is performing the export.
- tracks will list the tracks to be exported
- to and from (or toUTC and fromUTC) will list the range
- format will show the format of the export: wsb for native export (default) or mp4 or similar.
https://<ip>/simple/export?user=user&pwd=a&tracks=1.1&from=29/10/2024-10:00:00.000&to=29/10/2024-10:01:00.000
- If the export succeeds, it will return 200 OK status and will return an export file.
- If the user/pwd is wrong, it will return 403 Forbidden and the messages from wsexporttool
- If another error occurs, it will return 400 Bad Request and the messages from wsexporttool
Help text can be obtained by:
https://<ip>/simple/export?help
HTTP Data streaming
Streaming of video, audio or metadata is possible over HTTP multipart/x-mixed-replace. It is modelled on the rtsp streaming command. from 6.56.
- Paths like /data/00001 is permitted as the path component. The format is /data/<CHANNEL> where CHANNEL is a 5 digit hexadecimal channel number. Note that the channel number is in hexadecimal, so channel 13 is /data/0000d.
- The paths can be obtained from the /simple/camera command
- If no starttime is provided then Live is streamed.
The first digit of the 5-digit channel will show which stream (live) or which track (playback). See the RTSP docs below for details.
We can add starttime= to the URL for playback. This does not support endtime.
- /data/00001?starttime=20190329T103000Z
The reply is a stream of data which remains open until the end of recording is reached or the requester closes the connection. For each record: header fields X-DataTime: give the timestamp of the data in milliseconds, and X-DataType: gives a single character showing the type in addition to standard fields like Content-Size:
--datastream Content-Type: application/octet-stream Content-Length: nnn X-DataTime: tttttttt X-DataType: c
If the end of recording is reached a text record reporting this is added:
--datastream Content-Type: text/plain Content-Length: 16 End of recording
RTSP Server
The Wavestore also supports RTSP (port 554) for video streaming.
If connection to the RTSP port fails, clients should use RTSP tunnelled over HTTP data.
RTSP is implemented as RFC2326. OPTIONS, DESCRIBE, SETUP, PLAY, and TEARDOWN are implemented. SET_PARAMETER is supported only as a keepalive. No options are offered by the options command.
The response to a DESCRIBE command is SDP (RFC2327) format.
- Paths like /rtsp/00001 is permitted as the path component of the rtsp DESCRIBE command. The format is /rtsp/<CHANNEL> where CHANNEL is a 5 digit hexadecimal channel number. Note that the channel number is in hexadecimal, so channel 13 is /rtsp/0000d.
- The paths can be obtained from the /simple/Cameras command.
- If no range (or Range: npt=now-) then the live stream is provided.
- The path may be suffixed with 's' to mean 'slow start', eg, /rtsp/00001s. Normally the stream starts with the most recent i-frame followed by p-frames and that i-frame might be before the RTSP PLAY command. So a brief dropout could restart the stream earlier than a frame sent before the dropout. Some systems don't like this, reporting invalid or decreasing timestamp, so a 'slow start' flag can be added to ensure it starts the stream slowly with the next i-frame after the RTSP PLAY command time rather than the one before. from 6.32.
Playback of secondary live stream
- The top nibble of the 5-digit channel can be 0 or 1 for the first live stream.
- The top nibble of the 5-digit channel can be 2 for a secondary live stream. eg, 20005 is the second live stream on channel 5.
- The top nibble of the 5-digit channel can be 3 for a secondary live stream. eg, 30005 is the third live stream on channel 5.
- Where audio is available on the same track, its track 7, eg, 70005 is audio on channel 5 where video exists as well.
Using RTSP for playback
We can use the Range: keyword to specify a playback range. Specify only the start time using the clock= absolute time format as defined in RFC2326 section 12.29 Range. The format is clock=yyymmddThhmmss.000Z-. Remember to use UTC and not local time.
eg,
Range: clock=20190329T103000.000Z-
The track number should be in the top nibble of the 5-digit channel; normally recorded video is track 1, audio is track 7.
Alternatively, if it's hard to use the Range: parameter (some playback tools do not offer it) we can add starttime= and endtime= to the URL:
/rtsp/00001?starttime=20190329T103000Z&endtime=20190329T103500Z
The timestamps for starttime and endtime are the same format as clock= except that Z is optional; if Z present then time is in UTC, otherwise localtime. Also either T or _ can be used as time separator; eg, starttime=20190329_103000 or starttime=20190329T103000.
starttime= and endtime= url parameters, and the ability to put endtime on clock=, from 6.54
Historical Revisions
- The Simple interface was introduced in V6 with /simple/Cameras introduced in V6.0
- /simple/bounds and /simple/recordings and the improved /simple/camera were introduced in V6.20
- /simple/export was introduced in V6.40
- HTTPS was introduced in V6.40, until that version only HTTP (port 80) could be used.
- The starttime= field added in Wavestore V6.54 as the standard Range: field was hard for some customers to use.
- The HTTP /data multipart streaming was added in V6.56 to stream items which were hard to stream by RTSP.