openapi: 3.1.1
info:
  title: HangLooseConvolver Web API
  description: API for interacting with a HangLooseConvolver instance.
  version: 1.0.0

servers:
  - url: http://localhost:8081/api/v1
    description: Local server

paths:
  /is-standalone-app:
    get:
      summary: Queries if the server runs in a standalone app or a in a plugin in a host
      operationId: getIsStandaloneApp
      responses:
        "200":
          description: Success response
          content:
            application/json:
              schema:
                type: object
                properties:
                  isStandaloneApp:
                    type: boolean
                    description: true if the server is running in a standalone app, false for a hosted plugin
                required:
                  - isStandaloneApp
  /audio-device-type:
    put:
      summary: Allows changing the audio device type (e.g., Windows Audio to DirectSound)
      operationId: setAudioDeviceType
      tags:
        - Audio Settings
      requestBody:
        description: Name of the audio device type to use.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                audioDeviceTypeName:
                  type: string
                  description: Name of the audio device type to use.
              required:
                - audioDeviceTypeName
      responses:
        "200":
          description: Success response containing the audio settings after device type change.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AudioSettings"
        "400":
          description: Unknown audio device type supplied. Current audio settings are returned.
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: "#/components/schemas/ApiError"
                  - $ref: "#/components/schemas/AudioSettings"
        "500":
          description: Internal server error. No audio settings are returned.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
  /audio-settings:
    get:
      summary: Retrieves the current audio settings of the device.
      operationId: getAudioSettings
      tags:
        - Audio Settings
      responses:
        "200":
          description: Success response containing the current audio settings.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AudioSettings"
        "500":
          description: Internal server error. No audio settings are returned.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
    patch:
      summary: Updates the audio settings.
      operationId: setAudioSettings
      tags:
        - Audio Settings
      requestBody:
        description: New audio settings to be applied.
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Audio settings that can be set by the user
              properties:
                inputDeviceName:
                  type: string
                  description: Name of the audio input device to use.
                outputDeviceName:
                  type: string
                  description: Name of the audio output device to use.
                isInputMuted:
                  type: boolean
                  description: True, if audio input should be muted, false otherwise.
                sampleRate:
                  type: integer
                  format: int32
                  description: Sample rate in Hz to use.
                bufferSize:
                  type: integer
                  format: int32
                  description: Audio buffer size to use.
      responses:
        "200":
          description: Successful response containing the updated audio settings.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AudioSettings"
        "400":
          description: Invalid body or parameter combination supplied. The response contains the error message as well as current audio settings. If the input or output device was changed and the parameters together cannot be set, user can repeat the request seeing the new (partial) update to the settings.
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: "#/components/schemas/ApiError"
                  - $ref: "#/components/schemas/AudioSettings"
        "500":
          description: Internal server error. No audio settings are returned.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
  /filter/{filterId}/files:
    get:
      summary: Retrieves the filter loaded in the filterbank with the given ID.
      operationId: getLoadedFilter
      tags:
        - Filterbank Control
      parameters:
        - $ref: "#/components/parameters/FilterId"
      responses:
        "200":
          description: "Currently loaded filter file in the given filterbank"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LoadedFilter"
        "500":
          description: Server error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
    post:
      summary: Uploads filter file(s) to the filterbank with the given ID.
      operationId: loadFilter
      tags:
        - Filterbank Control
      parameters:
        - $ref: "#/components/parameters/FilterId"
      requestBody:
        description: Form data containing the filter files (.wav file, .zip file, or a combination of .cfg and .wav files).
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                "files[]":
                  type: array
                  items:
                    type: string
                    format: binary
                  description: The impulse response file to be used for the convolution filter.
              required:
                - "files[]"
      responses:
        "201":
          description: Filter files successfully uploaded.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LoadedFilterWithBypass"
        "400":
          description: Bad request; returned when the files are corrupted, have invalid sample rate, or one of files mentioned in the supplied .cfg file is missing.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        "403":
          description: Forbidden; returned when an impulse response is supplied although the product has not been activated with a license key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        "500":
          description: Server error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
  /audio-parameters:
    get:
      summary: Retrieves convolver's audio parameters.
      operationId: getAudioParameters
      tags:
        - Audio Parameters
      responses:
        "200":
          description: Current audio parameters.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AudioParameters"
        "500":
          description: Server error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
    put:
      summary: Sets convolver's audio parameters.
      operationId: setAudioParameters
      tags:
        - Audio Parameters
      requestBody:
        description: Audio parameters to set.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SettableAudioParameters"
      responses:
        "200":
          description: Settings successfully changed; current audio parameters are returned.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AudioParameters"
        "403":
          description: Forbidden; returned when audio parameters are set although the product has not been activated with a license key. Current audio parameters are returned.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ApiError"
                  - $ref: "#/components/schemas/AudioParameters"
        "500":
          description: Server error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"

  /filter/{filterId}/gain:
    get:
      summary: With the filter's id, retrieves its current gain.
      operationId: getFilterGainInfo
      tags:
        - Filterbank Control
      parameters:
        - $ref: "#/components/parameters/FilterId"
      responses:
        "200":
          description: Current filterbank gain information
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GainInfo"
        "400":
          description: Bad Request. The requested filter does not exist.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        "500":
          description: Server error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
    put:
      summary: Sets the selected filterbank's gain
      operationId: setGainByFilterId
      tags:
        - Filterbank Control
      parameters:
        - $ref: "#/components/parameters/FilterId"
      requestBody:
        description: Filterbank gain parameter to set.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Gain"
      responses:
        "200":
          description: Setting successfully changed; current filterbank gain info is returned.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GainInfo"
        "400":
          description: Bad Request; returned when the filter that is being updated does not have a filter loaded
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ApiError"
        "403":
          description: Forbidden; returned when filterbank gain is set although the product has not been activated with a license key. Current filterbank parameters are returned.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ApiError"
                  - $ref: "#/components/schemas/GainInfo"
        "500":
          description: Server error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
  /filter/{filterId}/select:
    put:
      summary: Selects the filter with the given index as current filter
      operationId: setSelectedFilterbank
      tags:
        - Filterbank Control
      parameters:
        - $ref: "#/components/parameters/FilterId"
      responses:
        "200":
          description: Filterbank successfully selected
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SelectedFilterbank"
        "400":
          description: Bad Request; returned when the filter that is being selected does not have a filter loaded
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ApiError"
                  - $ref: "#/components/schemas/SelectedFilterbank"
        "404":
          description: Not Found; returned when the filter that is being selected is non-existent.
        "403":
          description: Forbidden; returned when the product has not been activated with a license key.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ApiError"
  /license:
    get:
      summary: Retrieves license activation status. To use certain features of the app, the user needs to activate the product with a license key supplied at purchase.
      operationId: getProductRegistrationStatus
      tags:
        - License
      responses:
        "200":
          description: Successful response containing current license activation status.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LicenseInfo"
        "500":
          description: Internal server error. No license information is returned.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
    put:
      summary: Allows supplying the license key to register the product and unlock its entire functionality.
      operationId: registerProduct
      tags:
        - License
      requestBody:
        description: License key information to activate the product.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                licenseKey:
                  type: string
                  description: license key to activate the product
      responses:
        "200":
          description: License activation succeeded. Returned also when the product has already been registered.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LicenseInfo"
        "403":
          description: Forbidden; returned when the license key is incorrect and the product has not been activated before.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ApiError"
                  - $ref: "#/components/schemas/LicenseInfo"
        "500":
          description: Internal server error. No license information is returned.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
components:
  parameters:
    FilterId:
      name: filterId
      in: path
      required: true
      schema:
        type: integer
        minimum: 0
        maximum: 5
        description: "There are 6 filterbanks indexed from 0 to 5"
  schemas:
    ChannelInfo:
      type: object
      properties:
        name:
          type: string
          description: Name of the channel
        isActive:
          type: boolean
          description: Is this channel currently active?
      required:
        - name
        - isActive
    AudioSettings:
      type: object
      properties:
        deviceTypeName:
          type: string
          description: Name of the current audio device type (e.g., CoreAudio).
        inputDeviceName:
          type: string
          description: Name of the current audio input device.
        outputDeviceName:
          type: string
          description: Name of the current audio output device.
        sampleRate:
          type: integer
          format: int32
          description: Current audio sample rate in Hz.
        bufferSize:
          type: integer
          format: int32
          description: Current audio buffer size in samples.
        inputChannels:
          type: array
          description: Information on input channels.
          items:
            $ref: '#/components/schemas/ChannelInfo'
        outputChannels:
          type: array
          description: Information on output channels.
          items:
            $ref: '#/components/schemas/ChannelInfo'
        deviceTypeNames:
          type: array
          description: Names of available audio device types.
          items:
            type: string
        inputDeviceNames:
          type: array
          description: List of supported input device names.
          items:
            type: string
        outputDeviceNames:
          type: array
          description: List of supported output device names.
          items:
            type: string
        availableSampleRates:
          type: array
          description: List of supported audio sample rates in Hz.
          items:
            type: integer
            format: int32
        availableBufferSizes:
          type: array
          description: List of supported audio buffer sizes in samples.
          items:
            type: integer
            format: int32
      required:
        - deviceTypeName
        - inputDeviceName
        - outputDeviceName
        - sampleRate
        - bufferSize
        - inputChannels
        - outputChannels
        - deviceTypeNames
        - inputDeviceNames
        - outputDeviceNames
        - availableSampleRates
        - availableBufferSizes
    ApiError:
      type: object
      description: Basic structure for reporting errors when calling the REST API.
      properties:
        message:
          type: string
          description: Error message describing the problem.
      required:
        - message
    LicenseInfo:
      type: object
      description: Information on product registration status (i.e., license activation)
      properties:
        isLicenseActive:
          type: boolean
          description: true if the license is active, false otherwise
      required:
        - isLicenseActive
    SettableAudioParameters:
      type: object
      description: Representation of audio parameters settable by the user
      properties:
        isBypassed:
          type: boolean
          description: true, if the convolution filter is bypassed, false otherwise
        masterTrim:
          type: number
          format: double
          description: Master output trim (gain) level
      required:
        - isBypassed
        - masterTrim
    AudioParameters:
      allOf:
        - $ref: '#/components/schemas/SettableAudioParameters'
        - type: object
          description: Audio parameters representation
          properties:
            isBypassChangeEnabled:
              type: boolean
              description: >
                true, if the user is allowed to toggle bypass, false otherwise
                In some setups, bypass toggling is disabled, for example,
                when the license is not active or there is a multichannel filter loaded in one of the filterbanks
                (even if this filterbank is not selected).
            selectedFilterbank:
              $ref: '#/components/schemas/SelectedFilterbank'
          required:
            - isBypassChangeEnabled
            - selectedFilterbank
    Gain:
      type: object
      description: Filterbank's gain representation
      properties:
        gainDb:
          type: number
          format: double
          description: Selected filterbank's (gain) level
      required:
        - gainDb
    GainInfo:
      type: object
      description: Filterbank's gain information representation
      properties:
        gainDb:
          type: number
          format: double
          description: Selected filterbank's (gain) level
        minimumGainDb:
          type: number
          format: float
          description: Minimum allowed gain in decibels
        maximumGainDb:
          type: number
          format: float
          description: Minimum allowed gain in decibels
      required:
        - gainDb
        - maximumGainDb
        - minimumGainDb
    LoadedFilter:
      type: object
      description: "Information on the filter used by a filterbank"
      properties:
        loadedFilterFile:
          type: [string, "null"]
      required:
        - loadedFilterFile
    LoadedFilterWithBypass:
      allOf:
        - $ref: '#/components/schemas/LoadedFilter'
        - type: object
          description: See AudioParameters for an explanation
          properties:
            isBypassed:
              type: boolean
            isBypassChangeEnabled:
              type: boolean
          required:
            - isBypassed
            - isBypassChangeEnabled
    SelectedFilterbank:
      type: object
      description: Info on the currently selected filterbank.
      properties:
        selectedFilterbankIndex:
          type: integer
          format: int32
          description: index of currently selected filterbank
      required:
        - selectedFilterbankIndex