-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy path1-REST-API-Calls.html
More file actions
288 lines (221 loc) · 13.2 KB
/
1-REST-API-Calls.html
File metadata and controls
288 lines (221 loc) · 13.2 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
<!-- Blackmagic REST API Tutorial -->
<!-- Episode 1: Rest API Calls -->
<!-- (c) 2024 Dylan Speiser -->
<!-- Licensed under GNU GPL v3 -->
<!DOCTYPE html>
<html>
<head>
<!-- Page Title and Links -->
<title>1: Rest API Calls - Blackmagic REST API Tutorials</title>
<!-- Link Stylesheets -->
<link rel="stylesheet" href="resources/prism.css">
<link rel="stylesheet" href="resources/stylesheet.css">
<!-- Page metadata-->
<meta charset="UTF-8">
<meta name="description" content="Tutorial series for Blackmagic Camera Control REST API">
<meta name="author" content="Dylan Speiser">
<meta name="viewport" content="width=device-width, initial-scale=1">
<!-- Favicons -->
<link rel="apple-touch-icon" sizes="180x180" href="resources/favicon/apple-touch-icon.png">
<link rel="icon" type="image/png" sizes="32x32" href="resources/favicon/favicon-32x32.png">
<link rel="icon" type="image/png" sizes="16x16" href="resources/favicon/favicon-16x16.png">
</head>
<body class="noto-sans-display">
<!-- Load Scripts -->
<script type="module" src="https://md-block.verou.me/md-block.js"></script>
<script src="resources/prism.js"></script>
<!-- Header Block, same for every page -->
<header>
<h1><a href="index.html">Blackmagic REST API Tutorials</a></h1>
<a href="https://github.com/DylanSpeiser/BM-API-Tutorial">GitHub</a>
</header>
<!-- Next/Previous Page Items -->
<div id="PrevNextBox">
<a href="index.html">< Previous Page</a>
<a href="2-JSON-Data.html">Next Page ></a>
</div>
<!-- Parse page content from markdown -->
<md-block>
# 1. Rest API Calls
## Camera Setup
Before we can begin talking to the camera over a network connection, we must enable those features in **Blackmagic Camera Setup**,
the official setup utility from Blackmagic. You can download it from their website [here](https://www.blackmagicdesign.com/developer/products/camera/sdk-and-software).
Once you have the utility downloaded, connect the camera to your computer with a USB cable and open the utility.
It will prompt you to update the camera's firmware if it is out of date. If you have any of the following camera models,
this is a _must_, since the networking functionality has just now been enabled in version 8.6.
- Pocket Cinema Camera 4K
- Pocket Cinema Camera 6K
- Pocket Cinema Camera 6K G2
- Pocket Cinema Camera 6K Pro
- Cinema Camera 6K
I'll be using a Studio Camera 6K Pro, whose network control settings after a factory reset look like this:
<div style="flex-direction: column;">
<img src="resources/images/1/FactorySettings.png" alt="A screenshot of the camera's factory network settings" width="80%" style="max-width: 600px;">
<span>Factory network settings for Studio Camera 6K Pro</span>
</div>
Enable all three protocols, plus utility administration over Ethernet just in case we need to change something down the line.
**Once these settings are enabled, anyone on the network will be able to control the settings and view (and delete) files on the camera.** Make sure you trust the other
machines and humans using the network. That's why equipment like this is usually given its own network, and why it's usually not connected to the internet. My settings now look like this:
<div style="flex-direction: column;">
<img src="resources/images/1/ChangedSettings.png" alt="A screenshot of the camera's new network settings" width="80%" style="max-width: 600px;">
<span>New network settings for Studio Camera 6K Pro</span>
</div>
If you haven't already, connect the camera to the network with an Ethernet cable (and, if necessary, a USB-C to Ethernet adapter). Configure the IP settings as needed
(choose DHCP if you're unsure).
## Hostname
The camera's "hostname" is a term I'll use a lot in this series. A hostname is a computer's name that can be used to talk to it over a network. Think of it like a more readable
version of an IP address (under the hood, your network does translation between them).
Blackmagic Cameras set their hostnames to reflect the name they've been set to at the top of the settings window (just with spaces replaced with dashes and a `.local` at the end).
So, for example, if your camera's name is "Studio Camera 6K Pro", your hostname would be:
```
Studio-Camera-6K-Pro.local
```
You'll notice that the setup window lists URLs for accessing the camera with different protocols like FTP, SMB, and the web media manager via HTTP. Web browsers understand HTTP and HTTPS protocols,
so you can copy/paste that address into a web browser to access the camera's internal "Web Media Manager", but we'll talk more about that later.
## "Do You Copy?"
To verify that your computer and the camera can talk over the network, disconnect any USB cables and open Blackmagic Camera Setup again. You should see your camera appear
with a LAN icon, as shown here:
<div style="flex-direction: column;">
<img src="resources/images/1/CameraSetupNetwork.png" alt="A screenshot of the camera connected over the network in BMD Camera Setup" width="80%" style="max-width: 600px;">
<span>Studio Camera 6K Pro connected over the network</span>
</div>
You might want to check the connectivity from a different machine that might not have Blackmagic Camera Setup installed. One way that will work on any machine is the `ping` command.
Open your terminal/command line and enter the following command:
```shell
ping <Hostname>
```
When I run this command, I get the following output:
<div style="flex-direction: column;">
<img src="resources/images/1/ping.png" alt="A screenshot of a terminal window running the ping command" width="80%" style="max-width: 600px;">
</div>
```shell
ping Studio-Camera-6K-Pro.local
```
We can see that my camera has an IP address of `169.254.247.32`. This is the address on the local, closed network, so it isn't a privacy or security risk to show it here.
We can also see that the camera successfully echoed all of the `ping` packets that it received, meaning that the camera and my computer can talk to each other.
Woohoo!
## The API
The [Blackmagic REST API](https://documents.blackmagicdesign.com/DeveloperManuals/RESTAPIforBlackmagicCameras.pdf?_v=1696143610000) works by sending HTTP requests to the device.
Different types of requests are sent to different endpoints, like subpages of a website.
Each HTTP request a machine makes has a "method" that specifies what kind of request it is. The ones that most of the BMD API calls use are:
- `GET` 	 (I'm asking you for some data)
- `PUT` 	 (I'm giving you updates for some data)
Let's look at a sample request:
```HTTP
GET /control/api/v1/lens/iris HTTP/1.1
Accept: text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.7
Accept-Encoding: gzip, deflate
Accept-Language: en-US,en;q=0.9
Cache-Control: max-age=0
Connection: keep-alive
Host: studio-camera-6k-pro.local
Upgrade-Insecure-Requests: 1
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0.0.0 Safari/537.36
```
<div><span>HTTP GET Request Header</span></div>
and its response:
```HTTP
HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Cache-Control: no-cache
Content-Length: 153
Content-Type: application/json; charset=utf-8
Server: BlackmagicDesign
{
"apertureNumber": 328,
"apertureStop": 4.400000095367432,
"continuousApertureAutoExposure": false,
"normalised": 0.021739130839705467
}
```
<div><span>HTTP GET Request Response Header & Data</span></div>
There's a lot of data that the program sending the request includes in the header, but we're only interested in these lines:
```HTTP
GET /control/api/v1/lens/iris HTTP/1.1
Host: studio-camera-6k-pro.local
```
In English, these lines mean we are sending a `GET` HTTP request to `studio-camera-6k-pro.local` with endpoint `/control/api/v1/lens/iris`.
This endpoint is valid and part of the API, so the camera should respond with details about the lens's aperture settings.
And, sure enough, the camera's response is exactly that. In the header, we see in the first line `200 OK`, which means that the request was successful.
(For more information about HTTP status codes, see ["List of HTTP Status Codes" - Wikipedia](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes).)
The data that came back from the camera is:
```JSON
{
"apertureNumber": 328,
"apertureStop": 4.400000095367432,
"continuousApertureAutoExposure": false,
"normalised": 0.021739130839705467
}
```
This is great news. The camera has returned details about the lens's iris as a JSON Object. JSON is a data format that can organize and store its contents within text strings
to be parsed by other software into data that it can use. All of the API request bodies are in JSON, from the response to a `GET` request to the data
sent in a `PUT` request.
### API Address
Notice that the endpoint in the request is `/control/api/v1/lens/iris`. All of the endpoints in the API start with `/control/api/v1/`, as described in the documentation.
Just like a website, the specific endpoint is concatenated to the end of the protocol and hostname, giving a full address for _this request_ of:
```
http://studio-camera-6k-pro.local/control/api/v1/lens/iris
```
## Our First Request
The documentation from Blackmagic mentions using third-party software like [Postman](https://www.postman.com/) to manually send API calls, but we can do our first ones
right here from a web browser. When you type an address into the top bar of a web browser, it sends a `GET` HTTP (or HTTPS) request to the address in the bar, and displays the body of
the response on the page. Normally, this response is HTML code which the browser renders into a website. But, the JSON response is formatted as text, so it displays that on a plain
page. When I enter the above address into Safari, this is what I see:
<div style="flex-direction: column;">
<img src="resources/images/1/WebRequest.png" alt="A screenshot of Safari with JSON text on the page" width="80%" style="max-width: 600px;">
<span>Interfacing with the API through a web browser</span>
</div>
If you've made it this far, congratulations! You just sent and received your first API call to your camera!
## Basic GET Requests
Using this "type-the-address-into-your-browser" method is a great way to play with the many `GET` requests available to us. Look through the API documentation and find
`GET` requests to try out! For example,
```
http://studio-camera-6k-pro.local/control/api/v1/system/format
```
gives me
```JSON
{
"codec": "BRaw:8_1",
"frameRate": "24",
"maxOffSpeedFrameRate": 60,
"minOffSpeedFrameRate": 5,
"offSpeedEnabled": false,
"offSpeedFrameRate": 60,
"recordResolution": {
"height": 2160,
"width": 3840
},
"sensorResolution": {
"height": 2160,
"width": 3840
}
}
```
and
```
http://studio-camera-6k-pro.local/control/api/v1/video/iso
```
gives me
```JSON
{
"iso": 400
}
```
Of course, typing these by hand into the address bar of a browser is not a super efficient way of having two computers talk to each other, so in the next lesson we'll
see how we can automate this process with JavaScript or Python. This will also open the door for us to send `PUT` commands and change settings on the camera.
See you there!
</md-block>
<div><a href="2-JSON-Data.html" style="text-align: center;">Next Article</a></div>
<!-- Footer -->
<footer>
<div style="text-align: center;">
<br>
© 2024 Dylan Speiser
<br>
GNU GPL v3.0
<br>
All product images and trademarks are Copyright Blackmagic Design.
</div>
</footer>
</body>
</html>