JVC VN-H137, VN-H157WP, VN-H257, VN-H257VP, VN-H37U User Manual
...
1
IP Camera API GUIDE
VN-H37/137/237/237VP
VN-H57/157WP/257/257VP
This document provides information of protocol and API of JVC new IP cameras,
VN-H series.
Specifications subject to change without notice.
2012.06.29. (V4.00)
© 2012 JVC KENWOOD Corporation
2
Updates
Version
Date Updates
1.00 2012/1/31 New release
1.01a 2012/02/23 Corrections of typographical error
Page 5, section 2.1: change boundary to server_push
Page 6, section 2.2: change boundary to server_push
Page 14, Getting Enhance of Scene File: change 11 internal levels to 14
internal levels.
Page 15, Setting Enhance of Scene File: change 11 internal levels to 14
internal levels.
Page 17, Getting / Setting Shutter Speed of a Scene File:“auto” is added.
Page 22, Setting Frame Rate: 15, 10, and 7.5 is added.
1.01b 2012/03/06 Page 6, section 2.3. Response is added.
Page 7, section 2.4. Restrictions is added.
Page 7, section 2.5. JPEG File Format Sent Out by the camera is added.
Page 10, section 3.3. Response is added.
Page 10, section 3.4. Restrictions is added.
Page 10, section 3.5. H.264 Stream Format Send Out by the camera is added.
Page 81, Default User Name is changed from PSIATest to psia.
Default Password is changed from PSIATest to jvc.
2.00 2012/04/16 Page 6, section 2.2, Setting Frame Rate: 30, 15, 10, and 7.5 is added.
Page 12, section 4, “JVC Protocol :MPEG-4 Streaming” is added.
Page 19, section 8, “Getting Preset Data of Scene File” is added.
Page 21, section 8, “Enhance”: Explanation of parameter is added.
Page 22, section 8, Getting and Setting 3DDNR is added.
Page 25, section 8, Getting and Setting ALC priority is added.
Page 26, section 8, Corrections of typographical error: Easy is removed.
Page 26, section 8, Getting and Setting Easy Day and Night is added.
Page 27, section 8, Getting and Setting CLVI is added.
Page 28, section 9, Setting Compression Format : mpeg4 is added.
Page 29, section 9, Setting Resolution : 320x180 is removed.
Page 29, section 9, Getting and Setting Rate Control Setting : MPEG-4 is
added.
Page 29, section 9, Setting Rate Control: Explanation of parameter is added.
Page 29, section 9, Getting and Setting bitrate : MPEG-4 is added.
Page 30, section 9, Getting and Setting I-Frame Interval : MPEG-4 is added.
Page 31, section 9, Getting and Setting Monitor Out is added.
Page 59, section 16, JVC API for Tampering Detect is added.
Page 69, section 18, Getting and Setting Status of PSIA Protocol is added.
Page 69, section 18, Getting and Setting Status of ONVIF Protocol is addded.
Page 84, section 26, Getting and Setting Port Number of RTSP Server is
added.
Continue on next page
3
Version
Date Updates
2.01 2012/05/08 Page 5, “JVC API for Audio” is added.
Page 5, “Getting Audio from the Camera via HTTP” is added.
Page 5, “Sending Audio to the Camera” is added.
Page 33, section 10, JVC API for Audio is added.
Page 36, section 11, Getting and Setting Alarm Action: “audioplay” and
“pinout” are added.
Page 41, section 11, Getting and Setting Alarm Trigger: “m1”, “b1”, “m2”, “b2”,
“audio_detect1”, “audio_detect2”, “tampering_detect”, “ncbwe” and “ncbws”
are added.
Page 87, section 28, “Getting Audio from the Camera via HTTP” is added.
Page 90, section 29, “Sending Audio to the Camera” is added.
Page 92, section 31, List of ActiveX: “Audio Monitor” and “Audio Sending
Client” are added.
Page 93, section 31, Properties of ActiveX: Explanation of default Folder
Name is added.
Page 94, section 31, Properties of ActiveX: Audio Monitor / Audio Sending
Client is added.
Page 95, section 31, Method of ActiveX Control: Audio Monitor / Audio
Sending Client is added.
Page 96, section 31, How to use ActiveX control by HTML: Audio Monito
r and
Audio Sending Client are added.
Page 97, section 31, HTML Sample: Audio Monitor and Audio Sender are
added.
3.00 2012/05/21 Page 5, 13. JVC API for SD Card Record is added.
Page 5, 31. Getting SD Card data from the Camera via RTSP/RTP is added.
Page 5, 32. Exporting H.264 data from SD Card to the PC is added.
Page 35, section 11, Explanation of SD Card recording is added.
Page 51, section 12, Getting and Setting Parameters of Pre/Post Recording
for FTP : Explanation of Encoder No. is added.
Page 53, 13. JVC API for SD Card Record is added.
Page 96, 31. Getting SD Card data from the Camera via RTSP/RTP is added.
Page 97, 32. Exporting H.264 data from SD Card to the PC
4.00 2012/06/29 Page 30, section 9, Corrections of typographical error
change from “channel is saved” to “channel is availed”
Page 30, section 9, Example of Setting Compression Format is added.
Page 35, section 11, event No.10 is added.
Page 60, section 14, “Moving Specified Position to Center” is added.
4
Preface
This document is for VMS to support JVC new cameras, VN-H37/137/237.
If VMS supports only streaming, i.e. VMS does not have camera setting pages, the chapter
"Streaming Protocol" provides how to get stream from a camera.
If VMS have setting page of the camera, focusing on necessary functionalities is
recommended. Typical necessary functionalities are Image settings and Encode settings.
Supporting all functionalities of camera will not pay. For example, if VMS does not get
multiple streams from a camera, Encode settings can be simple because setting multiple
resolution/encode to camera is not required.
5
Content
1. Streaming Protocol
.................................................................................................................................................... 7
2. JVC Protocol: JPEG Streaming
......................................................................................................................... 7
3. JVC Protocol: H.264 Streaming
.......................................................................................................................11
4. JVC Protocol: MPEG-4 Streaming
.................................................................................................................14
5. RTSP/RTP
......................................................................................................................................................................17
6. API to Search Camera
............................................................................................................................................17
7. Using API that Requires Basic Authentication
.....................................................................................18
8. JVC API for Camera
................................................................................................................................................20
9. JVC API for Encode
.................................................................................................................................................30
10. JVC API for Audio (VN-H57/157WP/257/257VP)
...............................................................................34
11. JVC API for Alarm
................................................................................................................................................35
12. JVC API for Alarm Environment
.................................................................................................................44
13. JVC API for SD Card Record
........................................................................................................................52
14. JVC API for Digital PTZ
....................................................................................................................................55
15. JVC API for Auto Patrol
...................................................................................................................................62
16. JVC API for Privacy Masking
.......................................................................................................................64
17. JVC API for Motion Detect
.............................................................................................................................66
18. JVC API for Tampering Detect
....................................................................................................................67
19. JVC API for Network Basics
.........................................................................................................................69
20. JVC API for Protocol
..........................................................................................................................................75
21. JVC API for Multicast Streaming
...............................................................................................................77
22. JVC API for Access Restrictions
...............................................................................................................80
23. JVC API for Time
..................................................................................................................................................82
24. JVC API for Password
......................................................................................................................................85
25. JVC API for Maintenance
................................................................................................................................86
26. JVC API for LED Setting
..................................................................................................................................87
27. JVC API for Getting Status
............................................................................................................................88
28. JVC API for Others
..............................................................................................................................................90
29. Getting Audio from the Camera via HTTP (VN-H57/157WP/257/257VP)
...........................92
30. Sending Audio to the Camera (VN-H57/157WP/257/257VP)
....................................................94
31. Getting SD Card data from the Camera via RTSP/RTP
...............................................................96
32. Exporting H.264 data from SD Card to the PC
..................................................................................98
33. List of Protocols and Port Numbers Used
........................................................................................100
34. Customizing Built-in Viewer
.......................................................................................................................100
6
35. PSIA
............................................................................................................................................................................108
36. FAQ
.............................................................................................................................................................................108
7
1. Streaming Protocol
- Both JVC protocol and standard RTSP/RTP are supported.
- JPEG, H.264 baseline profile, and H.264 high profile are supported. MPEG-4 will be supported in
future.
- Maximum resolution is 1920x1080.
- VN-H series can send 3 different resolution streams of JPEG simultaneously.
- VN-H series can send 3 different resolution streams of H.264 simultaneously.
- Sending JPEG stream and H.264 stream simultaneously is supported.
2. JVC Protocol: JPEG Streaming
2.1. Basic Procedures
1) The client establishes a TCP connection to port number 80.
2) The client sends out API.
Example
to get JPEG stream encoded by first channel of the camera
GET /api/video?encode=jpeg(1)&framerate=5&server_push=on HTTP/1.1<CRLF>
Host: 192.168.0.2<CRLF><CRLF>
Note <CRLF> denotes the line feed code (
0x0D, 0x0A
).
3) The camera returns HTTP response and JPEG stream.
JPEG files in boundary structure will be sent out continuously after HTTP response. Each Content-Length is the
size of each JPEG data. Using the size, reading the whole data of each JPEG is possible. HTTP Response and
JPEG data sent out by the camera are as follows.
HTTP Response
JPEG (No. 1)
<CRLF>
JPEG (No. 2)
<CRLF>
,,,
--foo<CRLF>
Content-Type: image/jpeg<CRLF>
Content-Length: 31614<CRLF><CRLF>
--foo<CRLF>
Content-Type: image/jpeg<CRLF>
Content-Length: 32756<CRLF><CRLF>
8
4) When the client wants to stop current JPEG transmission, the client disconnects TCP80.
The camera does not accept further API via current TCP that is used for JPEG transmission. To change
parameter, disconnect current TCP to stop the JPEG transmission, connect new TCP, and send API with new
parameter.
2.2. API Format
Structure
Unlike APIs for getting/setting parameters, Accept line is not required. Basic authentication is also not necessary.
Example
GET /api/video?encode=jpeg(1)&framerate=5&server_push=on HTTP/1.1<CRLF>
Host: 192.168.0.2<CRLF><CRLF>
Parameter value is indicated using =. Do not insert space before and after =.
Example framerate=1
Parameters are segmented using &. Do not insert space before and after &.
Example encode=jpeg&framerate=5
There is no need to specify all parameters. Default values will be used for parameters that are not specified.
Parameter Description
encode For specifying compression format with channel number. For example, specify as encode=jpeg(1) to get
JPEG encoded by channel 1. To know compression format of each channel, open Encoder setting page by IE
described in INSTRUCTIONS manual, or issue "encode" API described in later chapter of this document.
framerate For specifying the frame rate. For example, specify as framerate=5 to get at 5 fps. Specify as
framerate=-5 to get at 1/5 fps, or in other words, 1 frame in 5 seconds. Selection range for JPEG is as follows.
30, 15, 10, 7.5, 5, 3, 2, 1, 0, -2, -3, -5, -10, -15, -20, -30, -60
When the parameter is specified as framerate=0, the camera sends 1 frame of JPEG data, and disconnect the
TCP connection.
server_push For specifying streaming structure. For example, specify as server_push=on to get Server Push
GET API space
space
HTTP/1.1
0x0D 0x0A 0x0D 0x0A
0x0D 0x0A
Host:
space
IP Address of Camera
9
structured JPEG. When framerate=0 is specified, Server Push is disabled even if server_push=on is specified.
2.3. Response
When API with server_push=on is successfully received.
The camera will return 200 OK. The x-vnh37_response line indicates actual parameter.
Example of VN-H137
HTTP/1.1 200 OK<CRLF>
Content-Type: multipart/x-mixed-replace;boundary=foo<CRLF>
Date: Tue, 06 Mar 2012 13:32:57 GMT<CRLF>
Server: JVC VN-H137 Network Camera<CRLF>
x-vnh37_response: encode=jpeg&framerate=5.0&framesize=1920x1080&server_push=on&ptz_info=off<CRLF>
<CRLF>
When API without server_push option is successfully received.
The camera will return 200 OK. The x-vnh37_response line indicates actual parameter.
Example of VN-H137
HTTP/1.1 200 OK<CRLF>
Connection: Keep-Alive<CRLF>
Content-Type: image/jpeg<CRLF>
Date: Tue, 06 Mar 2012 14:06:07 GMT<CRLF>
Server: JVC VN-H137 Network Camera<CRLF>
x-vnh37_response: encode=jpeg&framerate=5.0&framesize=1920x1080&server_push=off&ptz_info=off<CRLF>
<CRLF>
2.4. Restrictions
Access restriction
The camera has access restriction feature that enables to deny access from a specific IP address. If JPEG is
requested from the IP address of access restriction, the camera disconnects the TCP connection after API is sent.
Restriction by maximum bitrate of the camera.
The maximum bitrate of the camera is about 20 Mbps.
Number of clients
The maximum number of clients that can get JPEG stream depends on encode settings and requests from client.
10
Refer the instruction manual for detailed infomation.
2.5. JPEG File Format Sent Out by the camera
JPEG file from the camera is JFIF compliant and consist of the following.
FFD8
Start Code
FFE0
Application Segment
FFFE
Comment Segment 1
FFFE
Comment Segment 2 (reserved)
FFC4
DHT Huffman Table
FFDB
DQT Quantization Table
FFDD
DRI Restart Interval
FFC0
SOF Frame Information
FFDA
Data Start Segment
FFD9
End Code
The following information is stored in the comment segment 1. Each item has a fixed length.
Item Size Example Note
Version Information
9 JVC V1.0
Indicates the version of
information stored in the
comment segment.
File Size
18 size = 123456
Indicates JPEG size in bytes.
Width
13 width = 1920
Width of JPEG.
Height
14 height = 1080
Height of JPEG.
Model Name
18 type = VN-H137
Name of model that created the JPEG.
(reserved) 12 reverse = 0 (reserved)
Time Stamp
70
timestamp =
2012030623341253
8UTC
Indicates the time when the JPEG is created. This is
made up of the year/month/day, hour/minute/second,
millisecond and timezone code.
(reserved) 13 alarm = 00000000 (reserved)
Camera ID
50 camera = input01
Stores camera information set at VN-X35/235.
Motion Detect Setting
11 motion = 1
Specified as 1 when the motion detect is ON.
Motion Detect Result
7 md = 1
Specified as 1 if motion i
s detected at the time when
JPEG is created.
Tampering Detect
Result
14 tampering = 0
Specified as 1 if tampering is detected at the time when
JPEG is created.
Pan position 16 digipan = 123 Indicates pan position in pixels from 0 to 1278.
Tilt position 17 digitilt = 123 Indicates tilt position in pixels from 0 to 958.
Zoom position 17 digizoom = 1.23 Indicates zoom value from 0.25 to 8.00.
Preset Posision
Number
15 position = 19 Indicates preset position number after movin
g to
preset position
. In other cases, position = NA.
Item names and values, excluding the version information that does not include =, are stored in the following
format.
name
=
space
space
value
(stuffed wi
th 0x00)
fixed length for each item
11
Example: When width=640, the 13-byte area will be written as follows.
3. JVC Protocol: H.264 Streaming
3.1. Basic Procedures
1) The client establishes a TCP connection to port number 80.
2) The client sends out API.
Example
to get H.264 high profile stream encoded by first channel of the camera
GET /api/video?encode=h264(1) HTTP/1.1<CRLF>
Host: 192.168.0.2<CRLF><CRLF>
Note <CRLF> denotes the line feed code (
0x0D, 0x0A
).
3) The camera returns HTTP response and H.264 stream.
HTTP Response and H.264 stream sent out by the camera are as follows.
4) When the client wants to stop current H.264 transmission, the client disconnects TCP80.
The camera does not accept further API via current TCP that is used for H.264 transmission. To change
parameter, disconnect current TCP to stop the H.264 transmission, connect new TCP, and send API with new
parameter.
3.2. API Format
Structure
HTTP Response
I Picture of H.264 (First Frame)
,,,
P Picture of H.264 (Second Frame)
GET API space
space
HTTP/1.1
0x0D 0x0A
w i d t h = 6 4 0 0x00
0x00
12
Unlike APIs for getting/setting parameters, Accept line is not required. Basic authentication is also not necessary.
Example
GET /api/video?encode=h264(1) HTTP/1.1<CRLF>
Host: 192.168.0.2<CRLF><CRLF>
Parameter value is indicated using =. Do not insert space before and after =.
Example
encode=h264(1)
Parameter Description
encode For specifying compression format. For example, specify as encode=
h264
(1) to get H.264 encoded by
channel 1. To know compression format of each channel, open Encoder setting page by IE described in
INSTRUCTIONS manual, or issue "encode" API described in later chapter of this document.
3.3. Response
When API is successfully received.
The camera will return 200 OK. The x-vnh37_response line indicates actual parameter.
Example of VN-H137
HTTP/1.1 200 OK<CRLF>
Connection: Keep-Alive<CRLF>
Content-Type: video/mp4v-es<CRLF>
Date: Tue, 06 Mar 2012 15:10:55 GMT<CRLF>
Server: JVC VN-H137 Network Camera<CRLF>
x-vnh37_response: encode=h264&framesize=1920x1080<CRLF>
3.4. Restrictions
Access restriction
The camera has access restriction feature that enables to deny access from a specific IP address. If H.264 is
requested from the IP address of access restrictions, the camera disconnects the TCP connection after API is
send.
3.5. H.264 Stream Format Send Out by the camera
0x0D 0x0A 0x0D 0x0A
Host:
space
IP Address of Camera
13
H.264 stream form the camera is sequence of I Picture and P Picture. Ratio of I Picture and P Picture depends on
I-Frame interval setting. Encode page of Web has the setting.
Example of H.264 Stream
HTTP response
Sequence Parameter Set
Picture Parameter Set
User data
I Picture
User data
P Picture
~
User data
I Picture
There are Sequence Parameter Set, Picture Parameter Set, and User data before each I Picture and there is User
data before each P Picture.
The following information is stored in the User data. Each item has a fixed length.
Item Size Example Note
Start code 4 0x00000001 Start code of User data in H.264 stream.
NAL unit type 1 0x66 NAL unit type of User data in H.264 stream.
Payload type 1 0x05 Payload type of User data in H.264 stream.
User data size 1 0xf0 Size of User data in H.264 stream.
Reserved 16 0x030303030303030
30303030303030303
－
Model Name
18 type = VN-H137
Product Name
Time Stamp
70
timestamp =
2012030623341253
8UTC
This is made up of the year/month/day,
hour/minute/second, millisecond and timezone code.
Camera ID
50 camera = input01
Camera ID that user can define
Motion Detect Result
7 md = 1
Specified as 1 if motion is detected at the time when
data is created.
Tampering Detect
Result
14 tampering = 0
Specified as 1 if tampering is detected at the time when
data is created.
14
Pan position 16 digipan = 123 Indicates pan position in pixels from 0 to 1278.
Tilt position 17 digitilt = 123 Indicates tilt position in pixels from 0 to 958.
Zoom position 17 digizoom = 1.23 Indicates zoom value from 1.00 to 8.00.
Preset Posision
Number
15 position = 19 Indi
cates preset position number after moving to
preset position
. In other cases, position = NA.
4. JVC Protocol: MPEG-4 Streaming
4.1. Basic Procedures
1) The client establishes a TCP connection to port number 80.
2) The client sends out API.
Example
GET /api/video?encode=mpeg4 HTTP/1.1<CRLF>
Host: 192.168.0.2<CRLF><CRLF>
Note <CRLF> denotes the line feed code (
0x0D, 0x0A
).
3) The camera returns HTTP response and MPEG-4 stream.
HTTP Response and MPEG-4 stream sent out by the camera are as follows.
4) When the client wants to stop current MPEG-4 transmission, the client disconnects TCP80.
The camera does not accept further API via current TCP that is used for H.264 transmission. To change
parameter, disconnect current TCP to stop the MPEG-4 transmission, connect new TCP, and send API with new
parameter.
4.2. API Format
Structure
HTTP Response
VOP of MPEG_4 (First Frame)
,,,
VOP of MPEG-4 (Second Frame)
GET API space
space
HTTP/1.1
0x0D 0x0A 0x0D 0x0A
0x0D 0x0A
Host:
space
IP Address of Camera
15
Unlike APIs for getting/setting parameters, Accept line is not required. Basic authentication is also not necessary.
Example
GET /api/video?encode=mpeg4 HTTP/1.1<CRLF>
Host: 192.168.0.2<CRLF><CRLF>
Parameter value is indicated using =. Do not insert space before and after =.
Example
encode=h264
Parameter Description
encode For specifying compression format.
4.3. Response
When API is successfully received.
The camera will return 200 OK. The x-vnh37_response line indicates actual parameter.
Example of VN-H137
HTTP/1.1 200 OK<CRLF>
Connection: Keep-Alive<CRLF>
Content-Type: video/mp4v-es<CRLF>
Date: Tue, 06 Mar 2012 15:10:55 GMT<CRLF>
Server: JVC VN-H137 Network Camera<CRLF>
x-vnh37_response: encode=mpeg4&framesize=640x480<CRLF>
4.4. Restrictions
Access restriction
The camera has access restriction feature that enables to deny access from a specific IP address. If MPEG-4 is
requested from the IP address of access restrictions, the camera disconnects the TCP connection after API is
send.
4.5. MPEG-4 Stream Format Send Out by the camera
MPEG-4 stream form the camera is MPEG-4 Part2 (ISO/IEC 14496-2) compliant, level3 of simple profile. Its is a
sequence of I-VOPs, or I-VOPs and P-VOPs.
I-VOP: Inter frame compressed data
P-VOP: Inter frame compressed data with previous frame
16
Ratio of I-VOP and P-VOP depends on I-Frame interval setting. Encode page of Web has the setting.
First VOP can be I-VOP or P-VOP. If client want to decode from I-VOP, please skip P-VOP and wait first I-VOP.
Example of MPEG-4 Stream
HTTP response
P-VOP
P-VOP
P-VOP
VOL
I-VOP
P-VOP
~
There are VOL, Userdata1, GOV and Userdata2 before each I-VOP.
Data structure before I-VOP
Item Note
VOL VOL of MPEG-4 Video
Userdata1 Reserved
GOV GOV of MPEG-4 Video
Userdata2 Userdata
Data structure of Userdata2
Item Size Example Note
Start code 4 0x000001B2 Start code of User data in MPEG-4 stream.
Model Name
18 type = VN-H137
Product Name
Time Stamp
70
timestamp =
2012030623341253
8UTC
This is made up of the year/month/day,
hour/minute/second, millisecond and timezone code.
Camera ID
50 camera = input01
Camera ID that user can define
Motion Detect Result
7 md = 1
Specified as 1 if mo
tion is detected at the time when
data is created.
Tampering Detect
Result
14 tampering = 0
Specified as 1 if tampering is detected at the time when
data is created.
Pan position 16 digipan = 123 Indicates pan position in pixels from 0 to 1278.
Tilt position 17 digitilt = 123 Indicates tilt position in pixels from 0 to 958.
Zoom position 17 digizoom = 1.23 Indicates zoom value from 1.00 to 8.00.
Preset Posision
Number
15 position = 19 Indicates preset position number after
moving to
preset position
. In other cases, position = NA.
17
5. RTSP/RTP
5.1. URI
RTSP of the camera is RFC2326 compliant.
Three encoders can be enabled in the camera at its maximum. Each encoder's URI for RTSP is:
Encoder Channel URI of RTSP
1 rtsp://ipaddress/PSIA/Streaming/channels/0
2 rtsp://ipaddress/PSIA/Streaming/channels/1
3 rtsp://ipaddress/PSIA/Streaming/channels/2
To know compression format of each channel, open Encoder setting page by IE described in INSTRUCTIONS
manual, or issue "encode" API described in later chapter of this document.
5.2. JPEG
- RFC
JPEG/RTP of the camera is RFC2435 compliant.
- Frame Rate of JPEG
In case of JPEG/RTP, the client can request frame rate to the camera.
Example to get 5fps JPEG: (This is valid when encode channel 1 is set to JPEG.)
rtsp://ipaddress/PSIA/Streaming/channels/0?maxFrameRate=5
If maxFrameRate is not specified, the camera tries to send JPEG at its maximum frame rate.
5.3. H.264
H.264/RTP of the camera is RFC3984 compliant.
6. API to Search Camera
The camera in LAN can be searched by broadcast/multicast packet that has search API.
Search Camera in LAN
Protocol Send broadcast/multicast packet with following text in UDP payload to destination port number 80.
Source port number can be any value. Multicast address is 239.0.255.255.
system.id<CRLF>
Response The camera that received this packet sends unicast udp packet to the source port number of the
search packet. UDP payload of response packet has model name, IP address, and subnet mask. The camera
18
waits 0-0.7 second before sending response to avoid too many responses are sent in short period from many
cameras.
Response Example system.id=VN-H37(192.168.0.2/24)&200 OK<CRLF>
7. Using API that Requires Basic Authentication
Basic authentication is required for JVC API explained in Section 7 or later. This section provides general
explanation of those APIs.
7.1. Procedure
1) The client establishes a TCP connection to port number 80.
2) The client sends API.
API has following structure.
The following is an example of API for Getting subnet mask of the camera.
Example
GET /api/param?network.interface.subnetmask HTTP/1.1<CRLF>
Accept: text/plain<CRLF>
Host: 192.168.0.2<CRLF>
Authorization: Basic YWRtaW46anZj<CRLF><CRLF>
Specify the response format by Accept line. Plain text response is returned when this is specified as text/plain.
HTML response is returned when text/html is specified. HTML response is returned when Accept is not specified.
These APIs for getting/setting parameters are protected by basic authentication. Authorization line needs to
include encoded username and password. There are 3 types of usernames, namely admin, operator and user.
Available APIs are different for each username. Join the user name and the password using a colon, Base64
encode this character string and enter this in the Authorization line.
For example, when
User name admin
Password jvc
then the character string joining the user name and the password with a colon is:
Accept:
text/plain (or text/html)
space
space
HTTP/1.1
0x0D 0x0A
Host:
space
IP Address of Camera
0x0D 0x0A
Authorization: Basic
space
Encoded
User Name and Password
0x0D 0x0A 0x0D 0x0A
GET space
API Characters
0x0D 0x0A
19
admin:jvc
Base64 encoding of this string yields YWRtaW46anZj. Enter this in the Authorization line. Default password for
each username is jvc.
3) The camera returns a response to the client. In the following example, current subnet mask is 255.0.0.0. In
addition, 255.0.0.0 is followed by & and 200 OK, indicating that getting parameter is successful.
Example
HTTP/1.1 200 OK<CRLF>
Connection: close<CRLF>
Content-Length: 80<CRLF>
Content-type: text/plain<CRLF>
Date: Fri, 13 MAY 2011 07:33:12 GMT<CRLF>
Server: JVC VN-H37 API Server<CRLF>
network.interface.subnetmask=255.0.0.0&200 OK<CRLF>
4) The client disconnects TCP80 to end the use of API.
Note: APIs for getting/setting parameters are not restricted by the access restriction function.
7.2. Getting Parameter
Specify API in GET line according to the format below when getting a parameter from the camera.
/api/param?ParamA.ParamB.ParamC
It is possible to get multiple parameters at a time. Connect parameters with &. Do not insert space before and after
&.
/api/param?ParamA.ParamB.ParamC&ParamA.ParamD.ParamE
The upper limit of this character string is 1024 bytes. The maximum number of parameters that can be acquired at
a time is 15. Status settings, i.e.
network.interface.status, network.dns.status, network.ntp.status, etc.,
can not be
acquired at a time.
When acquisition is successfully completed, values will be shown in the body of HTTP response, followed by
"&200 OK" message.
Example:
ParamA.ParamB.ParamC=Data&200 OK
20
When an error occurs, an error code will be returned instead of indicating a value in the body of HTTP response.
Example:
ParamA.ParamB.ParamC&401 Unauthorized
When multiple APIs for getting are performed at one time, a response will be returned for each setting.
ParamA.ParamB.ParamC&200 OK<CRLF>
ParamA.ParamB.ParamD&200 OK<CRLF>
7.3. Setting Parameter
Specify API in GET line according to the format below when setting a parameter for the camera.
/api/param?ParamA.ParamB.ParamC=Data
Parameter values are indicated using =. Do not insert space before and after =.
It is possible to perform multiple settings at a time. Connect parameters with &. Do not insert space before and
after &.
/api/param?ParamA.ParamB.ParamC=Data&ParamA.ParamB.ParamD=Data
The upper limit of this character string is 1024 bytes. The maximum number of parameters that can be set at a
time is 15. Status settings, i.e.
network.interface.status, network.dns.status, network.ntp.status, etc., can
not be
acquired at a time.
Response will be in the following format.
ParamA.ParamB.ParamC&200 OK
An error code will be returned when setting is not properly performed. Example:
ParamA.ParamB.ParamC&401 Unauthorized
When multiple settings are performed at one time, a response will be returned for each setting.
ParamA.ParamB.ParamC&200 OK<CRLF>
ParamA.ParamB.ParamD&200 OK<CRLF>
8. JVC API for Camera
These APIs are related to camera settings. Same functions are shown on the Camera page of the WEB setting
page. Refer to the instruction manual for details on the Camera page.
Getting Camera ID
21
Format /api/param?camera.id
Example of response camera.id=VN-H37&200 OK
Response example when setting field is left blank camera.id=&200 OK
Interpretation Acquire Camera ID comment. This comment is stored in comment segment of JPEG. The
Camera ID is used as sender's display name of alarm mail. If you want to
set sender's mail address, s
ee
"
Setting Sender Mail Address".
Example of response camera.id=Camera01&200 OK
Sender Camera01<somename@somecompany.com>
Allowed users admin, operator, user
Setting Camera ID
Format /api/param?camera.id=data
Example /api/param?camera.id=Camera01
Example when setting as blank /api/param?camera.id=%00
Example of response camera.id&202 Accepted(camera.status=save)
Interpretation Change the camera ID stored in comment segment of JPEG. Maximum size is 40 bytes.
To use following characters, specify by hexadecimal number after %.
space & / < > # % " { } | \ ^ [ ] `
To set as blank, specify as %00(0x25, 0x30, 0x30).
To use space, specify as %20(0x25, 0x32, 0x30). If you want to set "Comment In JPEG" for example, specify
as follows. /api/param?camera.id=Comment%20In%20JPEG
The Camera ID is used as sender's display name of alarm mail. If you want to
set sender's mail address, s
ee
"
Setting Sender Mail Address".
Example of setting
/api/param?camera.id=Camera01
Sender Camera01<somename@somecompany.com>
The change is saved by the API, camera.status=save. If the change is not saved, the setting is restored by reboot.
Allowed users admin, operator
Getting Current Scene File Number
Format /api/param?camera.scene.status
Example of response camera.scene.status=0&200 OK
Interpretation Acquire current scene file number. A number from 0 to 7 is returned.
A scene file is a set of preset parameters below.
auto_exposure.reference, color, monitortype, pedestal, gamma, enhance, white_balance, brightness,
white_balance, white_balance.r, white_balance.b, senseup_limit, brightness.highgain, true_daynight, blc,
auto_exposure.priority, shutter
22
Allowed users admin, operator, user
Getting Preset Data of Scene File
Format /api/param?camera.scene(number).status
Example of getting scene file 0 /api/param?camera.scene(0).status
Example of response
camera.scene(0).status=General-55--0.45-30-auto-off-0-51-off-low-53-mid-autoM-2-combo-color-8-8-auto
W-107-65-off-off-0-normal&200 OK
Interpretation Acquire preset data of specified scene file. The preset data is joined with hyphen as follows.
scenename-color-monitortype*1-gamma-shutter-brightness.highgain*2-auto_focus-iris-pedestal-autoblack*1-enha
nce_band*1-enhance-3ddnr-brightness-senseup_limit-auto_exposure.priority-true_daynight*2-avpk_color-avpk_b
w*3-white_balance-white_balance_r-white_balance_b-blc-clvi-autoexposure.reference-atw_convergence
*1
parameter that is marked with
*1
: The parameter is not used or data value is invalid.
parameter that is marked with
*2
: The parameter is used for VN-H37and VN-H237VP.
parameter that is marked with
*3
: The parameter is used for VN-H137and VN-H237.
Allowed users admin, operator, user
Loading/Saving/Initializing Scene File
Format /api/param?camera.scene(number).status=data
Example of loading scene file 0 /api/param?camera.scene(0).status=goto
Example of saving scene file 0 /api/param?camera.scene(0).status=save
Example of initializing scene file 0 /api/param?camera.scene(0).status=initialize
Example of response camera.scene(0).status&200 OK
Interpretation Load/save/initialize scene file setting. Specify from scene(0) to scene(7). Loading scene file
changes current camera settings. Saving scene file saves setting s of specified scene file. Initializing scene file
changes settings of specified scene file to default values.
Allowed users admin, operator
Getting Current Scene File Name
Format /api/param?camera.scene(number).name
Example of response camera.scene(0).name=general&200 OK
Interpretation Acquire current scene file name. Range of scene file number is between 0 to 7.
Scene file names are General, Indoor, Outdoor, CLVI, Traffic, DataSaving, Day, and Night.
Scene file name is read only.
Allowed users admin, operator, user
23
Getting Auto Exposure Reference of a Scene File
Format /api/param?camera.scene(number).auto_exposure.reference
Example of response camera.scene(0).auto_exposure.reference=0&200 OK
Interpretation Acquire auto exposure reference. A number from -5 to 5 is returned. When the number is bigger,
image becomes brighter.
Allowed users admin, operator, user
Setting Auto Exposure Reference of a Scene File
Format /api/param?camera.scene(number).auto_exposure.reference=data
Example /api/param?camera.scene(0).auto_exposure.reference=0
Example of response camera.scene(0).auto_exposure.reference&202
Accepted(camera.scene.status=save)
Interpretation Change auto exposure reference. Specify a number from -5 to 5, or "+", "-". When the number is
bigger, image becomes brighter. The change of scene file 0 is saved by the API, camera.scene(0).status=save. If
the change is not saved, the setting is restored by reboot.
Allowed users admin, operator
Getting Color Level of a Scene File
Format /api/param?camera.scene(number).image.color
Example of response camera.scene(0).image.color=50&200 OK
Interpretation Acquire color level value. Range of color level is between 0 to 100. The value is mapped to 11
internal levels. The larger the value, the stronger will be the color.
Allowed users admin, operator, user
Setting Color Level of a Scene File
Format /api/param?camera.scene(number).image.color=data
Example of setting a value /api/param?camera.scene(0).image.color=50
Example of 1 step change /api/param?camera.scene(0).image.color=+
Example of response
camera.scene(0).image.color&202 Accepted(camera.scene.status=save)
Interpretation Change color level value. Specify 0 to 100, "+" or "-". The value is mapped to 11 internal levels.
The larger the value, the stronger will be the color. It becomes stronger 1 step by specifying "+", softer 1 step by
specifying "-". The change of scene file 0 is saved by the API, camera.scene(0).status=save. If the change is not
saved, the setting is restored by reboot.
Allowed users admin, operator
24
Getting Enhance of a Scene File
Format /api/param?camera.scene(number).image.enhance
Example of response camera.scene(0).image.enhance=50&200 OK
Interpretation Acquire enhance setting. The enhance is equal to sharpness of image. Range of enhance is
between 0 to 100, and it is mapped to 14 internal levels. The larger the value, the sharper will be the image.
Allowed users admin, operator, user
Setting Enhance of a Scene File
Format /api/param?camera.scene(number).image.enhance=data
Example of setting a value /api/param?camera.scene(0).image.enhance=50
Example of 1 step change /api/param?camera.scene(0).image.enhance=+
Example of response camera.scene(0).image.enhance&202 Accepted(camera.scene.status=save)
Interpretation Change enhance setting. The enhance is equal to sharpness of image. Specify 0 to 100, "+" or "-".
The value is mapped to 14 internal levels. It becomes sharper 1 step by specifying "+", softer 1 step by specifying
"-". The change of scene file 0 is saved by the API, camera.scene(0).status=save. If the change is not saved, the
setting is restored by reboot.
Allowed users admin, operator
Getting 3DDNR of a Scene File
Format /api/param?camera.scene(number).image.3ddnr
Example of response camera.scene(0).image.3ddnr=mid&200 OK
Interpretation Acquire 3DDNR (3 Dimension Digital Noise Reduction) setting. “off”, “low”, “mid” of “high”is
returned.
Allowed users admin, operator, user
Setting 3DDNR of a Scene File
Format /api/param?camera.scene(number).image.3ddnr=data
Example of setting a value /api/param?camera.scene(0).image.3ddnr=mid
Example of response camera.scene(0).image.3ddnr&202 Accepted(camera.scene(0).status=save)
Interpretation Change 3DDNR setting. Specify “off”, “low”, “mid” of “high”. The change of scene file 0 is saved by
the API, camera.scene(0).status=save. If the change is not saved, the setting is restored by reboot.
Allowed users admin, operator
Getting White Balance of a Scene File
Format /api/param?camera.scene(number).image.white_balance
Example of response camera.scene(0).image.white_balance=auto&200 OK
25
Interpretation Acquire white balance setting. "autoW", "autoN", or "manual" is returned.
Allowed users admin, operator, user
Setting White Balance of a Scene File
Format /api/param?camera.scene(number).image.white_balance=data
Example /api/param?camera.scene(0).image.white_balance=auto
Example of response camera.scene(0).image.white_balance&202 Accepted(camera.scene.status=save)
Interpretation Change white balance setting. Specify "autoW", "autoN", or "manual". If "op_auto" is specified,
one push auto white balance control is done, and setting becomes "manual". The change of scene file 0 is saved
by the API, camera.scene(0).status=save. If the change is not saved, the setting is restored by reboot.
Allowed users admin, operator
Getting R-Gain of White Balance of a Scene File
Format /api/param?camera.scene(number).image.white_balance.r
Example of response camera.scene(0).image.white_balance.r=s85&200 OK
Interpretation Acquire R-gain of white balance setting. s0 to s255 is returned. The s before number means
"step". Default value is s85.
Allowed users admin, operator, user
Setting R-Gain of White Balance of a Scene File
Format /api/param?camera.scene(number).image.white_balance.r=data
Example /api/param?camera.scene(0).image.white_balance.r=s100
Example of response
camera.scene(0).image.white_balance.r&202 Accepted(camera.status=save)
Interpretation Change R-gain white balance setting. Specify s0 to s255. The s before number means "step".
Default value is s85. The change of scene file 0 is saved by the API, camera.scene(0).status=save. If the change
is not saved, the setting is restored by reboot.
Allowed users admin, operator
Getting B-Gain of White Balance of a Scene File
Format /api/param?camera.scene(number).image.white_balance.b
Example of response camera.scene(0).image.white_balance.b=s219&200 OK
Interpretation Acquire B-gain of white balance setting. s0 to s255is returned. The s before number means "step".
Default value is s219.
Allowed users admin, operator, user
26
Setting B-Gain of White Balance of a Scene File
Format /api/param?camera.scene(number).image.white_balance.b=data
Example /api/param?camera.scene(0).image.white_balance.b=s100
Example of response
camera.scene(0).image.white_balance.b&202 Accepted(camera.status=save)
Interpretation Change B-gain white balance setting. Specify s0 to s255. The s before number means "step".
Default value is s219. The change of scene file 0 is saved by the API, camera.scene(0).status=save. If the change
is not saved, the setting is restored by reboot.
Allowed users admin, operator
Getting AGC of a Scene File
Format /api/param?camera.scene(number).image.brightness
Example of response camera.scene(0).image.brightnesss=autoL&200 OK
Interpretation Acquire AGC setting. "manual", "autoM" or "autoH" is returned.
Allowed users admin, operator, user
Setting AGC of a Scene File
Format /api/param?camera.scene(number).image.brightness=data
Example /api/param?camera.scene(0).image.brightness=auto
Example of response camera.scene(0).image.brightness&202 Accepted(camera.scene.status=save)
Interpretation Change AGC setting. Specify "manual", "autoM" or "autoH". The change of scene file 0 is saved
by the API, camera.scene(0).status=save. If the change is not saved, the setting is restored by reboot.
The AGC setting is limited by Day and Night setting. Change Day and Night first, then change AGC setting.
Allowed users admin, operator
Getting Limit of Sense Up of a Scene File
Format /api/param?camera.scene(number).image.senseup_limit
Example of response camera.scene(0).image.senseup_limit=0&200 OK
Interpretation Acquire limit of sense up. 0, 2, 4, 8, 16, 32 or 60 is returned. 0 means sense up is disabled. Other
numbers mean frame number of sense up.
Allowed users admin, operator, user
Setting Limit of Sense Up of a Scene File
Format /api/param?camera.scene(number).image.senseup_limit=data
Example /api/param?camera.scene(0).image.senseup_limit=4
Example of response camera.scene(0).image.senseup_limit&202 Accepted(camera.status=save)
27
Interpretation Change limit of sense up. Specify 0, 2, 4, 8, 16, 32, 60, "+" or "-". It becomes bigger 1 step by
specifying "+", smaller 1 step by specifying "-". The change of scene file 0 is saved by the API,
camera.scene(0).status=save. If the change is not saved, the setting is restored by reboot.
Allowed users admin, operator
Getting ALC priority of Scene File
Format /api/param?camera.scene(number).auto_exposure.priority
Example of response camera.scene(0).auto_exposure.priority=combo&200 OK
Interpretation Acquire ALC priority. ALC priority decides what is used first for auto exposure. “combo”, “motion”
or “quality”is returned.
Allowed users admin, operator, user
Setting ALC priority of Scene File
Format /api/param?camera.scene(number).auto_exposure.priority=data
Example /api/param?camera.scene(0).auto_exposure.priority=combo
Example of response camera.scene(0).auto_exposure.priority&202
Accepted(camera.scene(0).status=save)
Interpretation Change ALC priority. ALC priority decides what is used first for auto exposure. “combo”, “motion” or
“quality”is returned. In case of “combo”, selects the best combination automatically. In case of “motion”, assigns
priority to AGC. In case of “quality”, assigns priority to the Sense Up function.
Allowed users admin, operator, user
Getting Shutter Speed of a Scene File
Format /api/param?camera.scene(number).shutter
Example of response camera.scene(0).shutter=60&200 OK
Interpretation Acquire shutter speed setting. “auto”, "auto100", "auto1000", 30, 50, 60, 100, 250, 500, 1000,
2000, 4000, 10000 or "flickerless" is returned. For example, 60 means shutter speed 1/60. In case of “auto”, the
shutter speed is adjusted from 1/30 to 1/10000. In case of "auto100", the shutter speed is adjusted from 1/30 to
1/100. In case of "auto1000", the shutter speed is adjusted from 1/30 to 1/1000. In case of "flickerless", the shutter
speed that avoids flicker is selected automatically.
Allowed users admin, operator, user
Setting Shutter Speed of a Scene File
Format /api/param?camera.scene(number).shutter=data
Example of setting a value /api/param?camera.scene(0).shutter=60
Example of 1 step change /api/param?camera.scene(0).shutter=+
28
Example of response camera.scene(0).shutter&202 Accepted(camera.scene.status=save)
Interpretation Change shutter speed setting. Specify "auto100", "auto1000", 30, 50, 60, 100, 250, 500, 1000,
2000, 4000, 10000 or "flickerless", "+" or "-". To set 1/60 for example, specify 60. It becomes shorter 1 step by
specifying "+", longer 1 step by specifying "-". The change of scene file 0 is saved by the API,
camera.scene(0).status=save. If the change is not saved, the setting is restored by reboot.
Allowed users admin, operator
Getting Day and Night Setting of a Scene File (for VN-H37 and VN-H237VP)
Format /api/param?camera.scene(number).image.true_daynight
Example of response camera.scene(0).image.true_daynight=off&200 OK
Interpretation Acquire Day and Night setting. "color", "bw", "autoL", "autoM", or "autoH" is returned.
Allowed users admin, operator, user
Setting Day and Night Setting of a Scene File (for VN-H37 and VN-H237VP)
Format /api/param?camera.scene(number).image.true_daynight=data
Example /api/param?camera.scene(0).image.true_daynight=on
Example of response
camera.scene(0).image.true_daynight&202 Accepted(camera.scene.status=save)
Interpretation Change Day and Night setting. Specify "color", "bw", "autoL", "autoM", or "autoH". The change of
scene file 0 is saved by the API, camera.scene(0).status=save. If the change is not saved, the setting is restored
by reboot.
The AGC setting is limited by Day and Night setting. Change Day and Night first, then change AGC setting.
Allowed users admin, operator
Getting Easy Day and Night Setting of a Scene File (for VN-H137 and VN-H237)
Format /api/param?camera.scene(number).image.brightness.highgain
Example of response camera.scene(0).image.brightness.highgain=color&200 OK
Interpretation Acquire Easy Day and Night setting. "color", "bw" or "auto" is returned.
Allowed users admin, operator, user
Setting Easy Day and Night Setting of a Scene File (for VN-H137 and VN-H237)
Format /api/param?camera.scene(number).image.brightness.highgain=data
Example /api/param?camera.scene(0).image.brightness.highgain=color
Example of response
camera.scene(0).image.brightness.highgain&202 Accepted(camera.scene.status=save)
Interpretation Change Day and Night setting. Specify "color", "bw" or "auto". The change of scene file 0 is saved
29
by the API, camera.scene(0).status=save. If the change is not saved, the setting is restored by reboot.
The AGC setting is limited by Day and Night setting. Change Day and Night first, then change AGC setting.
Allowed users admin, operator
Getting Back Light Compensation of a Scene File
Format /api/param?camera.scene(number).image.blc
Example of response camera.scene(0).image.blc=off&200 OK
Interpretation Acquire Back Light Compensation setting. "off", "a", "b", "c" or "d" is returned. Refer the instruction
manual for detailed information of "a", "b", "c" and "d".
Allowed users admin, operator, user
Setting Back Light Compensation of a Scene File
Format /api/param?camera.scene(number).image.blc=data
Format of setting ON /api/param?camera.scene(0).image.blc=a
Example of response camera.scene(0).image.blc&202 Accepted(camera.scene.status=save)
Interpretation Change Back Light Compensation setting. Specify "off", "a", "b", "c" or "d". Refer the instruction
manual for detailed information of "a", "b", "c" and "d". The change of scene file 0 is saved by the API,
camera.scene(0).status=save. If the change is not saved, the setting is restored by reboot.
Allowed users admin, operator
Getting CLVI of a Scene File
Format /api/param?camera.scene(number).image.clvi
Example of response camera.scene(0).image.clvi=off&200 OK
Interpretation Acquire CLVI (Clear Logic Video Intelligence) setting. "on" or "off" is returned.
Allowed users admin, operator, user
Setting CLVI of a Scene File
Format /api/param?camera.scene(number).image.clvi=data
Format of setting ON /api/param?camera.scene(0).image.clvi=on
Example of response camera.scene(0).image.clvi&202 Accepted(camera.scene.status=save)
Interpretation Change CLVI (Clear Logic Video Intelligence) setting. Specify "on" or "off". The change of scene
file 0 is saved by the API, camera.scene(0).status=save. If the change is not saved, the setting is restored by
reboot.
Allowed users admin, operator
30
9. JVC API for Encode
These APIs are related to camera settings. Same functions are shown on the Encode page of the WEB setting
page. Refer to the instruction manual for details on the Encode page.
Though multiple encode is available, there are limitations to set multiple encode channels. If VMS does not get
multiple streams from a camera, setting only first channel is recommended that can simplify such limitations.
Refer the Encode page of the camera to see those limitations.
Getting Compression Format
Format /api/param?encode(number).type
Example of response encode(1).type=jpeg&200 OK
Interpretation Acquire compression format of the encode channel. Encode channel is from encode(1) to
encode(3).
Allowed users admin, operator, user
Setting Compression Format
Format /api/param?encode(number).type=data
Example /api/param?encode(1).type=h264high
Example of response encode(1).type&202 Accepted(encode.status=save)
Interpretation Change compression format of the encode channel. Set "jpeg", "h264high", "h264baseline",
“mpeg4”or "off". The change of the first encode channel is availed by the API, encode(1).status=save.
Example When Changing Compression Format from H.264 to JPEG,
it is necessary that rate control setting is specified to “afs” or “vfs”.
/api/param?encode(1).type=jpeg&encode(1).cbr_mode=afs
/api/param?encode(1).status=save
Example When Changing Compression Format from JPEG to H.264,
it is necessary that rate control setting is specified to “cbr” or “vbr”.
/api/param?encode(1).type=h264high&encode(1).cbr_mode=cbr
/api/param?encode(1).status=save
Caution: In case of multiple resolution, 3 channels are available at the maximum. In case of multiple
encoding, 2 channels are available at the maximum, i.e. 3rd channel is not available.
Allowed users admin, operator
Getting Resolution (Frame Size)
Format /api/param?encode(number).framesize
Example of response encode(1).framesize=1920x1080&200 OK
Loading...