search

bitfocus / companion-module-requests

Repository for tracking module requests
95 stars 10 forks source link

Blackmagic Camera Control REST Api #1383

Open Julusian opened 5 months ago

Julusian commented 5 months ago

The name of the device, hardware, or software you would like to control:

Blackmagic design camera REST api

Perhaps related to #719 and https://github.com/bitfocus/companion-module-bmd-atem/issues/94

What you would like to be able to make it do from Companion:

For someone who intends to use this to define

Direct links or attachments to the ethernet control protocol or API:

There is a text description of it in the manual for the cameras, for example: https://documents.blackmagicdesign.com/UserManuals/BlackmagicMicroStudioCamera4KG2Manual.pdf?_v=1701331211000

The cameras also serve an openapi definition, which could be used to auto-generate a basic client library. A copy of this from firmware 8.4 (provided by a Micro Studio Camera G2) is bm-msc-g2-8.4.zip. When implementing, make sure to work from an updated copy as there could be changes.
It looks like the this schema defines all the functionality possible in the api, various methods fail on my camera as they are not supported on this model.

GarthDB commented 5 months ago

It looks like this data was already provided above as a zip, but I downloaded the same documentation from my Micro Studio Camera 4k G2 and posted it to a public gist to make it easier to review.

The most exciting part, I think, is the web socket for receiving updates, Notification.yaml. This should be invaluable for feedback updates of state changes, even if they occurred from another source like the ATEM.

GarthDB commented 5 months ago

I'm willing to take a stab at making this module. I'll start by creating an npm package for the functions.

Julusian commented 5 months ago

I'm willing to take a stab at making this module. I'll start by creating an npm package for the functions.

Please do!

One request from me is to make sure to generate the library using an openapi generator (ideally generating typescript). That should cut down the amount that needs to be done in the library significantly, and will make it loads easier to update when blackmagic updates the schema in the future, with the typescript giving usage of the library confidence over whether updates break anything

GarthDB commented 4 months ago

I took a first pass at generating the typescript-node client using the OpenAPI generator. It's in this repo. It does not include the Notifications because they are defined as an AsyncAPI. I looked into generating a client for that but haven't found a good match. The closest fit I could find was @asyncapi/ts-nats-template, which is based on nats.js. I think we could do something simpler with just websockets. The other AsyncAPI generator templates are for generating the service side, which isn't too helpful.

Next steps:

  1. setup typescript build task and release the npm package
  2. add support for the Notifications over websocket
  3. look into adding tests
alfo commented 4 months ago

+1 this would be very useful for me too. For now I'm making do with some basic HTTP requests but having a full module especially with feedback is ideal. Being able to use the Stream Deck Plus knobs to change the iris, focus/zoom/ and audio levels especially.

zachphillips commented 3 months ago

Hi @GarthDB I'd love to give this a spin. Aside from the notifications, is everything else working in your testing?

Thanks so much for generously sharing your work.

mattdking commented 1 month ago

FYI, these API controls are available as of March 28 for Pocket Cinema Cameras (4K, 6K, 6K G2, 6K Pro) via the 8.6 Public Beta.

DylanSpeiser commented 2 weeks ago

Any luck subscribing to the WebSocket events? I'm having trouble with that myself. I'm trying to do it in vanilla JS