GoPro

GoPro

Be a hero.

HTTP Specification v2.0

45 minute read

Overview

The GoPro API allows developers to create apps and utilities that interact with and control a GoPro camera.

What can you do with the GoPro API?

The GoPro API allows you to control and query the camera:

  • Capture photo/video media
  • Get media list
  • Change settings
  • Get and set the date/time
  • Get camera status
  • Get media metadata (file size, width, height, duration, tags, etc)
  • and more!

Supported Cameras

Below is a table of cameras that support GoPro's public HTTP API:

Model ID Model Code Marketing Name Minimal Firmware Version
60 H22.03 HERO11 Black Mini v01.10.00
58 H22.01 HERO11 Black v01.10.00
57 H21.01 HERO10 Black v01.10.00
55 HD9.01 HERO9 Black v01.70.00

The Basics

Connection

WiFi

Connection to the camera via WiFi requires that the camera's WiFi Access Point be enabled. This can be done by connecting to the camera via Bluetooth Low Energy (BLE) and sending the AP Control command: WIFI AP ON.

USB

OpenGoPro systems that utilize USB must support the Network Control Model (NCM) protocol. Connecting via USB requires the following steps:

  1. Physically connect the camera's USB-C port to your system
  2. Send HTTP command to enable wired USB control

Authentication

WiFi

Once the WiFi Access Point has been turned on, authentication with the camera simply requries connecting with the correct SSID and password. This information can be obtained in two ways:

  • Put the camera into pairing mode and tap the info button in the top-right corner of the screen.
  • Read the SSID/password directly via Bluetooth Low Energy. See Services and Characteristics seciton in BLE Specification for details.

USB

No authentication is necessary.

Socket Address

WiFi

The socket address for WiFi connections is 10.5.5.9:8080.

USB

The socket address for USB connections is 172.2X.1YZ.51:8080 where:

  • X is the 100's digit from the camera serial number
  • Y is the 10's digit from the camera serial number
  • Z is the 1's digit from the camera serial number

The camera's serial number can be obtained in any of the following ways:

  • Reading the sticker inside the camera's battery enclosure
  • Camera UI: Preferences >> About >> Camera Info
  • Bluetooth Low Energy by reading directly from Hardware Info . See Commands in BLE Specification for details.

For example, if the camera's serial number is C0000123456789, the IP address for USB connections would be 172.27.189.51.

Alternatively, the IP address can be discovered via mDNS as the camera registers the _gopro-web service.

Request and Response Formats

Most commands are sent via HTTP/GET and require no special headers. Responses come in two parts: The standard HTTP return codes and JSON containing any additional information.

The typical use case is that the camera accepts a valid command, returns HTTP/200 (OK) and empty JSON (i.e. { }) and begins asynchronously working on the command. If an error occurs, the camera will return a standard HTTP error code and JSON with helpful error/debug information.

Depending on the command sent, the camera can return JSON, binary, or Protobuf data. Some examples are listed below:

Command Return Type
Get Camera State JSON
Get Media Info JSON
Get Media GPMF Binary
Get Media List JSON
Get Media Screennail (JPEG) Binary
Get Media Thumbnail (JPEG) Binary
Get Presets JSON

Sending Commands

Depending on the camera's state, it may not be ready to accept specific commands. This ready state is dependent on the System Busy and the Encoding Active status flags. For example:

  • System Busy flag is set while loading presets, changing settings, formatting sdcard, ...
  • Encoding Active flag is set while capturing photo/video media

If the system is not ready, it should reject an incoming command; however, best practice is to always wait for the System Busy and Encode Active flags to be unset before sending messages other than camera status queries. For details regarding camera state, see Status Codes.

Keep Alive

In order to maximize battery life, GoPro cameras automatically go to sleep after some time. This logic is handled by a combination of an Auto Power Down setting which most (but not all) cameras support and a Keep Alive message that the user can regularly send to the camera. The camera will automatically go to sleep if both timers reach zero.

The Auto Power Down timer is reset when the user taps the LCD screen, presses a button on the camera or programmatically (un)sets the shutter, sets a setting, or loads a Preset.

The Keep Alive timer is reset when the user sends a keep alive message.

The best practice to prevent the camera from inadvertently going to sleep is to start sending Keep Alive messages every 3.0 seconds after a connection is established.

Command

HTTP/GET Description
/gopro/camera/keep_alive Send keep-alive

Commands

Using the Open GoPro API, a client can perform various command, control, and query operations!

Commands Quick Reference

Below is a table of commands that can be sent to the camera and how to send them.
✔ Indicates support for all Open GoPro firmware versions.
❌ Indicates a lack of support for all Open GoPro firmware versions.
>= vXX.YY.ZZ indicates support for firmware versions equal to or newer than vXX.YY.ZZ

Command Description HTTP Method Endpoint HERO11 Black Mini HERO11 Black HERO10 Black HERO9 Black
Analytics Set third party client GET /gopro/camera/analytics/set_client_info ✔ ✔ >= v01.30.00 >= v01.70.00
Camera: Get State Get camera state (status + settings) GET /gopro/camera/state ✔ ✔ ✔ ✔
Digital Zoom Digital zoom 50% GET /gopro/camera/digital_zoom?percent=50 ✔ ✔ ✔ ✔
Get Date/Time Get date/time GET /gopro/camera/get_date_time ✔ ✔ >= v01.30.00 >= v01.70.00
Keep-alive Send keep-alive GET /gopro/camera/keep_alive ✔ ✔ ✔ ✔
Media: GPMF Get GPMF data (JPG) GET /gopro/media/gpmf?path=100GOPRO/XXX.JPG ✔ ✔ ✔ ✔
Media: GPMF Get GPMF data (MP4) GET /gopro/media/gpmf?path=100GOPRO/XXX.MP4 ✔ ✔ ✔ ✔
Media: HiLight (Add) Add hilight to 100GOPRO/xxx.JPG GET /gopro/media/hilight/file?path=100GOPRO/XXX.JPG ✔ ✔ >= v01.30.00 >= v01.70.00
Media: HiLight (Add) Add hilight to 100GOPRO/xxx.MP4 at offset 2500 ms GET /gopro/media/hilight/file?path=100GOPRO/XXX.MP4&ms=2500 ✔ ✔ >= v01.30.00 >= v01.70.00
Media: HiLight (Remove) Remove hilight from 100GOPRO/xxx.JPG GET /gopro/media/hilight/remove?path=100GOPRO/XXX.JPG ✔ ✔ >= v01.30.00 >= v01.70.00
Media: HiLight (Remove) Remove hilight from 100GOPRO/xxx.MP4 at offset 2500ms GET /gopro/media/hilight/remove?path=100GOPRO/XXX.MP4&ms=2500 ✔ ✔ >= v01.30.00 >= v01.70.00
Media: HiLight Moment Hilight moment during encoding GET /gopro/media/hilight/moment ✔ ✔ >= v01.30.00 ❌
Media: Info Get media info (JPG) GET /gopro/media/info?path=100GOPRO/XXX.JPG ✔ ✔ ✔ ✔
Media: Info Get media info (MP4) GET /gopro/media/info?path=100GOPRO/XXX.MP4 ✔ ✔ ✔ ✔
Media: List Get media list GET /gopro/media/list ✔ ✔ ✔ ✔
Media: Screennail Get screennail for “100GOPRO/xxx.JPG” GET /gopro/media/screennail?path=100GOPRO/XXX.JPG ✔ ✔ ✔ ✔
Media: Screennail Get screennail for “100GOPRO/xxx.MP4” GET /gopro/media/screennail?path=100GOPRO/XXX.MP4 ✔ ✔ ✔ ✔
Media: Telemetry Get telemetry track data (JPG) GET /gopro/media/telemetry?path=100GOPRO/XXX.JPG ✔ ✔ ✔ ✔
Media: Telemetry Get telemetry track data (MP4) GET /gopro/media/telemetry?path=100GOPRO/XXX.MP4 ✔ ✔ ✔ ✔
Media: Thumbnail Get thumbnail for “100GOPRO/xxx.JPG” GET /gopro/media/thumbnail?path=100GOPRO/XXX.JPG ✔ ✔ ✔ ✔
Media: Thumbnail Get thumbnail for “100GOPRO/xxx.MP4” GET /gopro/media/thumbnail?path=100GOPRO/XXX.MP4 ✔ ✔ ✔ ✔
Media: Turbo Transfer Turbo transfer: off GET /gopro/media/turbo_transfer?p=0 ✔ ✔ ✔ ✔
Media: Turbo Transfer Turbo transfer: on GET /gopro/media/turbo_transfer?p=1 ✔ ✔ ✔ ✔
OTA Update Soft update: upload 12345 bytes starting at offset 67890 POST /gp/gpSoftUpdate (plus data) ✔ ✔ ✔ ✔
OTA Update Soft update: mark upload complete POST /gp/gpSoftUpdate (plus data) ✔ ✔ ✔ ✔
OTA Update Ota update: show canceled/failed ui on the camera GET /gp/gpSoftUpdate?request=canceled ✔ ✔ ✔ ✔
OTA Update Ota update: delete cached update files GET /gp/gpSoftUpdate?request=delete ✔ ✔ ✔ ✔
OTA Update Ota update: get current update state GET /gp/gpSoftUpdate?request=progress ✔ ✔ ✔ ✔
OTA Update Ota update: display update ui on camera GET /gp/gpSoftUpdate?request=showui ✔ ✔ ✔ ✔
OTA Update Ota update: initiate firmware update GET /gp/gpSoftUpdate?request=start ✔ ✔ ✔ ✔
Open GoPro Get version GET /gopro/version ✔ ✔ ✔ ✔
Presets: Get Status Get preset status GET /gopro/camera/presets/get ✔ ✔ ✔ ✔
Presets: Load Example preset id: 0x1234ABCD GET /gopro/camera/presets/load?id=305441741 ✔ ✔ ✔ ✔
Presets: Load Group Video GET /gopro/camera/presets/set_group?id=1000 ✔ ✔ ✔ ✔
Presets: Load Group Photo GET /gopro/camera/presets/set_group?id=1001 ❌ ✔ ✔ ✔
Presets: Load Group Timelapse GET /gopro/camera/presets/set_group?id=1002 ❌ ✔ ✔ ✔
Set Camera Control Status Set camera control status to idle GET /gopro/camera/control/set_ui_controller?p=0 ✔ ✔ >= v01.20.00 ❌
Set Camera Control Status Set camera control status to external_control GET /gopro/camera/control/set_ui_controller?p=2 ✔ ✔ >= v01.20.00 ❌
Set Date/Time Set date/time to 2023-01-31 03:04:05 GET /gopro/camera/set_date_time?date=2023_1_31&time=3_4_5 ✔ ✔ >= v01.30.00 >= v01.70.00
Set Local Date/Time Set local date/time to: 2023-01-31 03:04:05 (utc-02:00) (dst: on) GET /gopro/camera/set_date_time?date=2023_1_31&time=3_4_5&tzone=-120&dst=1 ✔ ✔ ❌ ❌
Set shutter Shutter: on GET /gopro/camera/shutter/start ✔ ✔ ✔ ❌
Set shutter Shutter: off GET /gopro/camera/shutter/stop ✔ ✔ ✔ ❌
Stream: Start Start preview stream GET /gopro/camera/stream/start ✔ ✔ ✔ ✔
Stream: Stop Stop preview stream GET /gopro/camera/stream/stop ✔ ✔ ✔ ✔
Webcam: Exit Exit webcam mode GET /gopro/webcam/exit ❌ ✔ ✔ ❌
Webcam: Preview Start preview stream GET /gopro/webcam/preview ❌ ✔ ✔ ❌
Webcam: Start Start webcam GET /gopro/webcam/start ❌ ✔ >= v01.40.00 ❌
Webcam: Start Start webcam GET /gopro/webcam/start?port=12345 ❌ >= v02.01.00 ❌ ❌
Webcam: Start Start webcam (res: resolution_1080, fov: wide) GET /gopro/webcam/start?res=12&fov=0 ❌ ✔ ✔ ❌
Webcam: Status Get webcam status GET /gopro/webcam/status ❌ ✔ ✔ ❌
Webcam: Stop Stop webcam GET /gopro/webcam/stop ❌ ✔ ✔ ❌
Webcam: Version Get webcam api version GET /gopro/webcam/version ❌ ✔ ✔ ❌
Wired USB Control Disable wired usb control GET /gopro/camera/control/wired_usb?p=0 ✔ ✔ >= v01.30.00 ❌
Wired USB Control Enable wired usb control GET /gopro/camera/control/wired_usb?p=1 ✔ ✔ >= v01.30.00 ❌

Settings

GoPro cameras have hundreds of setting options to choose from, all of which can be set using a single endpoint. The endpoint is configured with a setting id and an option value. Note that setting option values are not globally unique. While most option values are enumerated values, some are complex bitmasked values.

Settings Quick Reference

Below is a table of setting options detailing how to set every option supported by Open GoPro cameras.
✔ Indicates support for all Open GoPro firmware versions.
❌ Indicates a lack of support for all Open GoPro firmware versions.
>= vXX.YY.ZZ indicates support for firmware versions equal to or newer than vXX.YY.ZZ

Setting ID Setting Option HTTP Method Endpoint HERO11 Black Mini HERO11 Black HERO10 Black HERO9 Black
2 Resolution Set video resolution (id: 2) to 4k (id: 1) GET /gopro/camera/setting?setting=2&option=1 ✔ ✔ ✔ ✔
2 Resolution Set video resolution (id: 2) to 2.7k (id: 4) GET /gopro/camera/setting?setting=2&option=4 ✔ ✔ ✔ ✔
2 Resolution Set video resolution (id: 2) to 2.7k 4:3 (id: 6) GET /gopro/camera/setting?setting=2&option=6 ✔ ✔ ✔ ✔
2 Resolution Set video resolution (id: 2) to 1440 (id: 7) GET /gopro/camera/setting?setting=2&option=7 ❌ ❌ ❌ ✔
2 Resolution Set video resolution (id: 2) to 1080 (id: 9) GET /gopro/camera/setting?setting=2&option=9 ✔ ✔ ✔ ✔
2 Resolution Set video resolution (id: 2) to 4k 4:3 (id: 18) GET /gopro/camera/setting?setting=2&option=18 ✔ ✔ ✔ ✔
2 Resolution Set video resolution (id: 2) to 5k (id: 24) GET /gopro/camera/setting?setting=2&option=24 ❌ ❌ ❌ ✔
2 Resolution Set video resolution (id: 2) to 5k 4:3 (id: 25) GET /gopro/camera/setting?setting=2&option=25 ❌ ❌ ✔ ❌
2 Resolution Set video resolution (id: 2) to 5.3k 8:7 (id: 26) GET /gopro/camera/setting?setting=2&option=26 ✔ ✔ ❌ ❌
2 Resolution Set video resolution (id: 2) to 5.3k 4:3 (id: 27) GET /gopro/camera/setting?setting=2&option=27 ✔ ✔ ❌ ❌
2 Resolution Set video resolution (id: 2) to 4k 8:7 (id: 28) GET /gopro/camera/setting?setting=2&option=28 ✔ ✔ ❌ ❌
2 Resolution Set video resolution (id: 2) to 5.3k (id: 100) GET /gopro/camera/setting?setting=2&option=100 ✔ ✔ ✔ ❌
3 Frames Per Second Set video fps (id: 3) to 240 (id: 0) GET /gopro/camera/setting?setting=3&option=0 ✔ ✔ ✔ ✔
3 Frames Per Second Set video fps (id: 3) to 120 (id: 1) GET /gopro/camera/setting?setting=3&option=1 ✔ ✔ ✔ ✔
3 Frames Per Second Set video fps (id: 3) to 100 (id: 2) GET /gopro/camera/setting?setting=3&option=2 ✔ ✔ ✔ ✔
3 Frames Per Second Set video fps (id: 3) to 60 (id: 5) GET /gopro/camera/setting?setting=3&option=5 ✔ ✔ ✔ ✔
3 Frames Per Second Set video fps (id: 3) to 50 (id: 6) GET /gopro/camera/setting?setting=3&option=6 ✔ ✔ ✔ ✔
3 Frames Per Second Set video fps (id: 3) to 30 (id: 8) GET /gopro/camera/setting?setting=3&option=8 ✔ ✔ ✔ ✔
3 Frames Per Second Set video fps (id: 3) to 25 (id: 9) GET /gopro/camera/setting?setting=3&option=9 ✔ ✔ ✔ ✔
3 Frames Per Second Set video fps (id: 3) to 24 (id: 10) GET /gopro/camera/setting?setting=3&option=10 ✔ ✔ ✔ ✔
3 Frames Per Second Set video fps (id: 3) to 200 (id: 13) GET /gopro/camera/setting?setting=3&option=13 ✔ ✔ ✔ ✔
43 Webcam Digital Lenses Set webcam digital lenses (id: 43) to wide (id: 0) GET /gopro/camera/setting?setting=43&option=0 ✔ ✔ ✔ ✔
43 Webcam Digital Lenses Set webcam digital lenses (id: 43) to narrow (id: 2) GET /gopro/camera/setting?setting=43&option=2 ✔ ✔ ✔ ✔
43 Webcam Digital Lenses Set webcam digital lenses (id: 43) to superview (id: 3) GET /gopro/camera/setting?setting=43&option=3 ✔ ✔ ✔ ✔
43 Webcam Digital Lenses Set webcam digital lenses (id: 43) to linear (id: 4) GET /gopro/camera/setting?setting=43&option=4 ✔ ✔ ✔ ✔
59 Auto Power Down Set auto power down (id: 59) to never (id: 0) GET /gopro/camera/setting?setting=59&option=0 >= v02.10.00 ✔ ✔ ✔
59 Auto Power Down Set auto power down (id: 59) to 1 min (id: 1) GET /gopro/camera/setting?setting=59&option=1 >= v02.10.00 >= v02.01.00 ❌ ❌
59 Auto Power Down Set auto power down (id: 59) to 5 min (id: 4) GET /gopro/camera/setting?setting=59&option=4 >= v02.10.00 ✔ ✔ ✔
59 Auto Power Down Set auto power down (id: 59) to 15 min (id: 6) GET /gopro/camera/setting?setting=59&option=6 ❌ ✔ ✔ ✔
59 Auto Power Down Set auto power down (id: 59) to 30 min (id: 7) GET /gopro/camera/setting?setting=59&option=7 ❌ ✔ ✔ ✔
59 Auto Power Down Set auto power down (id: 59) to 8 seconds (id: 11) GET /gopro/camera/setting?setting=59&option=11 >= v02.10.00 ❌ ❌ ❌
59 Auto Power Down Set auto power down (id: 59) to 30 seconds (id: 12) GET /gopro/camera/setting?setting=59&option=12 >= v02.10.00 ❌ ❌ ❌
121 Video Digital Lenses Set video digital lenses (id: 121) to wide (id: 0) GET /gopro/camera/setting?setting=121&option=0 ✔ ✔ ✔ ✔
121 Video Digital Lenses Set video digital lenses (id: 121) to narrow (id: 2) GET /gopro/camera/setting?setting=121&option=2 ❌ ❌ ✔ ✔
121 Video Digital Lenses Set video digital lenses (id: 121) to superview (id: 3) GET /gopro/camera/setting?setting=121&option=3 ✔ ✔ ✔ ✔
121 Video Digital Lenses Set video digital lenses (id: 121) to linear (id: 4) GET /gopro/camera/setting?setting=121&option=4 ✔ ✔ ✔ ✔
121 Video Digital Lenses Set video digital lenses (id: 121) to max superview (id: 7) GET /gopro/camera/setting?setting=121&option=7 >= v02.00.00 ✔ ✔ ✔
121 Video Digital Lenses Set video digital lenses (id: 121) to linear + horizon leveling (id: 8) GET /gopro/camera/setting?setting=121&option=8 ✔ ✔ ✔ ✔
121 Video Digital Lenses Set video digital lenses (id: 121) to hyperview (id: 9) GET /gopro/camera/setting?setting=121&option=9 ✔ ✔ ❌ ❌
121 Video Digital Lenses Set video digital lenses (id: 121) to linear + horizon lock (id: 10) GET /gopro/camera/setting?setting=121&option=10 ✔ ✔ ❌ ❌
122 Photo Digital Lenses Set photo digital lenses (id: 122) to narrow (id: 19) GET /gopro/camera/setting?setting=122&option=19 ❌ ❌ ✔ ✔
122 Photo Digital Lenses Set photo digital lenses (id: 122) to max superview (id: 100) GET /gopro/camera/setting?setting=122&option=100 ❌ ✔ ✔ ✔
122 Photo Digital Lenses Set photo digital lenses (id: 122) to wide (id: 101) GET /gopro/camera/setting?setting=122&option=101 ❌ ✔ ✔ ✔
122 Photo Digital Lenses Set photo digital lenses (id: 122) to linear (id: 102) GET /gopro/camera/setting?setting=122&option=102 ❌ ✔ ✔ ✔
123 Time Lapse Digital Lenses Set time lapse digital lenses (id: 123) to narrow (id: 19) GET /gopro/camera/setting?setting=123&option=19 ❌ ❌ ✔ ✔
123 Time Lapse Digital Lenses Set time lapse digital lenses (id: 123) to max superview (id: 100) GET /gopro/camera/setting?setting=123&option=100 ❌ ✔ ✔ ❌
123 Time Lapse Digital Lenses Set time lapse digital lenses (id: 123) to wide (id: 101) GET /gopro/camera/setting?setting=123&option=101 ❌ ✔ ✔ ✔
123 Time Lapse Digital Lenses Set time lapse digital lenses (id: 123) to linear (id: 102) GET /gopro/camera/setting?setting=123&option=102 ❌ ✔ ✔ ✔
128 Media Format Set media format (id: 128) to time lapse video (id: 13) GET /gopro/camera/setting?setting=128&option=13 ❌ ✔ ✔ ✔
128 Media Format Set media format (id: 128) to time lapse photo (id: 20) GET /gopro/camera/setting?setting=128&option=20 ❌ ✔ ✔ ✔
128 Media Format Set media format (id: 128) to night lapse photo (id: 21) GET /gopro/camera/setting?setting=128&option=21 ❌ ✔ ✔ ✔
128 Media Format Set media format (id: 128) to night lapse video (id: 26) GET /gopro/camera/setting?setting=128&option=26 ❌ ✔ ✔ ✔
134 Anti-Flicker Set setup anti flicker (id: 134) to 60hz (id: 2) GET /gopro/camera/setting?setting=134&option=2 ✔ ✔ ✔ ✔
134 Anti-Flicker Set setup anti flicker (id: 134) to 50hz (id: 3) GET /gopro/camera/setting?setting=134&option=3 ✔ ✔ ✔ ✔
135 Hypersmooth Set video hypersmooth (id: 135) to off (id: 0) GET /gopro/camera/setting?setting=135&option=0 ✔ ✔ ✔ ✔
135 Hypersmooth Set video hypersmooth (id: 135) to on (id: 1) GET /gopro/camera/setting?setting=135&option=1 ✔ ✔ ❌ ✔
135 Hypersmooth Set video hypersmooth (id: 135) to high (id: 2) GET /gopro/camera/setting?setting=135&option=2 ❌ ❌ ✔ ✔
135 Hypersmooth Set video hypersmooth (id: 135) to boost (id: 3) GET /gopro/camera/setting?setting=135&option=3 ✔ ✔ ✔ ✔
135 Hypersmooth Set video hypersmooth (id: 135) to auto boost (id: 4) GET /gopro/camera/setting?setting=135&option=4 ✔ ✔ ❌ ❌
135 Hypersmooth Set video hypersmooth (id: 135) to standard (id: 100) GET /gopro/camera/setting?setting=135&option=100 ❌ ❌ ✔ ❌
150 Horizon Leveling Set video horizon levelling (id: 150) to off (id: 0) GET /gopro/camera/setting?setting=150&option=0 >= v02.00.00 ✔ ❌ ❌
150 Horizon Leveling Set video horizon levelling (id: 150) to on (id: 1) GET /gopro/camera/setting?setting=150&option=1 >= v02.00.00 ❌ ❌ ❌
150 Horizon Leveling Set video horizon levelling (id: 150) to locked (id: 2) GET /gopro/camera/setting?setting=150&option=2 ❌ ✔ ❌ ❌
151 Horizon Leveling Set photo horizon levelling (id: 151) to off (id: 0) GET /gopro/camera/setting?setting=151&option=0 ❌ ✔ ❌ ❌
151 Horizon Leveling Set photo horizon levelling (id: 151) to locked (id: 2) GET /gopro/camera/setting?setting=151&option=2 ❌ ✔ ❌ ❌
162 Max Lens Set max lens (id: 162) to off (id: 0) GET /gopro/camera/setting?setting=162&option=0 ❌ ✔ >= v01.20.00 ✔
162 Max Lens Set max lens (id: 162) to on (id: 1) GET /gopro/camera/setting?setting=162&option=1 ❌ ✔ >= v01.20.00 ✔
173 Video Performance Mode Set video performance mode (id: 173) to maximum video performance (id: 0) GET /gopro/camera/setting?setting=173&option=0 ❌ ❌ >= v01.16.00 ❌
173 Video Performance Mode Set video performance mode (id: 173) to extended battery (id: 1) GET /gopro/camera/setting?setting=173&option=1 ❌ ❌ >= v01.16.00 ❌
173 Video Performance Mode Set video performance mode (id: 173) to tripod / stationary video (id: 2) GET /gopro/camera/setting?setting=173&option=2 ❌ ❌ >= v01.16.00 ❌
175 Controls Set controls (id: 175) to easy (id: 0) GET /gopro/camera/setting?setting=175&option=0 ✔ ✔ ❌ ❌
175 Controls Set controls (id: 175) to pro (id: 1) GET /gopro/camera/setting?setting=175&option=1 ✔ ✔ ❌ ❌
176 Speed Set speed (id: 176) to 8x ultra slo-mo (id: 0) GET /gopro/camera/setting?setting=176&option=0 ❌ ✔ ❌ ❌
176 Speed Set speed (id: 176) to 4x super slo-mo (id: 1) GET /gopro/camera/setting?setting=176&option=1 ❌ ✔ ❌ ❌
176 Speed Set speed (id: 176) to 2x slo-mo (id: 2) GET /gopro/camera/setting?setting=176&option=2 ❌ ✔ ❌ ❌
176 Speed Set speed (id: 176) to 1x (low light) (id: 3) GET /gopro/camera/setting?setting=176&option=3 ❌ ✔ ❌ ❌
176 Speed Set speed (id: 176) to 4x super slo-mo (ext. batt) (id: 4) GET /gopro/camera/setting?setting=176&option=4 ❌ ✔ ❌ ❌
176 Speed Set speed (id: 176) to 2x slo-mo (ext. batt) (id: 5) GET /gopro/camera/setting?setting=176&option=5 ❌ ✔ ❌ ❌
176 Speed Set speed (id: 176) to 1x (ext. batt, low light) (id: 6) GET /gopro/camera/setting?setting=176&option=6 ❌ ✔ ❌ ❌
176 Speed Set speed (id: 176) to 8x ultra slo-mo (50hz) (id: 7) GET /gopro/camera/setting?setting=176&option=7 ❌ ✔ ❌ ❌
176 Speed Set speed (id: 176) to 4x super slo-mo (50hz) (id: 8) GET /gopro/camera/setting?setting=176&option=8 ❌ ✔ ❌ ❌
176 Speed Set speed (id: 176) to 2x slo-mo (50hz) (id: 9) GET /gopro/camera/setting?setting=176&option=9 ❌ ✔ ❌ ❌
176 Speed Set speed (id: 176) to 1x (low light, 50hz) (id: 10) GET /gopro/camera/setting?setting=176&option=10 ❌ ✔ ❌ ❌
176 Speed Set speed (id: 176) to 4x super slo-mo (ext. batt, 50hz) (id: 11) GET /gopro/camera/setting?setting=176&option=11 ❌ ✔ ❌ ❌
176 Speed Set speed (id: 176) to 2x slo-mo (ext. batt, 50hz) (id: 12) GET /gopro/camera/setting?setting=176&option=12 ❌ ✔ ❌ ❌
176 Speed Set speed (id: 176) to 1x (ext. batt, low light, 50hz) (id: 13) GET /gopro/camera/setting?setting=176&option=13 ❌ ✔ ❌ ❌
176 Speed Set speed (id: 176) to 8x ultra slo-mo (ext. batt) (id: 14) GET /gopro/camera/setting?setting=176&option=14 ❌ >= v02.01.00 ❌ ❌
176 Speed Set speed (id: 176) to 8x ultra slo-mo (ext. batt, 50hz) (id: 15) GET /gopro/camera/setting?setting=176&option=15 ❌ >= v02.01.00 ❌ ❌
176 Speed Set speed (id: 176) to 8x ultra slo-mo (long. batt) (id: 16) GET /gopro/camera/setting?setting=176&option=16 ❌ >= v02.01.00 ❌ ❌
176 Speed Set speed (id: 176) to 4x super slo-mo (long. batt) (id: 17) GET /gopro/camera/setting?setting=176&option=17 ❌ >= v02.01.00 ❌ ❌
176 Speed Set speed (id: 176) to 2x slo-mo (long. batt) (id: 18) GET /gopro/camera/setting?setting=176&option=18 ❌ >= v02.01.00 ❌ ❌
176 Speed Set speed (id: 176) to 1x (long. batt, low light) (id: 19) GET /gopro/camera/setting?setting=176&option=19 ❌ >= v02.01.00 ❌ ❌
176 Speed Set speed (id: 176) to 8x ultra slo-mo (long. batt, 50hz) (id: 20) GET /gopro/camera/setting?setting=176&option=20 ❌ >= v02.01.00 ❌ ❌
176 Speed Set speed (id: 176) to 4x super slo-mo (long. batt, 50hz) (id: 21) GET /gopro/camera/setting?setting=176&option=21 ❌ >= v02.01.00 ❌ ❌
176 Speed Set speed (id: 176) to 2x slo-mo (long. batt, 50hz) (id: 22) GET /gopro/camera/setting?setting=176&option=22 ❌ >= v02.01.00 ❌ ❌
176 Speed Set speed (id: 176) to 1x (long. batt, low light, 50hz) (id: 23) GET /gopro/camera/setting?setting=176&option=23 ❌ >= v02.01.00 ❌ ❌
176 Speed Set speed (id: 176) to 2x slo-mo (4k) (id: 24) GET /gopro/camera/setting?setting=176&option=24 ❌ >= v02.01.00 ❌ ❌
176 Speed Set speed (id: 176) to 4x super slo-mo (2.7k) (id: 25) GET /gopro/camera/setting?setting=176&option=25 ❌ >= v02.01.00 ❌ ❌
176 Speed Set speed (id: 176) to 2x slo-mo (4k, 50hz) (id: 26) GET /gopro/camera/setting?setting=176&option=26 ❌ >= v02.01.00 ❌ ❌
176 Speed Set speed (id: 176) to 4x super slo-mo (2.7k, 50hz) (id: 27) GET /gopro/camera/setting?setting=176&option=27 ❌ >= v02.01.00 ❌ ❌
177 Enable Night Photo Set enable night photo (id: 177) to off (id: 0) GET /gopro/camera/setting?setting=177&option=0 ❌ ✔ ❌ ❌
177 Enable Night Photo Set enable night photo (id: 177) to on (id: 1) GET /gopro/camera/setting?setting=177&option=1 ❌ ✔ ❌ ❌
178 Wireless Band Set wireless band (id: 178) to 2.4ghz (id: 0) GET /gopro/camera/setting?setting=178&option=0 ✔ ✔ ❌ ❌
178 Wireless Band Set wireless band (id: 178) to 5ghz (id: 1) GET /gopro/camera/setting?setting=178&option=1 ✔ ✔ ❌ ❌
179 Trail Length Set trail length (id: 179) to short (id: 1) GET /gopro/camera/setting?setting=179&option=1 ✔ ✔ ❌ ❌
179 Trail Length Set trail length (id: 179) to long (id: 2) GET /gopro/camera/setting?setting=179&option=2 ✔ ✔ ❌ ❌
179 Trail Length Set trail length (id: 179) to max (id: 3) GET /gopro/camera/setting?setting=179&option=3 ✔ ✔ ❌ ❌
180 Video Mode Set video mode (id: 180) to highest quality (id: 0) GET /gopro/camera/setting?setting=180&option=0 ❌ ✔ ❌ ❌
180 Video Mode Set video mode (id: 180) to extended battery (id: 1) GET /gopro/camera/setting?setting=180&option=1 ❌ ✔ ❌ ❌
180 Video Mode Set video mode (id: 180) to extended battery (green icon) (id: 101) GET /gopro/camera/setting?setting=180&option=101 ❌ >= v02.01.00 ❌ ❌
180 Video Mode Set video mode (id: 180) to longest battery (green icon) (id: 102) GET /gopro/camera/setting?setting=180&option=102 ❌ >= v02.01.00 ❌ ❌

Camera Capabilities

Camera capabilities usually change from one camera to another and often change from one release to the next. Below are documents that detail whitelists for basic video settings for every supported camera release.

Note about Dependency Ordering and Blacklisting

Capability documents define supported camera states. Each state is comprised of a set of setting options that are presented in dependency order. This means each state is guaranteed to be attainable if and only if the setting options are set in the order presented. Failure to adhere to dependency ordering may result in the camera's blacklist rules rejecting a set-setting command.

Example

Camera Command 1 Command 2 Command 3 Command 4 Command 5 Guaranteed Valid?
HERO10 Black Res: 1080 Anti-Flicker: 60Hz (NTSC) FPS: 240 FOV: Wide Hypersmooth: OFF ✔
HERO10 Black FPS: 240 Anti-Flicker: 60Hz (NTSC) Res: 1080 FOV: Wide Hypersmooth: OFF ❌

In the example above, the first set of commands will always work for basic video presets such as Standard.

In the second example, suppose the camera's Video Resolution was previously set to 4K. If the user tries to set Video FPS to 240, it will fail because 4K/240fps is not supported.

Capability Documents

Documents Product Release
capabilities.xlsx
capabilities.json 		HERO11 Black Mini v02.10.00
v02.00.00
v01.10.00
HERO11 Black v02.10.00
v02.01.00
v01.20.00
v01.12.00
v01.10.00
HERO10 Black v01.50.00
v01.46.00
v01.42.00
v01.40.00
v01.30.00
v01.20.00
v01.16.00
v01.10.00
HERO9 Black v01.72.00
v01.70.00

Spreadsheet Format

The capabilities spreadsheet contains worksheets for every supported release. Each row in a worksheet represents a whitelisted state and is presented in dependency order as outlined above.

JSON Format

The capabilities JSON contains a set of whitelist states for every supported release. Each state is comprised of a list of objects that contain setting and option IDs necessary to construct set-setting commands and are given in dependency order as outlined above.

Below is a simplified example of the capabilities JSON file; a formal schema is also available here: capabilities_schema.json 

{
    "(PRODUCT_NAME)": {
        "(RELEASE_VERSION)": {
            "states": [
                [
                    {"setting_name": "(str)", "setting_id": (int), "option_name": "(str)", "option_id": (int)},
                    ...
                ],
                ...
            ],
        },
        ...
    },
    ...
}

Media

The camera provides an endpoint to query basic details about media captured on the sdcard.

Chapters

All GoPro cameras break longer videos into chapters. GoPro cameras currently limit file sizes on sdcards to 4GB for both FAT32 and exFAT file systems. This limitation is most commonly seen when recording longer (10+ minute) videos. In practice, the camera will split video media into chapters named Gqccmmmm.MP4 (and ones for THM/LRV) such that:

  • q: Quality Level (X: Extreme, H: High, M: Medium, L: Low)
  • cc: Chapter Number (01-99)
  • mmmm: Media ID (0001-9999)

When media becomes chaptered, the camera increments subsequent Chapter Numbers while leaving the Media ID unchanged. For example, if the user records a long High-quality video that results in 4 chapters, the files on the sdcard may look like the following: 

-rwxrwxrwx@ 1 gopro  123456789  4006413091 Jan  1 00:00 GH010078.MP4
-rwxrwxrwx@ 1 gopro  123456789       17663 Jan  1 00:00 GH010078.THM
-rwxrwxrwx@ 1 gopro  123456789  4006001541 Jan  1 00:00 GH020078.MP4
-rwxrwxrwx@ 1 gopro  123456789       17357 Jan  1 00:00 GH020078.THM
-rwxrwxrwx@ 1 gopro  123456789  4006041985 Jan  1 00:00 GH030078.MP4
-rwxrwxrwx@ 1 gopro  123456789       17204 Jan  1 00:00 GH030078.THM
-rwxrwxrwx@ 1 gopro  123456789   756706872 Jan  1 00:00 GH040078.MP4
-rwxrwxrwx@ 1 gopro  123456789       17420 Jan  1 00:00 GH040078.THM
-rwxrwxrwx@ 1 gopro  123456789   184526939 Jan  1 00:00 GL010078.LRV
-rwxrwxrwx@ 1 gopro  123456789   184519787 Jan  1 00:00 GL020078.LRV
-rwxrwxrwx@ 1 gopro  123456789   184517614 Jan  1 00:00 GL030078.LRV
-rwxrwxrwx@ 1 gopro  123456789    34877660 Jan  1 00:00 GL040078.LRV

Media List Format

The format of the media list is given below. 

{
    "id": "<MEDIA SESSION ID>",
    "media": [
        {
            "d": "<DIRECTORY NAME>",
            "fs": [
                {<MEDIA ITEM INFO>},
                ...
            ]
        },
        ...
    ]
}

Media List Keys

The outer structure of the media list and the inner structure of individual media items use the keys in the table below.

Key Description
b ID of first member of a group (for grouped media items)
d Directory name
fs File system. Contains listing of media items in directory
g Group ID (if grouped media item)
glrv Low resolution video file size
id Media list session identifier
l ID of last member of a group (for grouped media items)
m List of missing/deleted group member IDs (for grouped media items)
media Contains media info for for each directory (e.g. 100GOPRO/, 101GOPRO/, …)
mod Last modified time (seconds since epoch)
n Media filename
s Size of (group) media in bytes
t Group type (for grouped media items) (b -> burst, c -> continuous shot, n -> night lapse, t -> time lapse)

Grouped Media Items

In order to minimize the size of the JSON transmitted by the camera, grouped media items such as Burst Photos, Time Lapse Photos, Night Lapse Photos, etc are represented with a single item in the media list with additional keys that allow the user to extrapolate individual filenames for each member of the group.

Filenames for group media items have the form "GXXXYYYY.ZZZ" where XXX is the group ID, YYY is the group member ID and ZZZ is the file extension.

For example, take the media list below, which contains a Time Lapse Photo group media item: 

{
    "id": "2530266050123724003",
    "media": [
        {
            "d": "100GOPRO",
            "fs": [
                {
                    "b": "8",
                    "cre": "1613669353",
                    "g": "1",
                    "l": "396",
                    "m": ['75', '139'],
                    "mod": "1613669353",
                    "n": "G0010008.JPG",
                    "s": "773977407",
                    "t": "t"
                }
            ]
        }
    ]
}

The first filename in the group is "G0010008.JPG" (key: "n").
The ID of the first group member in this case is "008" (key: "b").
The ID of the last group member in this case is "396" (key: "l").
The IDs of deleted members in this case are "75" and "139" (key: "m")
Given this information, the user can extrapolate that the group currently contains

G0010008.JPG, G0010009.JPG, G0010010.JPG,
...,
G0010074.JPG, G0010076.JPG,
...,
G0010138.JPG, G0010140.JPG,
...,
G0010394.JPG, G0010395.JPG. G0010396.JPG

Media HiLights

The HiLight Tags feature allows the user to tag moments of interest either during video capture or on existing media.

Add/Remove HiLights

Below is a table of all HiLight commands. For details on how to send HiLight commands, see Commands Quick Reference.

Command Description
Media: HiLight (Add) Video: Add a tag at a specific time offset (ms)
Photo: Add a tag
Media: HiLight (Remove) Video: Remove a tag at a specific time offset (ms)
Photo: Remove tag
Media: HiLight Moment Add a tag to the current time offset (ms) while encoding video

Note: Attempting to add a HiLight tag at a time offset that exceeds the duration of the video or removing a non-existent HiLight tag will result in an HTTP/500 error.

Get HiLights

Once HiLight tags have been added, they can be queried by calling the Media: Info command; the response content will be JSON that contains HiLight information:

Media Type Key Value
Photo hc HiLight Count
Video hc HiLight Count
Video hi HiLights (list of time offsets in ms)

Example

The JSON sample below shows media that contains three HiLights at time offsets 2502ms, 5839ms, and 11478ms. Note: Photo info will not have an "hi":[...] key-value pair. 

{
  ...,
  "hc":"3",
  "hi":[2502,5839,11478],
  ...,
}

Downloading Media

The URL to download/stream media from the DCIM/ directory on the sdcard is the Base URL plus /videos/DCIM/XXX/YYY where XXX is the directory name within DCIM/ given by the media list and YYY is the target media filename.

For example: Given the following media list: 

{
    "id": "3586667939918700960",
    "media": [
        {
            "d": "100GOPRO",
            "fs": [
                {
                    "n": "GH010397.MP4",
                    "cre": "1613672729",
                    "mod": "1613672729",
                    "glrv": "1895626",
                    "ls": "-1",
                    "s": "19917136"
                },
                {
                    "cre": "1614340213",
                    "mod": "1614340213",
                    "n": "GOPR0001.JPG",
                    "s": "6961371"
                }
            ]
        }
    ]
}

The URL to download GH010397.MP4 over WiFi would be http://10.5.5.9:8080/videos/DCIM/100GOPRO/GH010397.MP4

The URL to download GOPR0001.JPG over WiFi would be http://10.5.5.9:8080/videos/DCIM/100GOPRO/GOPR0001.JPG

Turbo Transfer

Some cameras support Turbo Transfer mode, which allows media to be downloaded over WiFi more rapidly. This special mode should only be used during media offload. It is recommended that the user check for and--if necessary--disable Turbo Transfer on connect. For details on which cameras are supported and how to enable and disable Turbo Transfer, see Commands Quick Reference.

Downloading Preview Stream

When the preview stream is started, the camera starts up a UDP client and begins writing MPEG Transport Stream data to the connected client on port 8554. In order to stream and save this data, the user can implement a UDP server that binds to the same port and appends datagrams to a file when they are received.

Camera State

The camera provides multiple types of state, all of which can be queried:

  • Camera state: Contains information about camera status (photos taken, date, is-camera-encoding, etc) and settings (current video resolution, current frame rate, etc)
  • Preset State: How presets are arranged into preset groups, their titles, icons, settings closely associated with each preset, etc

Camera State Format

Camera state is given in the following form:

{
    "status": {
        "1": <status 1 value>,
        "2": <status 2 value>,
        ...
    },
    "settings: {
        "2": <setting 2 value>,
        "3": <setting 3 value>,
        ...
    }
}

Where status X value and setting X value are almost always integer values. See Status Codes table in this document for exceptions.

For status, keys are status codes and values are status values.

For settings, keys are setting IDs, and values are option values

Status IDs

Below is a table of supported status IDs.
✔ Indicates support for all Open GoPro firmware versions.
❌ Indicates a lack of support for all Open GoPro firmware versions.
>= vXX.YY.ZZ indicates support for firmware versions equal to or newer than vXX.YY.ZZ

Status ID Name Description Type Values HERO11 Black Mini HERO11 Black HERO10 Black HERO9 Black
1 Internal battery present Is the system’s internal battery present? boolean 0: False
1: True
 ✔ ✔ ✔ ✔
2 Internal battery level Rough approximation of internal battery level in bars integer 0: Zero
1: One
2: Two
3: Three
 ✔ ✔ ✔ ✔
6 System hot Is the system currently overheating? boolean 0: False
1: True
 ✔ ✔ ✔ ✔
8 System busy Is the camera busy? boolean 0: False
1: True
 ✔ ✔ ✔ ✔
9 Quick capture active Is Quick Capture feature enabled? boolean 0: False
1: True
 ✔ ✔ ✔ ✔
10 Encoding active Is the system encoding right now? boolean 0: False
1: True
 ✔ ✔ ✔ ✔
11 Lcd lock active Is LCD lock active? boolean 0: False
1: True
 ✔ ✔ ✔ ✔
13 Video progress counter When encoding video, this is the duration (seconds) of the video so far; 0 otherwise integer * ✔ ✔ ✔ ✔
17 Enable Are Wireless Connections enabled? boolean 0: False
1: True
 ✔ ✔ ✔ ✔
19 State The pairing state of the camera integer 0: Never Started
1: Started
2: Aborted
3: Cancelled
4: Completed
 ✔ ✔ ✔ ✔
20 Type The last type of pairing that the camera was engaged in integer 0: Not Pairing
1: Pairing App
2: Pairing Remote Control
3: Pairing Bluetooth Device
 ✔ ✔ ✔ ✔
21 Pair time Time (milliseconds) since boot of last successful pairing complete action integer * ✔ ✔ ✔ ✔
22 State State of current scan for WiFi Access Points. Appears to only change for CAH-related scans integer 0: Never started
1: Started
2: Aborted
3: Canceled
4: Completed
 ✔ ✔ ✔ ✔
23 Scan time msec The time, in milliseconds since boot that the WiFi Access Point scan completed integer * ✔ ✔ ✔ ✔
24 Provision status WiFi AP provisioning state integer 0: Never started
1: Started
2: Aborted
3: Canceled
4: Completed
 ✔ ✔ ✔ ✔
26 Remote control version Wireless remote control version integer * ✔ ✔ ✔ ✔
27 Remote control connected Is a wireless remote control connected? boolean 0: False
1: True
 ✔ ✔ ✔ ✔
28 Pairing Wireless Pairing State integer * ✔ ✔ ✔ ✔
29 Wlan ssid Provisioned WIFI AP SSID. On BLE connection, value is big-endian byte-encoded int string * ✔ ✔ ✔ ✔
30 Ap ssid Camera’s WIFI SSID. On BLE connection, value is big-endian byte-encoded int string * ✔ ✔ ✔ ✔
31 App count The number of wireless devices connected to the camera integer * ✔ ✔ ✔ ✔
32 Enable Is Preview Stream enabled? boolean 0: False
1: True
 ✔ ✔ ✔ ✔
33 Sd status Primary Storage Status integer -1: Unknown
0: OK
1: SD Card Full
2: SD Card Removed
3: SD Card Format Error
4: SD Card Busy
8: SD Card Swapped
 ✔ ✔ ✔ ✔
34 Remaining photos How many photos can be taken before sdcard is full integer * ❌ ✔ ✔ ✔
35 Remaining video time How many minutes of video can be captured with current settings before sdcard is full integer * ✔ ✔ ✔ ✔
36 Num group photos How many group photos can be taken with current settings before sdcard is full integer * ❌ ✔ ✔ ✔
37 Num group videos Total number of group videos on sdcard integer * ✔ ✔ ✔ ✔
38 Num total photos Total number of photos on sdcard integer * ✔ ✔ ✔ ✔
39 Num total videos Total number of videos on sdcard integer * ✔ ✔ ✔ ✔
41 Ota status The current status of Over The Air (OTA) update integer 0: Idle
1: Downloading
2: Verifying
3: Download Failed
4: Verify Failed
5: Ready
6: GoPro App: Downloading
7: GoPro App: Verifying
8: GoPro App: Download Failed
9: GoPro App: Verify Failed
10: GoPro App: Ready
 ✔ ✔ ✔ ✔
42 Download cancel request pending Is there a pending request to cancel a firmware update download? boolean 0: False
1: True
 ✔ ✔ ✔ ✔
45 Camera locate active Is locate camera feature active? boolean 0: False
1: True
 ✔ ✔ ✔ ✔
49 Multi shot count down The current timelapse interval countdown value (e.g. 5…4…3…2…1…) integer * ✔ ✔ ✔ ✔
54 Remaining space Remaining space on the sdcard in Kilobytes integer * ✔ ✔ ✔ ✔
55 Supported Is preview stream supported in current recording/mode/secondary-stream? boolean 0: False
1: True
 ✔ ✔ ✔ ✔
56 Wifi bars WiFi signal strength in bars integer * ✔ ✔ ✔ ✔
58 Num hilights The number of hilights in encoding video (set to 0 when encoding stops) integer * ✔ ✔ ✔ ✔
59 Last hilight time msec Time since boot (msec) of most recent hilight in encoding video (set to 0 when encoding stops) integer * ✔ ✔ ✔ ✔
60 Next poll msec The min time between camera status updates (msec). Do not poll for status more often than this integer * ✔ ✔ ✔ ✔
64 Remaining timelapse time How many min of Timelapse video can be captured with current settings before sdcard is full integer * ✔ ✔ ✔ ✔
65 Exposure select type Liveview Exposure Select Mode integer 0: Disabled
1: Auto
2: ISO Lock
3: Hemisphere
 ❌ ✔ ✔ ✔
66 Exposure select x Liveview Exposure Select: y-coordinate (percent) percent 0-100 ❌ ✔ ✔ ✔
67 Exposure select y Liveview Exposure Select: y-coordinate (percent) percent 0-100 ❌ ✔ ✔ ✔
68 Gps status Does the camera currently have a GPS lock? boolean 0: False
1: True
 ✔ ✔ ✔ ✔
69 Ap state Is the WiFi radio enabled? boolean 0: False
1: True
 ✔ ✔ ✔ ✔
70 Internal battery percentage Internal battery level (percent) percent 0-100 ✔ ✔ ✔ ✔
74 Acc mic status Microphone Accesstory status integer 0: Microphone mod not connected
1: Microphone mod connected
2: Microphone mod connected and microphone plugged into Microphone mod
 ✔ ✔ ✔ ✔
75 Digital zoom Digital Zoom level (percent) percent 0-100 ✔ ✔ ✔ ✔
76 Wireless band Wireless Band integer 0: 2.4 GHz
1: 5 GHz
2: Max
 ✔ ✔ ✔ ✔
77 Digital zoom active Is Digital Zoom feature available? boolean 0: False
1: True
 ✔ ✔ ✔ ✔
78 Mobile friendly video Are current video settings mobile friendly? (related to video compression and frame rate) boolean 0: False
1: True
 ✔ ✔ ✔ ✔
79 First time use Is the camera currently in First Time Use (FTU) UI flow? boolean 0: False
1: True
 ❌ ❌ ✔ ✔
81 Band 5ghz avail Is 5GHz wireless band available? boolean 0: False
1: True
 ✔ ✔ ✔ ✔
82 System ready Is the system ready to accept commands? boolean 0: False
1: True
 ✔ ✔ ✔ ✔
83 Batt okay for ota Is the internal battery charged sufficiently to start Over The Air (OTA) update? boolean 0: False
1: True
 ✔ ✔ ✔ ✔
85 Video low temp alert Is the camera getting too cold to continue recording? boolean 0: False
1: True
 ✔ ✔ ✔ ✔
86 Actual orientation The rotational orientation of the camera integer 0: 0 degrees (upright)
1: 180 degrees (upside down)
2: 90 degrees (laying on right side)
3: 270 degrees (laying on left side)
 ✔ ✔ ✔ ✔
88 Zoom while encoding Is this camera capable of zooming while encoding (static value based on model, not settings) boolean 0: False
1: True
 ✔ ✔ ✔ ✔
89 Current mode Current flatmode ID integer * ✔ ✔ ✔ ✔
93 Active video presets Current Video Preset (ID) integer * ✔ ✔ ✔ ✔
94 Active photo presets Current Photo Preset (ID) integer * ❌ ✔ ✔ ✔
95 Active timelapse presets Current Timelapse Preset (ID) integer * ✔ ✔ ✔ ✔
96 Active presets group Current Preset Group (ID) integer * ✔ ✔ ✔ ✔
97 Active preset Current Preset (ID) integer * ✔ ✔ ✔ ✔
98 Preset modified Preset Modified Status, which contains an event ID and a preset (group) ID integer * ✔ ✔ ✔ ✔
99 Remaining live bursts How many Live Bursts can be captured before sdcard is full integer * ❌ ✔ ✔ ✔
100 Num total live bursts Total number of Live Bursts on sdcard integer * ❌ ✔ ✔ ✔
101 Capture delay active Is Capture Delay currently active (i.e. counting down)? boolean 0: False
1: True
 ✔ ✔ ✔ ✔
102 Media mod mic status Media mod State integer 0: Media mod microphone removed
2: Media mod microphone only
3: Media mod microphone with external microphone
 ✔ ✔ ✔ ✔
103 Timewarp speed ramp active Time Warp Speed integer 0: 15x
1: 30x
2: 60x
3: 150x
4: 300x
5: 900x
6: 1800x
7: 2x
8: 5x
9: 10x
10: Auto
11: 1x (realtime)
12: 1/2x (slow-motion)
 ✔ ✔ ✔ ✔
104 Linux core active Is the system’s Linux core active? boolean 0: False
1: True
 ❌ ❌ ✔ ✔
105 Camera lens type Camera lens type (reflects changes to setting 162) integer 0: Default
1: Max Lens
 ✔ ✔ ✔ ✔
106 Video hindsight capture active Is Video Hindsight Capture Active? boolean 0: False
1: True
 ❌ ✔ ✔ ✔
107 Scheduled preset Scheduled Capture Preset ID integer * ❌ ✔ ✔ ✔
108 Scheduled enabled Is Scheduled Capture set? boolean 0: False
1: True
 ❌ ✔ ✔ ✔
110 Media mod status Media Mode Status (bitmasked) integer 0: 000 = Selfie mod: 0, HDMI: 0, Media Mod Connected: False
1: 001 = Selfie mod: 0, HDMI: 0, Media Mod Connected: True
2: 010 = Selfie mod: 0, HDMI: 1, Media Mod Connected: False
3: 011 = Selfie mod: 0, HDMI: 1, Media Mod Connected: True
4: 100 = Selfie mod: 1, HDMI: 0, Media Mod Connected: False
5: 101 = Selfie mod: 1, HDMI: 0, Media Mod Connected: True
6: 110 = Selfie mod: 1, HDMI: 1, Media Mod Connected: False
7: 111 = Selfie mod: 1, HDMI: 1, Media Mod Connected: True
 ❌ ✔ ✔ ✔
111 Sd rating check error Does sdcard meet specified minimum write speed? boolean 0: False
1: True
 ✔ ✔ ✔ ❌
112 Sd write speed error Number of sdcard write speed errors since device booted integer * ✔ ✔ ✔ ❌
113 Turbo transfer Is Turbo Transfer active? boolean 0: False
1: True
 ✔ ✔ ✔ ✔
114 Camera control status Camera control status ID integer 0: Camera Idle: No one is attempting to change camera settings
1: Camera Control: Camera is in a menu or changing settings. To intervene, app must request control
2: Camera External Control: An outside entity (app) has control and is in a menu or modifying settings
 ✔ ✔ ✔ ❌
115 Usb connected Is the camera connected to a PC via USB? boolean 0: False
1: True
 ✔ ✔ ✔ ❌
116 Allow control over usb Camera control over USB state integer 0: Disabled
1: Enabled
 ✔ ✔ >= v01.30.00 ❌
117 Total sd space kb Total SD card capacity in kilobytes integer * ✔ ✔ ❌ ❌

Preset Status Format

Preset Status is returned as JSON, whose content is the serialization of the protobuf message: NotifyPresetStatus. Using Google protobuf APIs, the JSON can be converted back into a programmatic object in the user's language of choice.

Features

Presets

The camera organizes modes of operation into presets. A preset is a logical wrapper around a specific camera mode, title, icon, and a set of settings that enhance different styles of capturing media.

Depending on the camera's state, different collections of presets will be available for immediate loading and use. Below is a table of settings that affect the current preset collection and thereby which presets can be loaded:

ID Setting
162 Max Lens
173 Video Performance Mode
175 Controls
177 Enable Night Photo
180 Video Mode

To determine which presets are available for immediate use, get Preset Status.

Preset Status

All cameras support basic query and subscription mechanics that allow the user to:

  • Get hierarchical data describing the Preset Groups, Presets, and Settings that are available in the camera's current state

Preset Status should not be confused with camera status:

  • Preset Status contains information about current preset groups and presets
  • Camera status contains numerous statuses about current settings and camera system state

Preset Groups

Each Preset Group contains an ID, whether additional presets can be added, and an array of existing Presets.

Presets

Each Preset contains information about its ID, associated core mode, title, icon, whether it's a user-defined preset, whether the preset has been modified from its factory-default state (for factory-default presets only) and an array of Settings associated with the Preset.

Important Note: The Preset ID is required to load a Preset via the Presets: Load command.

Global Behaviors

In order to prevent undefined behavior between the camera and a connected app, simultaneous use of the camera and a connected app is discouraged.

Best practice for synchronizing user/app control is to use the Set Camera Control Status command and corresponding Camera Control Status (CCS) camera statuses in alignment with the finite state machine below:

IDLEControl Status: IdleCAMERA_CONTROLControl Status: Camera ControlEXTERNAL_CONTROLControl Status: External ControlApp sets CCS: IdleUser interacts with cameraUser returns camera to idle screenApp sets CCS: IdleApp sets CCS: External ControlApp sets CCS: IdleUser interacts with cameraUser interacts with cameraApp sets CCS: External ControlUser interacts with camera
Control Status ID
IDLE 0
CONTROL 1
EXTERNAL_CONTROL 2

Set Camera Control Status

This command is used to tell the camera that the app (i.e. External Control) wishes to claim control of the camera. This causes the camera to immediately exit any contextual menus and return to the idle screen. Any interaction with the camera's physical buttons will cause the camera to reclaim control and update control status accordingly. If the user returns the camera UI to the idle screen, the camera updates control status to Idle.

Note:

  • The entity currently claiming control of the camera is advertised in camera status 114
  • Information about whether the camera is in a contextual menu or not is advertised in camera status 63.

OTA Update

The Over The Air (OTA) update feature allows the user to update the camera's firmware via HTTP connection.

Firmware update files can be obtained from GoPro's update page or programmatically using the firmware catalog.

OTA Update Flow

The OTA update process involves uploading chunks (or all) of a file along with its corresponding SHA1 hash, marking the file complete and then telling the camera to begin the update process. For specific command examples, see /gp/gpSoftUpdate in Commands Quick Reference.

Note: Near the end of the firmware update process, in order to complete, the camera will need to reboot 1-2 times. This will cause any existing HTTP connections to be lost.

ClientClientCameraCameraObtain UPDATE.zip from update page or firmware catalogCalculate SHA1_HASH for UPDATE.zipHTTP/GET: /gp/gpSoftUpdate?request=deleteDelete any old/cached dataHTTP/200 (OK)JSON {"status":0,"message":"OK","sha1":"","bytes_complete":0,"complete":false}HTTP/GET: /gp/gpSoftUpdate?request=showuiDisplay update OSD on camera UIHTTP/200 (OK)JSON: {"status":0,"message":"OK","sha1":"","bytes_complete":0,"complete":false}loop[read CHUNK of UPDATE.zip, starting at OFFSET]HTTP/POST: /gp/gpSoftUpdateContent-Type: multipart/form-datadata={"sha1": "SHA1_HASH", "offset": OFFSET, file: @CHUNK}HTTP/200 (OK)JSON: {"status": 0,"message": "OK","sha1": "SHA1_HASH","bytes_complete": (total uploaded bytes),"complete": false}HTTP/POST: /gp/gpSoftUpdateContent-Type: multipart/form-datadata={"sha1": "SHA1_HASH", "complete": true}HTTP/200 (OK)JSON: {"status":0,"message":"OK","sha1":"SHA1_HASH","bytes_complete":(size of UPDATE.zip),"complete":true}HTTP/GET: /gp/gpSoftUpdate?request=startStart updating firmwareHTTP/200 (OK)JSON: {"status":0,"message":"OK","sha1":"SHA1_HASH","bytes_complete":(size of UPDATE.zip),"complete":true}loop[while camera updates firmware]HTTP/GET: /gp/gpSoftUpdate?request=progressJSON: {"status":11,"message":"Firmware update in progress"}WiFi connection lostCamera displays OSD "Update Complete", reboots 1-2 times

OTA Update Status Codes

ID Status Description
0 Ok No errors occurred
1 Unknown Request Server did not recognize the request
2 Bad Params Parameter values not recognized
3 SHA1 Send Mismatch SHA1 for chunk did not match SHA1 of previous chunk(s)
4 SHA1 Calculates Mismatch Calculated SHA1 did not match user-specified SHA1
5 HTTP Boundary Error HTTP Post malformed
6 HTTP Post Error Unexpected HTTP/POST Content Type
7 Server Busy HTTP server is busy
8 Offset Mismatch Tried to upload chunk with offset that did not align with previous chunk
9 Bad Post Data Server failed to parse POST data
10 File Incomplete Tried to start update before server finished validating .zip file
11 Update in Progress Firmware update in progress
12 Insufficient Space Insufficient space on the sdcard to hold (decompressed) update file

Webcam

The webcam feature enables developers who are interested in writing custom drivers to make the camera broadcast its video preview with a limited set of resolution and field of view options.

While active, the webcam feature runs a UDP client that sends raw Transport Stream data to the connected client on port 8554. To test basic functionality, connect the camera to your system, start the webcam, and use an application such as VLC to start a network stream on udp://@0.0.0.0:8554.

For readers interested in using a GoPro camera as a webcam with preexisting tools, please see How to use GoPro as a Webcam.

Webcam Finite State Machine

PREREQUISITEWired USB Control disabledOFFWebcam disabledIDLEWebcam readyHPPHigh power previewLPPLow power previewConnect USBStopExitStartStopExitPreviewStopExitStartPreviewStartPreview

Webcam Commands

Note: Prior to issuing webcam commands, Wired USB Control must be disabled. For details about how to send this and webcam commands, see Commands Quick Reference.

Command Connections Description
Webcam: Start USB Enters webcam mode, uses default resolution and last-used fov, starts high-res stream to the IP address of caller
Webcam: Start (with args) USB Enters webcam mode, uses specified resolution and/or fov, starts streaming to the IP address of caller
Webcam: Preview USB Enters webcam mode, sets stream resolution and bitrate, starts low-res stream to the IP address of caller.
Can set Webcam Digital Lenses and Digital Zoom levels while streaming
Webcam: Stop USB Stops the webcam stream
Webcam: Exit USB Stops the webcam stream and exits webcam mode
Webcam: Status USB Returns the current state of the webcam endpoint, including status and error codes (see tables below)
Webcam: Version USB Provides version information about webcam implementation in JSON format

Status Codes

Status Code
OFF 0
IDLE 1
HIGH_POWER_PREVIEW 2
LOW_POWER_PREVIEW 3

Error Codes

Status Code
NONE 0
SET_PRESET 1
SET_WINDOW_SIZE 2
EXEC_STREAM 3
SHUTTER 4
COM_TIMEOUT 5
INVALID_PARAM 6
UNAVAILABLE 7
EXIT 8

Webcam Settings

Aside from basic settings such as Resolution and FOV, the camera may support other settings such as Hypersmooth. In order to change these settings independently, the webcam must be in IDLE state.

Note: There is a known issue on some cameras in which the webcam state will be wrongly reported as IDLE after a new USB connection. The best workaround for this is to call Webcam: Start followed by the Webcam: Stop after connecting USB in order to attain the true IDLE state.

Resolutions

Note: If resolution is not set, 1080p will be used by default

ID Resolution HERO11 Black Mini HERO11 Black HERO10 Black HERO9 Black
4 480 ❌ ✔ ✔ ✔
7 720 ❌ ✔ ✔ ✔
12 1080 ❌ ✔ ✔ ✔

Digital Lenses / FOV

Note: If fov is not set, camera will default to the last-set fov or Wide if fov has never been set.

ID FOV HERO11 Black Mini HERO11 Black HERO10 Black HERO9 Black
0 WIDE ❌ ✔ ✔ ✔
2 NARROW ❌ ✔ ✔ ✔
3 SUPERVIEW ❌ ✔ ✔ ✔
4 LINEAR ❌ ✔ ✔ ✔

Limitations

HERO11 Black Mini

  • The camera will reject requests to change settings while encoding; for example, if Hindsight feature is active, the user cannot change settings
  • HTTP command arguments must be given in the order outlined in Commands Quick Reference

HERO11 Black

  • The camera will reject requests to change settings while encoding; for example, if Hindsight feature is active, the user cannot change settings
  • HTTP command arguments must be given in the order outlined in Commands Quick Reference

HERO10 Black

  • The camera will reject requests to change settings while encoding; for example, if Hindsight feature is active, the user cannot change settings
  • HTTP command arguments must be given in the order outlined in Commands Quick Reference

HERO9 Black

  • The HTTP server is not available while the camera is encoding, which means shutter controls are not supported over WiFi. This limitation can be overcome by using Bluetooth Low Energy for command and control and HTTP/REST for querying media content such as media list, media info, preview stream, etc.
  • USB command and control is not supported on HERO9 Black.
  • HTTP command arguments must be given in the order outlined in Commands Quick Reference

General

  • Unless changed by the user, GoPro cameras will automatically power off after some time (e.g. 5min, 15min, 30min). The Auto Power Down watchdog timer can be reset by sending periodic keep-alive messages to the camera. It is recommended to send a keep-alive at least once every 120 seconds.
  • In general, querying the value for a setting that is not associated with the current preset/core mode results in an undefined value. For example, the user should not try to query the current Photo Digital Lenses (FOV) value while in Standard preset (Video mode).