Blackmagic Camera Control openAPI REST

_bm_camera_control_api.md

Blackmagic Camera Control OpenAPI REST Example

This is the documentation from a Blackmagic Micro Studio Camera 4k G2, http://{ip}/control/documentation.html

AudioControl.yaml

openapi: 3.0.1
info:
  title: Audio Control API
  description: API For controlling audio on Blackmagic Design Cameras
  version: 0.1.0
servers:
- url: /control/api/v1
paths:
  /audio/channel/{channelIndex}/input:
    get:
      summary: Get the audio input (source and type) for the selected channel
      parameters:
        - name: channelIndex
          in: path
          description: The index of the channel that its input is being controlled. (Channels index from 0)
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Currently selected input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/input'
        '404':
          description: Channel does not exist
    put:
      summary: Set the audio input for the selected channel
      parameters:
        - name: channelIndex
          in: path
          description: The index of the channel that its input is being controlled. (Channels index from 0)
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/input'
      responses:
        '200':
          description: OK
        '400':
          description: Invalid input
        '404':
          description: Channel does not exist
  /audio/channel/{channelIndex}/input/description:
    get:
      summary: Get the description of the current input of the selected channel
      parameters:
        - name: channelIndex
          in: path
          description: The index of the channel that its input is being controlled. (Channels index from 0)
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Description of the current input of the selected channel
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/description'
        '404':
          description: Channel does not exist
  /audio/channel/{channelIndex}/supportedInputs:
    get:
      summary: Get the list of supported inputs and their availability to switch to for the selected channel
      parameters:
        - name: channelIndex
          in: path
          description: The index of the channel that its supported inputs are being queried. (Channels index from 0)
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: The list of supported inputs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/supportedInputs'
        '404':
          description: Channel does not exist
  /audio/channel/{channelIndex}/level:
    get:
      summary: Get the audio input level for the selected channel
      parameters:
        - name: channelIndex
          in: path
          description: The index of the channel that its input is being controlled. (Channels index from 0)
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Currently set level for the selected channel
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/level'
        '404':
          description: Channel does not exist
    put:
      summary: Set the audio input level for the selected channel
      parameters:
        - name: channelIndex
          in: path
          description: The index of the channel that its input is being controlled. (Channels index from 0)
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/level'
      responses:
        '200':
          description: OK
        '400':
          description: Invalid input
        '404':
          description: Channel does not exist
  /audio/channel/{channelIndex}/phantomPower:
    get:
      summary: Get the audio input phantom power for the selected channel if possible
      parameters:
        - name: channelIndex
          in: path
          description: The index of the channel that its input is being controlled. (Channels index from 0)
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Currently set level for the selected channel
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/phantomPower'

        '404':
          description: Channel does not exist
    put:
      summary: Set the audio phantom power for the selected channel
      parameters:
        - name: channelIndex
          in: path
          description: The index of the channel that its input is being controlled. (Channels index from 0)
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/phantomPower'
      responses:
        '200':
          description: OK
        '400':
          description: Phantom power is not supported for this input
        '404':
          description: Channel does not exist
  /audio/channel/{channelIndex}/padding:
    get:
      summary: Get the audio input padding for the selected channel
      parameters:
        - name: channelIndex
          in: path
          description: The index of the channel that its input is being controlled. (Channels index from 0)
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Currently set padding for the selected channel
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/padding'

        '404':
          description: Channel does not exist
    put:
      summary: Set the audio input padding for the selected channel
      parameters:
        - name: channelIndex
          in: path
          description: The index of the channel that its input is being controlled. (Channels index from 0)
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/padding'
      responses:
        '200':
          description: OK
        '400':
          description: Padding is not supported for this input
        '404':
          description: Channel does not exist
  /audio/channel/{channelIndex}/lowCutFilter:
    get:
      summary: Get the audio input low cut filter for the selected channel
      parameters:
        - name: channelIndex
          in: path
          description: The index of the channel that its input is being controlled. (Channels index from 0)
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Currently set low cut filter for the selected channel
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/lowCutFilter'

        '404':
          description: Channel does not exist
    put:
      summary: Set the audio input low cut filter for the selected channel
      parameters:
        - name: channelIndex
          in: path
          description: The index of the channel that its input is being controlled. (Channels index from 0)
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/lowCutFilter'
      responses:
        '200':
          description: OK
        '400':
          description: Low cut filter is not supported for this input
        '404':
          description: Channel does not exist
  /audio/channel/{channelIndex}/available:
    get:
      summary: Get the audio input's current availability for the selected channel. If unavailable, the source will be muted
      parameters:
        - name: channelIndex
          in: path
          description: The index of the channel that its input is being controlled. (Channels index from 0)
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Currently set availability for the selected channel
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/available'
        '404':
          description: Channel does not exist
components:
  schemas:
    input:
      type: object
      properties:
        input:
          type: string
          enum:
              - None
              - Camera - Left
              - Camera - Right
              - Camera - Mono
              - XLR1 - Mic
              - XLR1 - Line
              - XLR2 - Mic
              - XLR2 - Line
              - 3.5mm Left - Line
              - 3.5mm Left - Mic
              - 3.5mm Right - Line
              - 3.5mm Right - Mic
              - 3.5mm Mono - Line
              - 3.5mm Mono - Mic
    description:
      type: object
      properties:
        gainRange:
          type: object
          properties:
            Min:
              description: The minimum gain value in dB
              type: number
            Max:
              description: The maximum gain value in dB
              type: number
        capabilities:
          type: object
          properties:
            PhantomPower:
              description: Input supports setting of phantom power
              type: boolean
            LowCutFilter:
              description: Input supports setting of low cut filter
              type: boolean
            Padding:
              type: object
              properties:
                available:
                  description: Input supports setting of padding
                  type: boolean
                forced:
                  description: Padding is forced to be set for the input
                  type: boolean
                value:
                  description: Value of the padding in dB
                  type: number
    supportedInputs:
      type: object
      properties:
        supportedInputs:
          type: array
          items:
            type: object
            properties:
              schema:
                $ref: '#/components/schemas/input'
              available:
                description: Is the input available to be switched into from the current input for the selected channel
                type: boolean
    level:
      description: The input level of the selected channel. Only one property is required for setting. If both provided, gain will be prioritized and level would be ignored.
      type: object
      properties:
        gain:
          type: number
        normalised:
          type: number
    phantomPower:
      type: object
      properties:
        phantomPower:
          type: boolean
    padding:
      type: object
      properties:
        padding:
          type: boolean
    lowCutFilter:
      type: object
      properties:
        lowCutFilter:
          type: boolean
    available:
      type: object
      properties:
        available:
          type: boolean

ColorCorrectionControl.yaml

openapi: 3.0.1
info:
  title: Color Correction Control API
  description: API For controlling the color correction on Blackmagic Design products based on DaVinci Resolve Color Corrector
  version: 0.2.0
servers:
- url: /control/api/v1
paths:
  /colorCorrection/lift:
    get:
      summary: Get color correction lift
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Lift'
    put:
      summary: Set color correction lift
      requestBody:
        content:
          application/json:
              schema:
                $ref: '#/components/schemas/Lift'
      responses:
        200:
          description: OK
  /colorCorrection/gamma:
    get:
      summary: Get color correction gamma
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Gamma'
    put:
      summary: Set color correction gamma
      requestBody:
        content:
          application/json:
              schema:
                $ref: '#/components/schemas/Gamma'
      responses:
        200:
          description: OK
  /colorCorrection/gain:
    get:
      summary: Get color correction gain
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Gain'
    put:
      summary: Set color correction gain
      requestBody:
        content:
          application/json:
              schema:
                $ref: '#/components/schemas/Gain'
      responses:
        200:
          description: OK
  /colorCorrection/offset:
    get:
      summary: Get color correction offset
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Offset'
    put:
      summary: Set color correction offset
      requestBody:
        content:
          application/json:
              schema:
                $ref: '#/components/schemas/Offset'
      responses:
        200:
          description: OK
  /colorCorrection/contrast:
    get:
      summary: Get color correction contrast
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contrast'
    put:
      summary: Set color correction contrast
      requestBody:
        content:
          application/json:
              schema:
                $ref: '#/components/schemas/Contrast'
      responses:
        200:
          description: OK
  /colorCorrection/color:
    get:
      summary: Get color correction color properties
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Color'
    put:
      summary: Set color correction color properties
      requestBody:
        content:
          application/json:
              schema:
                $ref: '#/components/schemas/Color'
      responses:
        200:
          description: OK
  /colorCorrection/lumaContribution:
    get:
      summary: Get color correction luma contribution
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LumaContribution'
    put:
      summary: Set color correction luma contribution
      requestBody:
        content:
          application/json:
              schema:
                $ref: '#/components/schemas/LumaContribution'
      responses:
        200:
          description: OK

components:
  schemas:
    Lift:
      type: object
      properties:
        red:
          type: number
          maximum: 2.0
          minimum: -2.0
          default: 0.0
        green:
          type: number
          maximum: 2.0
          minimum: -2.0
          default: 0.0
        blue:
          type: number
          maximum: 2.0
          minimum: -2.0
          default: 0.0
        luma:
          type: number
          maximum: 2.0
          minimum: -2.0
          default: 0.0
    Gamma:
      type: object
      properties:
        red:
          type: number
          maximum: 4.0
          minimum: -4.0
          default: 0.0
        green:
          type: number
          maximum: 4.0
          minimum: -4.0
          default: 0.0
        blue:
          type: number
          maximum: 4.0
          minimum: -4.0
          default: 0.0
        luma:
          type: number
          maximum: 4.0
          minimum: -4.0
          default: 0.0
    Gain:
      type: object
      properties:
        red:
          type: number
          maximum: 16.0
          minimum: 0.0
          default: 0.0
        green:
          type: number
          maximum: 16.0
          minimum: 0.0
          default: 0.0
        blue:
          type: number
          maximum: 16.0
          minimum: 0.0
          default: 0.0
        luma:
          type: number
          maximum: 16.0
          minimum: 0.0
          default: 0.0
    Offset:
      type: object
      properties:
        red:
          type: number
          maximum: 8.0
          minimum: -8.0
          default: 0.0
        green:
          type: number
          maximum: 8.0
          minimum: -8.0
          default: 0.0
        blue:
          type: number
          maximum: 8.0
          minimum: -8.0
          default: 0.0
        luma:
          type: number
          maximum: 8.0
          minimum: -8.0
          default: 0.0
    Contrast:
      type: object
      properties:
        pivot:
          type: number
          maximum: 1.0
          minimum: 0.0
          default: 0.5
        adjust:
          type: number
          maximum: 2.0
          minimum: 0.0
          default: 1.0
    Color:
      type: object
      properties:
        hue:
          type: number
          maximum: 1.0
          minimum: -1.0
          default: 0.0
        saturation:
          type: number
          maximum: 2.0
          minimum: 0.0
          default: 1.0
    LumaContribution:
      type: object
      properties:
        lumaContribution:
          type: number
          maximum: 1.0
          minimum: 0.0
          default: 1.0

EventControl.yaml

openapi: 3.0.1
info:
  title: Event Control API
  description: API For working with built-in websocket.
  version: 1.0.0
servers:
- url: /control/api/v1
paths:
  /event/list:
    get:
      summary: Get the list of events that can be subscribed to using the websocket API.
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                  $ref: '#/components/schemas/eventsList'
components:
  schemas:
    eventsList:
      type: object
      properties:
        events:
          type: array
          items:
            type: string
            description: List of events that can be subscribed to using the websocket API

LensControl.yaml

openapi: 3.0.1
info:
  title: Lens Control API
  description: API For controlling the lens on Blackmagic Design products
  version: 0.1.0
servers:
- url: /control/api/v1
paths:
  /lens/iris:
    get:
      summary: Get lens' aperture
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  continuousApertureAutoExposure:
                    type: boolean
                    description: Is Aperture controlled by auto exposure
                  apertureStop:
                    $ref: '#/components/schemas/apertureStop'
                  normalised:
                    $ref: '#/components/schemas/normalised'
                  apertureNumber:
                    $ref: '#/components/schemas/apertureNumber'
    put:
      summary: Set lens' aperture
      requestBody:
        description: Only a single property need to be selected. If multiple provided, the order of priority is (apertureStop > normalised > apertureNumber)
        content:
          application/json:
              schema:
                type: object
                properties:
                  apertureStop:
                    $ref: '#/components/schemas/apertureStop'
                  normalised:
                    $ref: '#/components/schemas/normalised'
                  apertureNumber:
                    $ref: '#/components/schemas/apertureNumber'
      responses:
        200:
          description: OK
  /lens/zoom:
    get:
      summary: Get lens' zoom
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  focalLength:
                    $ref: '#/components/schemas/focalLength'
                  normalised:
                    $ref: '#/components/schemas/normalised'
    put:
      summary: Set lens' zoom
      requestBody:
        description: Only a single property need to be selected. If multiple provided, the order of priority is (focalLength > normalised)
        content:
          application/json:
              schema:
                type: object
                properties:
                  focalLength:
                    $ref: '#/components/schemas/focalLength'
                  normalised:
                    $ref: '#/components/schemas/normalised'
      responses:
        200:
          description: OK
  /lens/focus:
    get:
      summary: Get lens' focus
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  focus:
                    $ref: '#/components/schemas/normalised'
    put:
      summary: Set lens' focus
      requestBody:
        content:
          application/json:
              schema:
                type: object
                properties:
                  focus:
                    $ref: '#/components/schemas/normalised'
      responses:
        200:
          description: OK
  /lens/focus/doAutoFocus:
    put:
      summary: Perform auto focus
      responses:
        200:
          description: OK

components:
  schemas:
    apertureStop:
      type: number
      description: Aperture stop value
    normalised:
      type: number
      description: Normalised value
      maximum: 1.0
      minimum: 0.0
    apertureNumber:
      type: number
      description: Aperture number
    focalLength:
      type: integer
      description: Focal length in mm

MediaControl.yaml

openapi: 3.0.1
info:
  title: Media Control API
  description: API for controlling media devices in Blackmagic Design products.
  version: 1.0.0
servers:
- url: /control/api/v1
paths:
  /media/workingset:
    get:
      summary: Get the list of media devices currently in the working set.
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workingset'
  /media/active:
    get:
      summary: Get the currently active media device.
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActiveMedia'
    put:
      summary: Set the currently active media device.
      requestBody:
        description: Set the specified index to be active
        content:
          application/json:
            schema:
              type: object
              properties:
                workingsetIndex:
                  type: integer
                  description: Working set index of the media to become active
      responses:
        204:
          description: No Content
  /media/devices/doformatSupportedFilesystems:
    get:
      summary: Get the list of filesystems available to format the device.
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DoFormatSupportedFilesystems'
  /media/devices/{deviceName}:
    get:
      summary: Get information about the selected device.
      parameters:
        - in: path
          name: deviceName
          schema:
            type: string
          required: true
          description: Device name of the media device, as returned by deviceName member of Workingset or ActiveMedia
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MediaDeviceInformation'
  /media/devices/{deviceName}/doformat:
    get:
      summary: Get a format key, used to format the device with a put request.
      parameters:
        - in: path
          name: deviceName
          schema:
            type: string
          required: true
          description: Device name of the media device, as returned by deviceName member of Workingset or ActiveMedia
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                properties:
                  deviceName:
                    type: string
                    description: Internal device name of this media device
                  key:
                    $ref: '#/components/schemas/FormatKey'
    put:
      summary: Perform a format of the media device.
      parameters:
        - in: path
          name: deviceName
          schema:
            type: string
          required: true
          description: Device name of the media device, as returned by deviceName member of Workingset or ActiveMedia
      requestBody:
        content:
          application/json:
            schema:
              properties:
                key:
                  $ref: '#/components/schemas/FormatKey'
                filesystem:
                  type: string
                  description: Filesystem to format to (supportedFilesystems returns list of supported fileSystems)
                volume:
                  type: string
                  description: Volume name to set for the disk after format
      responses:
        204:
          description: No Content
components:
  schemas:
    Workingset:
      type: object
      properties:
        size:
          type: integer
          description: The fixed size of this device's working set
        workingset:
          type: array
          required: [index]
          items:
            type: object
            properties:
              index:
                type: integer
                description: Index of this media in the working set
                example: 0
              activeDisk:
                type: boolean
                description: Is this current item the active disk
                example: false
              volume:
                type: string
                description: Volume name
                example: My disk
              deviceName:
                type: string
                description: Internal device name of this media device
                example: sd1
              remainingRecordTime:
                type: integer
                description: Remaining record time on media device in seconds
                example: 5124087
              totalSpace:
                type: integer
                description: Total space on media device in bytes
                example: 9817071702016
              remainingSpace:
                type: integer
                description: Remaining space on media device in bytes
                example: 7817071702016
              clipCount:
                type: integer
                description: Number of clips currently on the device
                example: 12
    ActiveMedia:
      type: object
      properties:
        workingsetIndex:
          type: integer
          description: Working set index of the active media device
          example: 0
        deviceName:
          type: string
          description: Internal device name of this media device
          example: sd1
    DoFormatSupportedFilesystems:
      type: array
      example: [ExFat, HFS]
      items:
        type: string
    MediaDeviceInformation:
      type: object
      properties:
        state:
          type: string
          enum: [None, Scanning, Mounted, Uninitialised, Formatting, RaidComponent]
          description: The current state of the media device.
    FormatKey:
      type: string
      description: The key used to format this device, it must be fetched with the GET request and then provided back with a PUT request

Notification.yaml

asyncapi: 2.6.0
info:
  title: Notification websocket
  version: 1.0.0
  description: Service that notifies subscribers of device state changes.
servers:
  public:
    url: /control/api/v1/event/websocket
    protocol: ws
channels:
  /:
    subscribe:
      message:
        oneOf:
          - $ref: '#/components/messages/responseMessage'
          - $ref: '#/components/messages/eventMessage'
    publish:
      message:
        oneOf:
          - $ref: '#/components/messages/responseMessage'
components:
  messages:
    requestMessage:
      payload:
        type: object
        properties:
          data:
            $ref: '#/components/messages/actionRequest'
          type:
            type: string
            enum: [request]
          id:
            description: Optional parameter that repeats the id in the output for tracking messages
            type: number
        x-response:
          oneOf:
            - $ref: '#/components/messages/responseMessage'
    responseMessage:
      payload:
        type: object
        properties:
          data:
            $ref: '#/components/schemas/actionData'
          type:
            type: string
            enum: [response]
          id:
            description: Optional parameter that repeats the id in the output for tracking messages
            type: number
        x-response:
          oneOf:
            - $ref: '#/components/schemas/actionData'
    eventMessage:
      payload:
        type: object
        properties:
          data:
            $ref: '#/components/schemas/eventData'
          type:
            type: string
            enum: [event]
        x-response:
          oneOf:
            - $ref: '#/components/schemas/actionData'
    actionRequest:
      payload:
        type: object
        properties:
          action:
            $ref: '#/components/schemas/action'
          properties:
            type: array
            items:
              $ref: '#/components/schemas/deviceProperty'
          values:
            type: object
            properties:
              <schemas/property>:
                $ref: '#/components/schemas/devicePropertyValue'
  schemas:
    actionData:
      type: object
      properties:
        action:
          $ref: '#/components/schemas/action'
        properties:
          type: array
          items:
            $ref: '#/components/schemas/deviceProperty'
        values:
          type: object
          properties:
            <schemas/property>:
              $ref: '#/components/schemas/devicePropertyValue'
        success:
          type: boolean
    eventData:
      type: object
      properties:
        action:
          type: string
          enum:
            - propertyValueChanged
        property:
          $ref: '#/components/schemas/deviceProperty'
        value:
          $ref: '#/components/schemas/devicePropertyValue'
    action:
      type: string
      enum:
        - subscribe
        - unsubscribe
        - listSubscriptions
        - listProperties
    deviceProperty:
      type: string
      description: Device property the user can subscribe to. The user can either choose a value from the predefined enum or provide a wildcard string.
      enum:
        - $ref: '#/components/schemas/ActiveMedia/x-propertyName'
        - $ref: '#/components/schemas/SystemResponse/x-propertyName'
        - $ref: '#/components/schemas/CodecFormat/x-propertyName'
        - $ref: '#/components/schemas/VideoFormat/x-propertyName'
        - $ref: '#/components/schemas/Format/x-propertyName'
        - $ref: '#/components/schemas/SupportedFormats/x-propertyName'
        - $ref: '#/components/schemas/Timeline/x-propertyName'
        - $ref: '#/components/schemas/TransportResponse/x-propertyName'
        - $ref: '#/components/schemas/Stop/x-propertyName'
        - $ref: '#/components/schemas/Play/x-propertyName'
        - $ref: '#/components/schemas/Playback/x-propertyName'
        - $ref: '#/components/schemas/Record/x-propertyName'
        - $ref: '#/components/schemas/Timecode/x-propertyName'
        - $ref: '#/components/schemas/TimecodeSource/x-propertyName'
      pattern: '.*'
    devicePropertyValue:
      type: object
      description: Value of the property
      oneOf:
          - $ref: '#/components/schemas/ActiveMedia'
          - $ref: '#/components/schemas/SystemResponse'
          - $ref: '#/components/schemas/CodecFormat'
          - $ref: '#/components/schemas/VideoFormat'
          - $ref: '#/components/schemas/Format'
          - $ref: '#/components/schemas/SupportedFormats'
          - $ref: '#/components/schemas/Timeline'
          - $ref: '#/components/schemas/TransportResponse'
          - $ref: '#/components/schemas/Stop'
          - $ref: '#/components/schemas/Play'
          - $ref: '#/components/schemas/Playback'
          - $ref: '#/components/schemas/Record'
          - $ref: '#/components/schemas/Timecode'
          - $ref: '#/components/schemas/TimecodeSource'
    ActiveMedia:
      type: object
      x-propertyName: /media/active
      properties:
        workingsetIndex:
          type: integer
          description: Working set index of the active media device
        deviceName:
          type: string
          description: Internal device name of this media device
    SystemResponse:
      type: object
      x-propertyName: /system
      properties:
        codecFormat:
          $ref: "#/components/schemas/CodecFormat"
        videoFormat:
          $ref: "#/components/schemas/VideoFormat"
    CodecFormat:
      type: object
      x-propertyName: /system/codecFormat
      description: Currently selected codec
      properties:
        codec:
          type: string
          description: Currently selected codec
          example: ProRes:HQ
        container:
          type: string
          description: Multimedia container format
          example: MOV
    FrameRate:
      type: string
      enum:
        - "23.98"
        - "24.00"
        - "24"
        - "25.00"
        - "25"
        - "29.97"
        - "30.00"
        - "30"
        - "47.95"
        - "48.00"
        - "48"
        - "50.00"
        - "50"
        - "59.94"
        - "60.00"
        - "60"
        - "119.88"
        - "120.00"
        - "120"
    VideoFormat:
      type: object
      x-propertyName: /system/videoFormat
      description: Currently selected video format
      properties:
        frameRate:
          type: string
          $ref: "#/components/schemas/FrameRate"
          description: Frame rate
          example: "30"
        height:
          type: number
          description: Height dimension of video format
          example: 1920
        width:
          type: number
          description: Width dimension of video format
          example: 1080
        interlaced:
          type: boolean
          description: Is the display format interlaced?
          example: false
        name:
          description: Video format serialised as a string
          example: 1920x1080p29.97
          type: string
    Format:
      type: object
      x-propertyName: /system/format
      properties:
        codec:
          type: string
          description: Currently selected codec
          example: BRaw:8_1
        frameRate:
          $ref: "#/components/schemas/FrameRate"
          description: Frame rate
          example: "24"
        maxOffSpeedFrameRate:
          type: number
          example: 60
        minOffSpeedFrameRate:
          type: number
          example: 5
        offSpeedEnabled:
          type: boolean
          example: false
        offSpeedFrameRate:
          type: number
          example: 60
        recordResolution:
          $ref: '#/components/schemas/Resolution'
        sensorResolution:
          $ref: '#/components/schemas/Resolution'
    Resolution:
      type: object
      properties:
        height:
          type: number
          description: Height of the resolution
          example: 2160
        width:
          type: number
          description: Width of the resolution
          example: 3840
    SupportedFormats:
      type: object
      x-propertyName: /system/supportedFormats
      properties:
        supportedFormats:
          type: array
          items:
            $ref: '#/components/schemas/SupportedFormat'
    SupportedFormat:
      type: object
      properties:
        codecs:
          type: array
          items:
            type: string
            example: BRaw:Q0
        frameRates:
          type: array
          items:
            $ref: '#/components/schemas/FrameRate'
        maxOffSpeedFrameRate:
          type: number
          example: 60
        minOffSpeedFrameRate:
          type: number
          example: 5
        recordResolution:
          $ref: '#/components/schemas/Resolution'
        sensorResolution:
          $ref: '#/components/schemas/Resolution'
    Timeline:
      type: object
      x-propertyName: /timelines/0
      properties:
        clips:
          type: array
          items:
            type: object
            properties:
              clipUniqueId:
                type: integer
                description: Unique ID used to identify this clip
              frameCount:
                type: integer
                description: Number of frames in this clip on the timeline
    TransportResponse:
      type: object
      x-propertyName: /transports/0
      properties:
        mode:
          type: string
          description: Transport mode
          enum:
          - InputPreview
          - InputRecord
          - Output
    Stop:
      type: boolean
      x-propertyName: /transports/0/stop
      description: true when transport mode is InputPreview or when in Output mode and speed is 0
    Play:
      type: boolean
      x-propertyName: /transports/0/play
      description: True when transport is in Output mode and speed is non-zero
    Playback:
      type: object
      x-propertyName: /transports/0/playback
      properties:
        type:
          type: string
          enum:
          - Play
          - Jog
          - Shuttle
          - Var
        loop:
          description: When true playback loops from the end of the timeline to the beginning of the timeline
          type: boolean
        singleClip:
          description: When true playback loops from the end of the current clip to the beginning of the current clip
          type: boolean
        speed:
          description: Playback speed, 1.0 for normal forward playback
          type: number
        position:
          type: integer
          description: Playback position on the timeline in units of video frames
    Record:
      type: object
      x-propertyName: /transports/0/record
      properties:
        recording:
          description: Is transport in Input Record mode
          type: boolean
    Timecode:
      type: object
      x-propertyName: /transports/0/timecode
      properties:
        timecode:
          type: number
          description: The time of day timecode in units of binary-coded decimal (BCD).
        clip:
          type: number
          description: The position of the clip timecode in units of binary-coded decimal (BCD).
    TimecodeSource:
      type: object
      x-propertyName: /transports/0/timecode/source
      properties:
        timecode:
          type: string
          enum: [Timecode, Clip]

PresetControl.yaml

openapi: 3.0.1
info:
  title: Preset Control API
  description: API For controlling the presets on Blackmagic Design products
  version: 0.1.0
servers:
- url: /control/api/v1
paths:
  /presets:
    get:
      summary: Get the list of the presets on the camera
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/presetList'
    post:
      summary: Send a preset file to the camera
      requestBody:
        content:
          application/octet-stream:
            schema:
              type: string
              format: binary
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/postPresetResponse'
  /presets/active:
    get:
      summary: Get the list of the presets on the camera
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/activePreset'
    put:
      summary: Set the active preset on the camera
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/activePreset'
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: string
  /presets/{presetName}:
    get:
      summary: Download the preset file
      parameters:
        - in: path
          name: presetName
          description: name of the preset file
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
    put:
      summary: Update a preset on the camera if it exists, if not create a preset and save current state with the presetName
      parameters:
        - in: path
          name: presetName
          description: name of the preset file
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: string
    delete:
      summary: Delete a preset from a camera if exists
      parameters:
        - in: path
          name: presetName
          description: name of the preset file
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: string

components:
  schemas:
    presetList:
      type: object
      properties:
        presets:
          type: array
          items:
            type: string
          description: List of the presets on the camera
    postPresetResponse:
      type: object
      properties:
        presetAdded:
          type: string
          description: Name of the preset uploaded
    activePreset:
      type: object
      properties:
        preset:
          type: string

SystemControl.yaml

openapi: 3.0.1
info:
  title: System Control API
  description: API for controlling the System Modes on Blackmagic Design products.
  version: 1.0.0
servers:
- url: /control/api/v1
paths:
  /system:
    get:
      summary: Get device system information.
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SystemResponse'
        501:
          description: This functionality is not implemented for the device in use.
  /system/supportedCodecFormats:
    get:
      summary: Get the list of supported codecs.
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SupportedCodecFormats'
        501:
          description: This functionality is not implemented for the device in use.
  /system/codecFormat:
    get:
      summary: Get the currently selected codec.
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CodecFormat'
        501:
          description: This functionality is not implemented for the device in use.
    put:
      summary: Set the codec.
      requestBody:
        description: Update the system codec
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CodecFormat'
      responses:
        204:
          description: No Content
        501:
          description: This functionality is not implemented for the device in use.
  /system/videoFormat:
    get:
      summary: Get the currently selected video format.
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetVideoFormat'
        501:
          description: This functionality is not implemented for the device in use.
    put:
      summary: Set the video format.
      requestBody:
        description: Update the system video format
        content:
          application/json:
            schema:
                $ref: '#/components/schemas/VideoFormat'
      responses:
        204:
          description: No Content
        501:
          description: This functionality is not implemented for the device in use.
  /system/supportedVideoFormats:
    get:
      summary: Get the list of supported video formats for the current system state.
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SupportedVideoFormats'
        501:
          description: This functionality is not implemented for the device in use.
  /system/supportedFormats:
    get:
      summary: Get supported formats.
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SupportedFormats'
        501:
          description: This functionality is not implemented for the device in use.
  /system/format:
    get:
      summary: Get current format.
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Format'
        501:
          description: This functionality is not implemented for the device in use.
    put:
      summary: Set the format.
      requestBody:
        description: Update the system format
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Format'
      responses:
        204:
          description: No Content
        501:
          description: This functionality is not implemented for the device in use.
components:
  schemas:
    SystemResponse:
      type: object
      description: The properties will be populated only with the values that are supported/implemented by the device in use.
      properties:
        codecFormat:
          $ref: "#/components/schemas/CodecFormat"
        videoFormat:
          $ref: "#/components/schemas/GetVideoFormat"
    SupportedCodecFormats:
      type: object
      properties:
        codecs:
          type: array
          items:
            $ref: "#/components/schemas/CodecFormat"
    CodecFormat:
      type: object
      properties:
        codec:
          type: string
          description: Currently selected codec
          example: ProRes:HQ
        container:
          type: string
          description: Multimedia container format
          example: MOV
    SupportedVideoFormats:
      type: object
      properties:
        formats:
          type: array
          items:
            $ref: "#/components/schemas/VideoFormat"
    FrameRate:
      type: string
      example: "29.97"
      enum:
        - "23.98"
        - "24.00"
        - "24"
        - "25.00"
        - "25"
        - "29.97"
        - "30.00"
        - "30"
        - "47.95"
        - "48.00"
        - "48"
        - "50.00"
        - "50"
        - "59.94"
        - "60.00"
        - "60"
        - "119.88"
        - "120.00"
        - "120"
    VideoFormat:
      type: object
      properties:
        frameRate:
          $ref: "#/components/schemas/FrameRate"
          description: Frame rate
          example: "30"
        height:
          type: number
          description: Height dimension of video format
          example: 1920
        width:
          type: number
          description: Width dimension of video format
          example: 1080
        interlaced:
          type: boolean
          description: Is the display format interlaced?
          example: false
    GetVideoFormat:
      type: object
      properties:
        name:
          type: string  
          description: Video format serialised as a string
          example: 1920x1080p29.97
        frameRate:
          $ref: "#/components/schemas/FrameRate"
          description: Frame rate
          example: "29.97"
        height:
          type: number
          description: Height dimension of video format
          example: 1920
        width:
          type: number
          description: Width dimension of video format
          example: 1080
        interlaced:
          type: boolean
          description: Is the display format interlaced?
          example: false
    Format:
      type: object
      properties:
        codec:
          type: string
          description: Currently selected codec
          example: BRaw:8_1
        frameRate:
          $ref: "#/components/schemas/FrameRate"
          description: Frame rate
          example: "24"
        maxOffSpeedFrameRate:
          type: number
          example: 60
        minOffSpeedFrameRate:
          type: number
          example: 5
        offSpeedEnabled:
          type: boolean
          example: false
        offSpeedFrameRate:
          type: number
          example: 60
        recordResolution:
          $ref: '#/components/schemas/Resolution'
        sensorResolution:
          $ref: '#/components/schemas/Resolution'
    Resolution:
      type: object
      properties:
        height:
          type: number
          description: Height of the resolution
          example: 2160
        width:
          type: number
          description: Width of the resolution
          example: 3840
    SupportedFormats:
      type: object
      properties:
        supportedFormats:
          type: array
          items:
            $ref: '#/components/schemas/SupportedFormat'
    SupportedFormat:
      type: object
      properties:
        codecs:
          type: array
          items:
            type: string
            example: BRaw:Q0
        frameRates:
          type: array
          items:
            $ref: '#/components/schemas/FrameRate'
        maxOffSpeedFrameRate:
          type: number
          example: 60
        minOffSpeedFrameRate:
          type: number
          example: 5
        recordResolution:
          $ref: '#/components/schemas/Resolution'
        sensorResolution:
          $ref: '#/components/schemas/Resolution'

TimelineControl.yaml

openapi: 3.0.1
info:
  title: Timeline Control API
  description: API for controlling playback timeline.
  version: 1.0.0
servers:
- url: /control/api/v1
paths:
  /timelines/0:
    get:
      summary: Get the current playback timeline.
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Timeline'
    delete:
      summary: Clear the current playback timeline.
      responses:
        204:
          description: No Content
  /timelines/0/add:
    post:
      summary: Add a clip to the end of the timeline.
      requestBody:
        description: Clip information to add
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddClip'
      responses:
        204:
          description: No Content
components:
  schemas:
    Timeline:
      type: object
      properties:
        clips:
          type: array
          items:
            type: object
            properties:
              clipUniqueId:
                type: integer
                description: Unique ID used to identify this clip
                example: 1
              frameCount:
                type: integer
                description: Number of frames in this clip on the timeline
                example: 90000
    AddClip:
      oneOf:
        - type: object
          properties:
            clips:
              type: integer
              description: Unique ID used to identify this clip
              example: 1
        - type: object
          properties:
            clips:
              type: array
              items:
                type: integer
                description: Unique ID used to identify this clip
              example: [1, 2, 3]

TransportControl.yaml

openapi: 3.0.1
info:
  title: Transport Control API
  description: API for controlling Transport on Blackmagic Design products.
  version: 1.0.0
servers:
- url: /control/api/v1
paths:
  /transports/0:
    get:
      summary: Get device's basic transport status.
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransportResponse'
    put:
      summary: Set device's basic transport status.
      requestBody:
          description: Set the transport mode
          content:
            application/json:
              schema:
                type: object
                properties:
                  mode:
                    type: string
                    description: Transport mode.
                    enum:
                    - InputPreview
                    - Output
      responses:
        204:
          description: No Content
  /transports/0/stop:
    get:
      summary: Determine if transport is stopped.
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                description: True when transport mode is InputPreview or when in Output mode and speed is 0
                type: boolean
    put:
      summary: Stop transport.
      responses:
        204:
          description: No Content
  /transports/0/play:
    get:
      summary: Determine if transport is playing.
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                description: True when transport is in Output mode and speed is non-zero
                type: boolean
    put:
      summary: Start playing on transport.
      responses:
        204:
          description: No Content
  /transports/0/playback:
    get:
      summary: Get playback state.
      responses:
        200:
          description: OK
          content:
              application/json:
                schema:
                  $ref: '#/components/schemas/Playback'
    put:
      summary: Set playback state.
      requestBody:
        description: Update playback state
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Playback'
      responses:
        204:
          description: No Content
  /transports/0/record:
    get:
      summary: Get record state.
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetRecord'
    put:
      summary: Set record state.
      requestBody:
        description: Update record state
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Record'
      responses:
        204:
          description: No Content
  /transports/0/timecode:
    get:
      summary: Get device's timecode.
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Timecode'
  /transports/0/timecode/source:
    get:
      summary: Get timecode source selected on device
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TimecodeSource'

components:
  schemas:
    TransportResponse:
      type: object
      properties:
        mode:
          type: string
          description: Transport mode.
          enum:
          - InputPreview
          - InputRecord
          - Output
    Stopped:
      type: object
      description: True when transport mode is InputPreview or when in Output mode and speed is 0
      properties:
        stopped:
          type: boolean
    Playback:
      type: object
      properties:
        type:
          type: string
          enum:
          - Play
          - Jog
          - Shuttle
          - Var
        loop:
          type: boolean
          description: When true playback loops from the end of the timeline to the beginning of the timeline
        singleClip:
          type: boolean
          description: When true playback loops from the end of the current clip to the beginning of the current clip
        speed:
          type: number
          description: Playback Speed, 1.0 for normal forward playback
        position:
          type: integer
          description: Playback position on the timeline in units of video frames
    GetRecord:
      type: object
      properties:
        recording:
          type: boolean
          description: Is transport in Input Record mode
    Record:
      type: object
      properties:
        recording:
          type: boolean
          description: Is transport in Input Record mode
        clipName:
          type: string
          description: Used to set the requested clipName to record to, when specifying "recording" attribute to True
    Timecode:
      type: object
      properties:
        timecode:
          type: number
          description: The time of day timecode in units of binary-coded decimal (BCD).
        clip:
          type: number
          description: The position of the clip timecode in units of binary-coded decimal (BCD).
    TimecodeSource:
      type: object
      properties:
        timecode:
          type: string
          enum: [Timecode, Clip]

VideoControl.yaml

openapi: 3.0.1
info:
  title: Video Control API
  description: API For controlling the video on Blackmagic Design products
  version: 0.1.0
servers:
- url: /control/api/v1
paths:
  /video/iso:
    get:
      summary: Get current ISO
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  iso:
                    type: integer
                    description: Current ISO value
                    maximum: 2147483647
                    minimum: 0
    put:
      summary: Set current ISO
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                iso:
                  type: integer
                  description: ISO value to set
                  maximum: 2147483647
                  minimum: 0
      responses:
        200:
          description: OK
  /video/gain:
    get:
      summary: Get current gain value in decibels
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  gain:
                    type: integer
                    description: Current gain value in decibels
                    maximum: 128
                    minimum: -128
    put:
      summary: Set current gain value
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                gain:
                  type: integer
                  description: Gain value in decibels to set
                  maximum: 128
                  minimum: -128
      responses:
        200:
          description: OK
  /video/whiteBalance:
    get:
      summary: Get current white balance
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  whiteBalance:
                    type: integer
                    description: Current white balance
                    maximum: 10000
                    minimum: 2500
    put:
      summary: Set current white balance
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                whiteBalance:
                  type: integer
                  description: White balance to set
                  maximum: 10000
                  minimum: 2500
      responses:
        200:
          description: OK
  /video/whiteBalance/doAuto:
    put:
      summary: Set current white balance automatically
      responses:
        200:
          description: OK
  /video/whiteBalanceTint:
    get:
      summary: Get white balance tint
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  whiteBalanceTint:
                    type: integer
                    description: Current white balance tint
                    maximum: 50
                    minimum: -50
    put:
      summary: Set white balance tint
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                whiteBalanceTint:
                  type: integer
                  description: White balance tint to set
                  maximum: 50
                  minimum: -50
      responses:
        200:
          description: OK
  /video/ndFilter:
    get:
      summary: Get ND filter stop
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  stop:
                    type: number
                    description: Current filter power (fStop)
                    maximum: 15.0
                    minimum: 0.0
    put:
      summary: Set ND filter stop
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                stop:
                  type: number
                  description: Filter power (fStop) to set
                  maximum: 15.0
                  minimum: 0.0
      responses:
        200:
          description: OK
  /video/ndFilter/displayMode:
    get:
      summary: Get ND filter display mode on the camera
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  displayMode:
                    $ref: '#/components/schemas/ndFilterDisplayMode'
    put:
      summary: Set ND filter display mode on the camera
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                displayMode:
                  $ref: '#/components/schemas/ndFilterDisplayMode'
      responses:
        200:
          description: OK
  /video/shutter:
    get:
      summary: Get current shutter. Will return either shutter speed or shutter angle depending on shutter measurement in device settings
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  continuousShutterAutoExposure:
                    type: boolean
                    description: Is shutter controlled by auto exposure
                  shutterSpeed:
                    $ref: '#/components/schemas/shutterSpeed'
                  shutterAngle:
                    $ref: '#/components/schemas/shutterAngle'
    put:
      summary: Set current shutter
      requestBody:
        description: Only a single property needs to be selected. If more than one is provided, the order of priority is (shutterSpeed > shutterAngle)
        content:
          application/json:
            schema:
              type: object
              properties:
                shutterSpeed:
                  $ref: '#/components/schemas/shutterSpeed'
                shutterAngle:
                  $ref: '#/components/schemas/shutterAngle'
      responses:
        200:
          description: OK
  /video/autoExposure:
    get:
      summary: Get current auto exposure mode
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  mode:
                    $ref: '#/components/schemas/autoExposureMode'
    put:
      summary: Set auto exposure
      requestBody:
        description: Auto exposure mode to set
        content:
          application/json:
            schema:
              type: object
              properties:
                mode:
                  $ref: '#/components/schemas/autoExposureMode'
      responses:
        200:
          description: OK
components:
  schemas:
    shutterSpeed:
      type: integer
      description: Shutter speed value in fractions of a second (minimum is sensor frame rate)
      maximum: 50000
    shutterAngle:
      type: integer
      description: Shutter angle
      maximum: 36000
      minimum: 100
    autoExposureMode:
      type: object
      description: Auto exposure mode
      properties:
        mode:
          type: string
          enum: ["Off", "Continuous", "OneShot"]
        type:
          type: string
          enum: ["", "Iris", "Shutter", "Iris,Shutter", "Shutter,Iris"]
    ndFilterDisplayMode:
      type: string
      enum: ["Stop", "Number", "Fraction"]