v1.3.0: no SD card needed

GoPro HERO4 Black as a plug-and-play USB webcam (1920x1080 or 1280x720 at 29.97 fps, full sensor readout), microphone (48 kHz stereo) and USB Ethernet. No capture card, no app on the computer, and now no SD card needed after setup.

Prebuilt: no Docker needed. Everything is built except the firmware: GoPro's code isn't ours to share, so patch_firmware.py makes the patched image from your own copy of the official v05.00.00 UPDATE.zip. It accepts only that exact file, and writes the result only if it matches the tested image byte for byte (SHA-256 2c0eca6d…).

What's new since v1.2.0

• Runs without the SD card. The card is only needed to install. Put an empty h4/install on the card and turn the camera on once: the webcam files (~3 MB) are copied to the camera's internal flash, MD5-checked, and the result goes to h4_install.log. From then on the camera works with the card out (it appears ~10 s later than with a card).
  • How: Linux comes back from a hibernation image on every power-on, and the startup scripts after the hibernation point run every time. The patch adds one line to one of them (S65gopro2, same commands otherwise) that starts the webcam from internal flash. RTOS code untouched.
  • A card with h4.sh still takes precedence, so updating and testing work as before. h4/uninstall removes the internal copy.

Install

1. Download GoPro's v05.00.00 update: https://device-firmware.gp-static.com/13/HD4.02/camera_fw/05.00.00/UPDATE.zip
2. Download and unzip hero4-webcam-v1.3.0.zip, then:

   python3 -m pip install lzallright
   python3 patch_firmware.py UPDATE.zip /path/to/sdcard
   

3. Copy h4.sh and the h4 folder to the root of the card, put it in the camera and turn it on. It updates itself. Afterwards, delete UPDATE/ from the card.
4. Optional, to run without the card: create an empty h4/install on the card and turn the camera on once more.

Upgrading from v1.2.0 / v1.1.0: replace h4.sh and h4/ on the card (works on the older images with the card in), and flash the new image to run without the card.

Full instructions, options and how to undo: README. How it was found: docs/findings.md.

Assets

• hero4-webcam-v1.3.0.zip: card files (h4.sh, h4/: kernel modules, h4uvc, h4csi) plus the firmware patcher. No GoPro code.
• faad2-2.11.4.tar.gz: source of the faad2 statically linked into h4uvc (GPL-2.0). Code from FAAD2 is copyright (c) Nero AG, www.nero.com.

Risk: this flashes modified firmware to your camera. It worked on ours, but a bad flash can brick a camera, and modified firmware may void the warranty. Use at your own risk. Not affiliated with or endorsed by GoPro.

v1.2.0: full sensor readout

GoPro HERO4 Black as a plug-and-play USB webcam (1920x1080 or 1280x720 at 29.97 fps, the app picks), microphone (48 kHz stereo) and USB Ethernet. No capture card, no app on the computer.

Prebuilt: no Docker needed. Everything is built except the firmware: GoPro's code isn't ours to share, so patch_firmware.py makes the patched image from your own copy of the official v05.00.00 UPDATE.zip. It accepts only that exact file, and writes the result only if it matches the tested image byte for byte (SHA-256 ab817816…).

What's new since v1.1.0

• Sharper 1080p: full sensor readout. The stock idle preview reads the sensor 2x2-binned. The patch now adds an idle mode copied from the one the camera records 1080 SuperView 30 with, which reads the full 4000x3000 sensor, and h4uvc uses it (through the camera's 2.7K SuperView 30 setting). Same framing, still 1080p, visibly more fine detail.
• New card options: h4/bitrate (default 8 Mbps; 10 Mbps works, 12 Mbps drops frames) and h4/res (8 for the old binned readout).

Install

1. Download GoPro's v05.00.00 update: https://device-firmware.gp-static.com/13/HD4.02/camera_fw/05.00.00/UPDATE.zip
2. Download and unzip hero4-webcam-v1.2.0.zip, then:

   python3 -m pip install lzallright
   python3 patch_firmware.py UPDATE.zip /path/to/sdcard
   

3. Copy h4.sh and the h4 folder to the root of the card, put it in the camera and turn it on. It updates itself. Afterwards, delete UPDATE/ from the card.

Upgrading from v1.1.0: replace h4.sh and h4/ on the card. That alone keeps working on the v1.1.0 image (binned readout); flash the new image for the full readout. From v1.0.0: same steps as a first install.

Full instructions, options and how to undo: README. The whole story, including a 4K attempt that hangs the camera: docs/findings.md.

Assets

• hero4-webcam-v1.2.0.zip: card files (h4.sh, h4/: kernel modules, h4uvc, h4csi) plus the firmware patcher. No GoPro code.
• faad2-2.11.4.tar.gz: source of the faad2 statically linked into h4uvc (GPL-2.0). Code from FAAD2 is copyright (c) Nero AG, www.nero.com.

Risk: this flashes modified firmware to your camera. It worked on ours, but a bad flash can brick a camera, and modified firmware may void the warranty. Use at your own risk. Not affiliated with or endorsed by GoPro.

v1.1.0: 1080p, microphone hang fixed

GoPro HERO4 Black as a plug-and-play USB webcam, now at 1920x1080 (or 1280x720, the app picks) at 29.97 fps, plus microphone (48 kHz stereo) and USB Ethernet. No capture card, no app on the computer.

Prebuilt: no Docker needed. This release has everything built except the firmware. GoPro's code isn't ours to share, so patch_firmware.py makes the patched image from your own copy of the official v05.00.00 UPDATE.zip. It accepts only that exact file, and it writes the result only if it matches the tested image byte for byte (SHA-256 e0b87c26…).

Install or upgrade

1. Download GoPro's v05.00.00 update: https://device-firmware.gp-static.com/13/HD4.02/camera_fw/05.00.00/UPDATE.zip
2. Download and unzip hero4-webcam-v1.1.0.zip, then:

   python3 -m pip install lzallright
   python3 patch_firmware.py UPDATE.zip /path/to/sdcard
   

3. Copy h4.sh and the h4 folder to the root of the card (replacing the old ones when upgrading), put it in the camera and turn it on. It updates itself. Afterwards, delete UPDATE/ from the card.

Upgrading from v1.0.0: reflash too. The new h4cam.ko and h4uvc need the 1080p image; on the v1.0.0 (720p) image the webcam would announce 1080p and send 720p.

Full instructions, options and how to undo: README.

Changes since v1.0.0

• 1080p. The firmware patch now sets the idle preview's secondary encoder to 1920x1080 (still data only, still nothing written to the card). The webcam offers 1920x1080 and 1280x720; when an app picks 720p, h4uvc asks the camera for it through the HTTP API, no reflash. 8 Mbps H.264. Glass-to-glass latency is about 225 ms at 1080p and 195 ms at 720p.
• Fixed: reopening the microphone hung the whole camera. Closing the GoPro mic in one app and opening it again (the second open) froze the camera until a power cycle. This was in v1.0.0 too. The isochronous endpoint now stays enabled while the mic is closed.
• Fixed: false "interrupt storms". The USB driver's storm guard never reset its counters, so every ~50000 ordinary interrupts it masked an endpoint for a second (a gap in the mic, or a frozen picture).
• Fixed: frozen video with the camera still up. The video endpoint could be left masked with frames queued; the driver now re-arms it.
• With h4/debug on the card, h4uvc's log now survives a power cycle (copied to the card every 5 s).

Details in docs/findings.md.

Known issues

• During testing the camera rebooted by itself once (with an intermediate build) and hung once with several apps opening the camera at different sizes at the same time. Neither has shown up again with this release so far. If it happens, h4/debug keeps the logs.

Assets

• hero4-webcam-v1.1.0.zip: card files (h4.sh, h4/: kernel modules, h4uvc, h4csi) plus the firmware patcher. No GoPro code.
• faad2-2.11.4.tar.gz: source of the faad2 statically linked into h4uvc (GPL-2.0). Code from FAAD2 is copyright (c) Nero AG, www.nero.com.

Risk: this flashes modified firmware to your camera. It worked on ours, but a bad flash can brick a camera, and modified firmware may void the warranty. Use at your own risk. Not affiliated with or endorsed by GoPro.

v1.0.0

GoPro HERO4 Black as a plug-and-play USB webcam (1280x720 at 29.97 fps), microphone (48 kHz stereo) and USB Ethernet. No capture card, no app on the computer.

Prebuilt: no Docker needed. This release has everything built except the firmware. GoPro's code isn't ours to share, so patch_firmware.py makes the patched image from your own copy of the official v05.00.00 UPDATE.zip. It accepts only that exact file, and it writes the result only if it matches the tested image byte for byte.

Install

1. Download GoPro's v05.00.00 update: https://device-firmware.gp-static.com/13/HD4.02/camera_fw/05.00.00/UPDATE.zip
2. Download and unzip hero4-webcam-v1.0.0.zip, then:

   python3 -m pip install lzallright
   python3 patch_firmware.py UPDATE.zip /path/to/sdcard
   

3. Copy h4.sh and the h4 folder to the root of the card, put it in the camera and turn it on. It updates itself. Afterwards, delete UPDATE/ from the card.

Full instructions, options and how to undo: README.

Since the first commit

• Microphone crackle fixed. GoPro's streaming driver logged a line to the 115200 baud serial console every ~0.6 s, holding the CPU ~4 ms with interrupts off. The mic missed USB frames and macOS replayed old audio. h4uvc now keeps kernel messages off the console. Details in docs/findings.md.
• faad2 2.11.4 (from its new home, FreewareAdvancedAudio/faad2).
• Prebuilt releases: the patcher now takes UPDATE.zip directly.

Assets

• hero4-webcam-v1.0.0.zip: card files (h4.sh, h4/: kernel modules, h4uvc, h4csi) plus the firmware patcher. No GoPro code.
• faad2-2.11.4.tar.gz: source of the faad2 statically linked into h4uvc (GPL-2.0). Code from FAAD2 is copyright (c) Nero AG, www.nero.com.

Risk: this flashes modified firmware to your camera. It worked on ours, but a bad flash can brick a camera, and modified firmware may void the warranty. Use at your own risk. Not affiliated with or endorsed by GoPro.